> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentRunner

> Lifecycle orchestrator for multi-agent systems

## Overview

`AgentRunner` manages agent pipelines, coordinates startup and shutdown, and responds to bus messages. It owns the shared `AgentRegistry` and `AgentBus` for all agents in the system.

```python theme={null}
from pipecat_subagents.runner import AgentRunner
```

```python theme={null}
runner = AgentRunner()

agent = MyAgent("my_agent", bus=runner.bus, ...)
await runner.add_agent(agent)

await runner.run()
```

## Configuration

<ParamField path="name" type="str | None" default="None">
  Unique name for this runner. Defaults to a UUID-based name. Must be unique
  across all runners in a distributed setup.
</ParamField>

<ParamField path="bus" type="AgentBus | None" default="None">
  The [`AgentBus`](/api-reference/pipecat-subagents/bus#agentbus) instance.
  Creates an
  [`AsyncQueueBus`](/api-reference/pipecat-subagents/bus#asyncqueuebus) if not
  provided.
</ParamField>

<ParamField path="handle_sigint" type="bool" default="True">
  Whether to handle SIGINT for graceful shutdown.
</ParamField>

## Properties

### bus

```python theme={null}
runner.bus -> AgentBus
```

The bus instance for agent communication. Pass this to agents when creating them.

### registry

```python theme={null}
runner.registry -> AgentRegistry
```

The shared agent registry.

## Methods

### add\_agent

```python theme={null}
async def add_agent(self, agent: BaseAgent) -> None
```

Add an agent to this runner. Can be called before or after `run()`. When called after `run()` has started, the agent's pipeline task is created and started immediately.

| Parameter | Type                                                       | Description      |
| --------- | ---------------------------------------------------------- | ---------------- |
| `agent`   | [`BaseAgent`](/api-reference/pipecat-subagents/base-agent) | The agent to add |

### run

```python theme={null}
async def run(self) -> None
```

Start all agents and block until shutdown. Starts all registered agents, fires the `on_ready` event handler, then blocks until `end()` or `cancel()` is called. New agents can be added dynamically via `add_agent()` after `run()` has started.

### end

```python theme={null}
async def end(self, reason: str | None = None) -> None
```

Gracefully end all agents and shut down. Ends root agents first; parent agents propagate shutdown to their children automatically. Idempotent.

| Parameter | Type  | Default | Description |                                  |
| --------- | ----- | ------- | ----------- | -------------------------------- |
| `reason`  | \`str | None\`  | `None`      | Human-readable reason for ending |

### cancel

```python theme={null}
async def cancel(self, reason: str | None = None) -> None
```

Immediately cancel all agents and shut down. Cancels root agents first; parent agents propagate cancellation to their children automatically. Idempotent.

| Parameter | Type  | Default | Description |                                      |
| --------- | ----- | ------- | ----------- | ------------------------------------ |
| `reason`  | \`str | None\`  | `None`      | Human-readable reason for cancelling |

## Event Handlers

```python theme={null}
@runner.event_handler("on_ready")
async def on_ready():
    print("All agents started")

@runner.event_handler("on_error")
async def on_error(error: str):
    print(f"Runner error: {error}")
```

| Event      | Description                                         |
| ---------- | --------------------------------------------------- |
| `on_ready` | Fired after all registered agents have been started |
| `on_error` | Fired when the runner encounters an error           |