Agent Lifecycle Management

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• ROADMAP.md
• core/src/agent/README.md
• loom-py/src/loom/agent/README.md
• loom-py/src/loom/cli/README.md
• loom-py/src/loom/runtime/orchestrator.py
• loom-py/src/loom/runtime/README.md
• core/src/agent/directory.rs
• core/src/agent/runtime.rs

Agent Lifecycle Management is a core feature of the Loom runtime, responsible for the creation, continuous operation, monitoring, and termination of AI agents. Unlike library-based approaches where agents exist only for the duration of a script, Loom treats agents as long-running services. This is managed by the stable Rust Core, which acts as the "Hands" of the system, handling infrastructure tasks like agent lifecycle, while the Python agent code serves as the "Brain," focusing on fast-iterating logic and reasoning.

This system enables agents to run continuously, respond to real-world events, and collaborate across different processes, forming the foundation of Loom's event-driven, multi-agent architecture.

Sources: ROADMAP.md, ARCHITECTURE.md, README.md, core/src/agent/README.md

Architecture Overview

The lifecycle management architecture is split between the Python SDK and the Rust Core, following the "Brain/Hand" separation principle. The Python side initiates and orchestrates, while the Rust side provides the robust, secure runtime environment.

The following diagram illustrates the high-level interaction between these components.

This diagram shows the Python Orchestrator starting agent processes, which then connect via the gRPC Bridge to the AgentRuntime in Rust Core for formal registration and management.

Sources: ARCHITECTURE.md, loom-py/src/loom/runtime/orchestrator.py, core/src/agent/runtime.rs

Python SDK Orchestration

The lifecycle begins on the Python side, using the loom CLI and the Orchestrator module.

Sources: loom-py/src/loom/cli/README.md, loom-py/src/loom/runtime/README.md

CLI Commands

A set of CLI commands are provided to manage the full lifecycle of a Loom project, including the runtime and all associated agents.

Command	Description
loom up	Starts the Loom runtime (Core + Bridge + Dashboard). It automatically downloads pre-built binaries if not found locally.
loom run	Starts the runtime and then runs the project's agents, with auto-discovery of agent scripts.
loom down	Gracefully stops all Loom-related processes, including the runtime and any running agents.

These commands use the Orchestrator to manage processes.

Sources: loom-py/src/loom/cli/README.md, loom-py/README.md

Orchestrator

The Orchestrator class in loom-py/src/loom/runtime/orchestrator.py is the primary process manager on the Python side. When loom run is executed, the orchestrator performs these key functions:

1. Starts the Rust Runtime: It launches the loom-core and loom-bridge binaries as subprocesses. It can manage different modes, such as full (with dashboard) or bridge-only.
2. Manages Agent Processes: It discovers and starts the Python agent scripts (e.g., from an agents/ directory) as separate subprocesses.
3. Health and Shutdown: It monitors the health of these processes and handles graceful shutdown, sending SIGTERM and escalating to SIGKILL if necessary.

Sources: loom-py/src/loom/runtime/orchestrator.py, loom-py/src/loom/runtime/README.md

Python Agent Registration

Once a Python agent process is started by the Orchestrator, the loom.Agent class within that process takes over.

1. Connection: It establishes a gRPC stream to the Rust Bridge.
2. Registration: It sends a RegisterAgent request to the runtime, identifying itself with an agent_id and declaring the topics it subscribes to and the tools it provides.
3. Heartbeat: It maintains the connection by sending periodic heartbeats to the runtime, which allows the core to detect unresponsive agents.

Sources: loom-py/src/loom/agent/README.md

Rust Core Management

The Rust Core is the authoritative manager for all registered agents, ensuring stable and continuous operation.

Sources: core/src/agent/README.md, ARCHITECTURE.md

Core Components

The agent lifecycle in Rust is managed by a few key components.

Component	File	Description
AgentRuntime	runtime.rs	The central manager that creates, starts, and stops agents. It listens for registration requests from the Bridge and wires topic subscriptions to the Event Bus.
Agent	instance.rs	A running actor instance that owns its state, behavior, and an event mailbox. It runs an event loop to process incoming events.
AgentDirectory	directory.rs	A thread-safe registry of all active agents, their status, subscriptions, and capabilities. It's the source of truth for agent topology.
AgentBehavior	runtime.rs	A trait defining the business logic of an agent (on_event, on_init, on_shutdown). This is implemented by specific agent types.

The relationship between these components is shown below.

Agent State and Directory

The AgentDirectory tracks the state of each agent using the AgentInfo struct and AgentStatus enum.

AgentStatus Enum

Status	Description
Active	The agent is running and responsive.
Inactive	The agent is registered but not currently active.
Error	The agent has encountered an error.

AgentInfo Struct

Field	Description
agent_id	Unique identifier for the agent.
subscribed_topics	List of event topics the agent is subscribed to.
capabilities	List of tools or capabilities the agent provides.
last_heartbeat	Timestamp of the last received heartbeat.
status	The current AgentStatus of the agent.

Sources: core/src/agent/directory.rs

End-to-End Lifecycle Flow

The following sequence diagram shows the complete agent startup and registration process, from the user's command to the agent being active in the Rust runtime.

This flow demonstrates how the Python SDK and Rust Core collaborate to provide a managed lifecycle for each agent, enabling robust, long-running multi-agent systems.

Sources: loom-py/src/loom/cli/README.md, loom-py/src/loom/runtime/orchestrator.py, loom-py/src/loom/agent/README.md, core/src/agent/runtime.rs

Summary

Loom's Agent Lifecycle Management is a foundational pillar of its architecture, providing a robust runtime environment that distinguishes it from script-based agent libraries. By delegating lifecycle responsibilities to the Rust Core, Loom ensures that agents are treated as persistent, long-running services. This is orchestrated by the Python SDK, which simplifies development and deployment through high-level commands and classes. This dual-component architecture enables the creation of complex, resilient, and observable multi-agent systems capable of continuous operation and real-world event handling.

Sources: ROADMAP.md, ARCHITECTURE.md, README.md