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.
Overview
Bus messages are the communication primitives for the multi-agent framework. They are organized into two priority levels:
- Data messages (
BusDataMessage): Normal-priority messages for routine communication.
- System messages (
BusSystemMessage): High-priority messages that preempt normal messages in subscriber queues (e.g. cancel, errors).
Some messages also implement BusLocalMessage, meaning they stay on the local bus and are never forwarded to remote buses.
from pipecat_subagents.bus import (
BusActivateAgentMessage,
BusDeactivateAgentMessage,
BusEndMessage,
BusCancelMessage,
# ... etc
)
Base Types
| Type | Parent | Description |
|---|
BusMessage | - | Mixin carrying source and target metadata |
BusLocalMessage | - | Mixin: message stays on the local bus only |
BusDataMessage | BusMessage, DataFrame | Normal-priority bus message |
BusSystemMessage | BusMessage, SystemFrame | High-priority bus message |
Common Fields
All messages inherit these fields from BusDataMessage or BusSystemMessage:
| Field | Type | Default | Description | |
|---|
source | str | | Name of the agent or component that sent this message | |
target | `str | None` | None | Name of the intended recipient, or None for broadcast |
Frame Transport
| Type | Priority | Description |
|---|
BusFrameMessage | Data | Wraps a Pipecat Frame for transport over the bus |
BusFrameMessage
| Field | Type | Default | Description | |
|---|
source | str | | Sending agent name | |
target | `str | None` | None | Recipient agent name |
frame | Frame | | The Pipecat frame to transport | |
direction | FrameDirection | | Direction the frame should travel in the recipient’s pipeline | |
bridge | `str | None` | None | Bridge name for routing in multi-bridge setups |
Agent Lifecycle
| Type | Priority | Local | Description |
|---|
BusActivateAgentMessage | Data | No | Tells a targeted agent to become active |
BusDeactivateAgentMessage | Data | No | Tells a targeted agent to become inactive |
BusEndMessage | Data | No | Request a graceful end of the session |
BusEndAgentMessage | Data | No | Tells a targeted agent to end its pipeline |
BusCancelMessage | System | No | Request a hard cancel of the session |
BusCancelAgentMessage | System | No | Tells a targeted agent to cancel its pipeline |
BusActivateAgentMessage
| Field | Type | Default | Description | |
|---|
source | str | | Sending agent name | |
target | `str | None` | None | Agent to activate |
args | `dict | None` | None | Activation arguments forwarded to on_activated |
BusEndMessage / BusEndAgentMessage
| Field | Type | Default | Description | |
|---|
source | str | | Sending agent name | |
target | `str | None` | None | Recipient agent name |
reason | `str | None` | None | Human-readable reason for ending |
BusCancelMessage / BusCancelAgentMessage
| Field | Type | Default | Description | |
|---|
source | str | | Sending agent name | |
target | `str | None` | None | Recipient agent name |
reason | `str | None` | None | Human-readable reason for cancellation |
Registry & Errors
| Type | Priority | Local | Description |
|---|
BusAddAgentMessage | System | Yes | Request to add an agent to the local runner |
BusAgentRegistryMessage | System | No | Snapshot of agents managed by a runner |
BusAgentReadyMessage | Data | No | Announces that an agent is ready |
BusAgentErrorMessage | System | No | Reports an error from a root agent |
BusAgentLocalErrorMessage | System | Yes | Reports an error from a child agent to its parent |
BusAgentRegistryMessage
| Field | Type | Default | Description |
|---|
source | str | | Sending runner name |
runner | str | | Name of the runner that owns these agents |
agents | list[AgentRegistryEntry] | | List of agent entries with their state |
BusAgentReadyMessage
| Field | Type | Default | Description | |
|---|
source | str | | Agent name | |
runner | str | | Name of the runner managing this agent | |
parent | `str | None` | None | Name of the parent agent, or None for root agents |
active | bool | False | Whether the agent started active | |
bridged | bool | False | Whether the agent is bridged | |
started_at | `float | None` | None | Unix timestamp when the agent became ready |
BusAgentErrorMessage / BusAgentLocalErrorMessage
| Field | Type | Description |
|---|
source | str | Agent name |
error | str | Description of the error |
Task Messages
| Type | Priority | Description |
|---|
BusTaskRequestMessage | Data | Requests a task agent to start work |
BusTaskResponseMessage | Data | Response from a task agent |
BusTaskResponseUrgentMessage | System | High-priority response from a task agent |
BusTaskUpdateMessage | Data | Progress update from a task agent |
BusTaskUpdateUrgentMessage | System | High-priority progress update |
BusTaskUpdateRequestMessage | Data | Request a progress update from a task agent |
BusTaskCancelMessage | System | Cancel a running task |
BusTaskRequestMessage
| Field | Type | Default | Description | |
|---|
source | str | | Requester agent name | |
target | `str | None` | None | Worker agent name |
task_id | str | | Unique task identifier | |
task_name | `str | None` | None | Task name for routing to named handlers |
payload | `dict | None` | None | Structured data describing the work |
BusTaskResponseMessage / BusTaskResponseUrgentMessage
| Field | Type | Default | Description | |
|---|
source | str | | Worker agent name | |
target | `str | None` | None | Requester agent name |
task_id | str | | The task identifier | |
status | TaskStatus | | Completion status | |
response | `dict | None` | None | Result data |
BusTaskUpdateMessage / BusTaskUpdateUrgentMessage
| Field | Type | Default | Description | |
|---|
source | str | | Worker agent name | |
target | `str | None` | None | Requester agent name |
task_id | str | | The task identifier | |
update | `dict | None` | None | Progress data |
BusTaskCancelMessage
| Field | Type | Default | Description | |
|---|
source | str | | Requester agent name | |
target | `str | None` | None | Worker agent name |
task_id | str | | The task identifier | |
reason | `str | None` | None | Human-readable reason for cancellation |
Task Streaming
| Type | Priority | Description |
|---|
BusTaskStreamStartMessage | Data | Signals the start of a streaming task response |
BusTaskStreamDataMessage | Data | A chunk of streaming task data |
BusTaskStreamEndMessage | Data | Signals the end of a streaming task response |
BusTaskStreamStartMessage / BusTaskStreamDataMessage / BusTaskStreamEndMessage
| Field | Type | Default | Description | |
|---|
source | str | | Worker agent name | |
target | `str | None` | None | Requester agent name |
task_id | str | | The task identifier | |
data | `dict | None` | None | Stream metadata (start), chunk payload (data), or final metadata (end) |
