Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:Loom is an event-driven AI agent runtime designed for building long-lifecycle, collaborative, and observable agents. Unlike a library that is called by your code, Loom is a runtime that runs your agents, enabling them to operate continuously, respond to system-level events (like hotkeys or file changes), and communicate with each other across different processes. This approach is ideal for creating complex, multi-agent systems that integrate deeply with their environment.
The core architectural principle of Loom is the "Brain/Hand Separation," which isolates the fast-iterating LLM logic (the "Brain," typically in Python) from the stable, secure infrastructure and tool execution (the "Hands," in Rust). This separation allows for rapid development of agent reasoning while maintaining a robust and secure foundation.
Sources: README.md:7-12, ROADMAP.md:3-10
1. Installation
Loom is distributed as a Python package on PyPI, which includes the Python SDK and the command-line interface (CLI).
To install Loom, use pip:
pip install loom
The package requires Python 3.9+ and includes dependencies such as grpcio, pydantic, rich, and opentelemetry.
Sources: loom-py/README.md:14-18, loom-py/pyproject.toml:10, 20-35
2. Runtime Management
The Loom runtime consists of several components, including the Rust Core, the gRPC Bridge, and an optional Dashboard for observability. The loom CLI provides commands to manage the entire runtime lifecycle.
Starting the Runtime
The loom up command automatically downloads pre-built binaries (or uses local builds), caches them, and starts the runtime.
# Start the full runtime (Core + Bridge + Dashboard)
loom up
This command will display the Dashboard URL (e.g., http://localhost:3030) when running in full mode.
The following diagram illustrates the binary selection logic used by loom up.
This diagram shows the priority order for selecting the runtime binaries.
Sources: loom-py/README.md:37-51, loom-py/src/loom/runtime/README.md:44-48
Stopping the Runtime
To gracefully shut down all Loom-related processes, including the runtime and any running agents, use the loom down command.
# Stop all Loom processes
loom down
This command scans for all relevant processes, sends a SIGTERM signal for a graceful shutdown, and escalates to SIGKILL if they do not terminate within a 3-second timeout.
Sources: loom-py/README.md:53-59, loom-py/src/loom/cli/README.md:70-77
CLI Runtime Commands
The loom CLI offers several commands for managing the runtime and projects.
| Command | Description |
|---|---|
loom up | Starts the Loom runtime (Core, Bridge, Dashboard). |
loom down | Stops all running Loom processes, including agents. |
loom run | Runs a Loom project, automatically discovering and starting agents. |
loom chat | Starts an interactive terminal chat with a cognitive agent. |
loom init | Creates a new Loom project from a template. |
Sources: loom-py/src/loom/cli/README.md:14-25
3. Creating and Running Your First Agent
Agents are the core components that you build with the Loom Python SDK. They connect to the Loom runtime to send and receive events and execute tools.
Agent Code
Here is an example of a simple agent that defines a tool and echoes back any event it receives.
# my_agent.py
from loom import Agent, tool
@tool("web.search", description="Search the web for information")
def web_search(query: str) -> dict:
return {"query": query, "results": ["example.com"]}
async def on_event(ctx, topic, event):
# Echo payload back
await ctx.emit(topic, type="echo", payload=event.payload)
agent = Agent(
agent_id="py-agent-1",
topics=["topic.test"],
tools=[web_search],
address="127.0.0.1:50051", # Or set LOOM_BRIDGE_ADDR
)
if __name__ == "__main__":
agent.run()
Sources: loom-py/README.md:65-83
Running the Agent
With the Loom runtime already started via loom up, you can run your agent script in a separate terminal.
python my_agent.py
Alternatively, for multi-agent projects, you can use loom run, which automatically discovers and runs agent scripts (e.g., from an agents/ directory or a loom.toml file).
Sources: loom-py/README.md:85-87, loom-py/src/loom/cli/README.md:83-96
4. Interactive Chat
Loom includes a powerful interactive chat CLI for testing and debugging cognitive agents.
To start a chat session, run:
loom chat
This command starts a cognitive agent and provides a rich terminal interface for interaction. You can see the agent's thought process, tool calls, and final answers.
Chat Interaction Flow
The following sequence diagram shows how a user query is processed in a loom chat session.
Chat Commands
The chat interface supports several slash commands for controlling the session.
| Command | Description |
|---|---|
/help | Show available commands. |
/clear | Clear the conversation history. |
/verbose | Toggle the display of the agent's thinking steps. |
/stream | Toggle streaming mode for responses. |
/history | Show the conversation history. |
/status | Show the connection status. |
/quit | Exit the chat session. |
Sources: loom-py/README.md:99-106
5. Example: Multi-Agent System
Loom excels at building complex, multi-agent systems where specialized agents collaborate via an event bus. The market-analyst application is a demonstration of this capability.
The system consists of multiple agents, each with a specific role, that communicate asynchronously to analyze market data and make trading decisions.
Market Analyst Architecture
This diagram shows the event flow between agents in the Market Analyst system.
To run this example:
cd apps/market-analyst
loom run
This demonstrates how loom run can orchestrate a full multi-agent application defined in a loom.toml configuration file.
Sources: README.md:95-125, apps/market-analyst/README.md:15-22, 40-48
Summary
This guide provides the essential steps to get started with Loom. You have learned how to install the loom package, manage the Rust runtime using the CLI, create and run a simple Python agent, and interact with it via the loom chat interface. By following these steps, you can begin to explore Loom's powerful features for building event-driven, long-running AI agent systems. For more advanced use cases, refer to the example applications like the Market Analyst.