conversation

Conversation module for CrewMaster v2.0.0.

Provides two conversation modes:

• Dialogue 1:1: Human-to-agent dialogue with structured clarification (:func:dialogue).
• Sequential channel: Ordered agent dispatch with history accumulation and silence filtering (:func:channel_dispatch).

MODULE	DESCRIPTION
channel	Message, Role, and channel dispatch for conversation in CrewMaster v2.0.0.
channel_test	Tests for Message, Role models and channel dispatch.
dialogue	Dialogue 1:1 conversation mode for CrewMaster v2.0.0.
dialogue_test	Tests for the dialogue 1:1 conversation mode.

CLASS	DESCRIPTION
ChannelAgentMessage	An agent's response in a sequential channel.
Message	A single message in a conversation or channel history.
Role	Configuration for a participant in a conversation or channel.
Silent	An agent chose not to respond (empty response filtered out).
AgentOutputClarification	Agent requests additional information from the human.
DialogueAgentMessage	A regular text response from the agent during dialogue.
DialogueComplete	Terminal event indicating the dialogue has ended.

FUNCTION	DESCRIPTION
channel_dispatch	Dispatch a message through a sequential channel of agents.

__all__ module-attribute

__all__ = ['ChannelAgentMessage', 'Message', 'Role', 'Silent', 'channel_dispatch', 'AgentOutputClarification', 'DialogueAgentMessage', 'DialogueComplete', 'dialogue']

ChannelAgentMessage

An agent's response in a sequential channel.

ATTRIBUTE	DESCRIPTION
agent_name	The name of the agent who produced this response. TYPE: str
content	The text content of the agent's response. TYPE: str

agent_name instance-attribute

agent_name: str

content instance-attribute

content: str

Message

A single message in a conversation or channel history.

ATTRIBUTE	DESCRIPTION
role	The sender role ("user", "assistant", "system", "tool"). TYPE: Literal['user', 'assistant', 'system', 'tool']
content	The text content of the message. TYPE: str
timestamp	When the message was created (UTC). TYPE: datetime
metadata	Optional metadata dictionary for tool calls, etc. TYPE: dict[str, Any]

role class-attribute instance-attribute

role: Literal['user', 'assistant', 'system', 'tool'] = 'user'

content class-attribute instance-attribute

content: str = ''

timestamp class-attribute instance-attribute

timestamp: datetime = Field(default_factory=lambda: now(utc))

metadata class-attribute instance-attribute

metadata: dict[str, Any] = Field(default_factory=dict)

Role

Configuration for a participant in a conversation or channel.

Defines what context a participant consumes and which task blocks they use for their prompt assembly.

ATTRIBUTE	DESCRIPTION
name	Unique role name within the channel. TYPE: str
consumes	List of context types this role needs from upstream. TYPE: list[type[Any]]
task_blocks	List of blocks:// URIs for this role's task blocks. TYPE: list[str]

name instance-attribute

name: str

consumes class-attribute instance-attribute

consumes: list[type[Any]] = Field(default_factory=list)

task_blocks class-attribute instance-attribute

task_blocks: list[str] = Field(default_factory=list)

Silent

An agent chose not to respond (empty response filtered out).

ATTRIBUTE	DESCRIPTION
agent_name	The name of the agent who remained silent. TYPE: str

agent_name instance-attribute

agent_name: str

AgentOutputClarification

Agent requests additional information from the human.

This is a typed output, not an exception. The response_schema field describes the expected format for the human's response, and question contains the natural-language request.

ATTRIBUTE	DESCRIPTION
question	Natural-language question for the human. TYPE: str
response_schema	The expected response model type (e.g., a Pydantic model). TYPE: type[Any] | None

question instance-attribute

question: str

response_schema class-attribute instance-attribute

response_schema: type[Any] | None = Field(default=None)

model_config class-attribute instance-attribute

model_config = {'arbitrary_types_allowed': True}

DialogueAgentMessage

A regular text response from the agent during dialogue.

ATTRIBUTE	DESCRIPTION
content	The agent's text response. TYPE: str

content instance-attribute

content: str

DialogueComplete

Terminal event indicating the dialogue has ended.

ATTRIBUTE	DESCRIPTION
typed_output	The final structured output, if any. None if the dialogue ended with a clarification request. TYPE: Any

typed_output class-attribute instance-attribute

typed_output: Any = None

model_config class-attribute instance-attribute

model_config = {'arbitrary_types_allowed': True}

channel_dispatch async

channel_dispatch(message: str, agent_order: list[str], agents: dict[str, 'AgentConfig'], shared_context: Any = None, context_store: 'ContextStore | None' = None, runtime: 'RuntimeDriver | None' = None) -> AsyncIterator[ChannelAgentMessage | Silent]

Dispatch a message through a sequential channel of agents.

Agents are invoked in the order given by agent_order. Each agent sees the accumulated responses of all prior agents. Agents that return an empty response are reported as Silent.

CrewMaster does not rank agents — the application provides agent_order. Instructions like "only respond if you add value" belong in the application's prompt blocks, not in this function.

PARAMETER	DESCRIPTION
message	The initial message broadcast to all agents. TYPE: str
agent_order	Ordered list of agent names to iterate through. TYPE: list[str]
agents	Mapping of agent name to AgentConfig. TYPE: dict[str, 'AgentConfig']
shared_context	Arbitrary shared context available to all agents. TYPE: Any DEFAULT: None
context_store	Registry of domain objects for context projection. TYPE: 'ContextStore | None' DEFAULT: None
runtime	Runtime driver (falls back to agent.runtime). TYPE: 'RuntimeDriver | None' DEFAULT: None

YIELDS	DESCRIPTION
AsyncIterator[ChannelAgentMessage | Silent]	class:ChannelAgentMessage – an agent produced a response.
AsyncIterator[ChannelAgentMessage | Silent]	class:Silent – an agent returned an empty response.