> ## 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. # Messages > All bus message types for agent communication ## 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. ```python theme={null} 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`](/api-reference/pipecat-subagents/types#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) |