Messages

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	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)

Pipecat Server

Pipecat Subagents

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Overview

Base Types

Common Fields

Frame Transport

BusFrameMessage

Agent Lifecycle

BusActivateAgentMessage

BusEndMessage / BusEndAgentMessage

BusCancelMessage / BusCancelAgentMessage

Registry & Errors

BusAgentRegistryMessage

BusAgentReadyMessage

BusAgentErrorMessage / BusAgentLocalErrorMessage

Task Messages

BusTaskRequestMessage

BusTaskResponseMessage / BusTaskResponseUrgentMessage

BusTaskUpdateMessage / BusTaskUpdateUrgentMessage

BusTaskCancelMessage

Task Streaming

BusTaskStreamStartMessage / BusTaskStreamDataMessage / BusTaskStreamEndMessage

​Overview

​Base Types

​Common Fields

​Frame Transport

​BusFrameMessage

​Agent Lifecycle

​BusActivateAgentMessage

​BusEndMessage / BusEndAgentMessage

​BusCancelMessage / BusCancelAgentMessage

​Registry & Errors

​BusAgentRegistryMessage

​BusAgentReadyMessage

​BusAgentErrorMessage / BusAgentLocalErrorMessage

​Task Messages

​BusTaskRequestMessage

​BusTaskResponseMessage / BusTaskResponseUrgentMessage

​BusTaskUpdateMessage / BusTaskUpdateUrgentMessage

​BusTaskCancelMessage

​Task Streaming

​BusTaskStreamStartMessage / BusTaskStreamDataMessage / BusTaskStreamEndMessage

Overview

Base Types

Common Fields

Frame Transport

BusFrameMessage

Agent Lifecycle

BusActivateAgentMessage

BusEndMessage / BusEndAgentMessage

BusCancelMessage / BusCancelAgentMessage

Registry & Errors

BusAgentRegistryMessage

BusAgentReadyMessage

BusAgentErrorMessage / BusAgentLocalErrorMessage

Task Messages

BusTaskRequestMessage

BusTaskResponseMessage / BusTaskResponseUrgentMessage

BusTaskUpdateMessage / BusTaskUpdateUrgentMessage

BusTaskCancelMessage

Task Streaming

BusTaskStreamStartMessage / BusTaskStreamDataMessage / BusTaskStreamEndMessage