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.

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)