Inter-Agent Communication

d:spatch implements an Inter-Agent Communication (IAC) protocol that supports structured message passing between agents. Communication is synchronous and relationship-based — agents can only talk to agents they have an explicit connection with.

Communication methods

talk_to

The primary communication primitive. An agent sends a message to another agent and blocks until a response is received. The target agent receives the message as a new prompt.

# Delegate a task to a sub-agent
result = await ctx.talk_to("coder", "Implement the user authentication module.")

# Continue a conversation
followup = await ctx.talk_to("coder", "Add unit tests for the auth module.", continue_conversation=True)

talk_to is one-to-one and synchronous — the calling agent waits until the target agent finishes processing and returns a response.

Supervisor-to-worker

Supervisors can always talk_to their sub-agents. This is the primary delegation mechanism — a supervisor breaks down a task, sends instructions to workers, and collects results.

Worker-to-supervisor

Workers can send messages back to their supervisor. This is typically used for status updates, partial results, or escalation when the worker encounters something outside its authority.

Peer communication

Agents listed in each other's peers array can talk_to each other directly, regardless of their position in the hierarchy. Peer communication is useful for lateral coordination — for example, a frontend agent asking a backend agent about API response shapes.

Available agents

An agent can discover who it can communicate with at runtime:

agents = ctx.available_agents
# Returns a list of agent names: supervisor, sub-agents, and peers

This list is determined by the agent's position in the hierarchy and its peers declaration in the workspace config.

Conversation continuity

By default, each talk_to call starts a fresh conversation with the target agent. To resume a previous conversation — preserving the full message history — pass continue_conversation=True:

# First message starts a new conversation
await ctx.talk_to("coder", "Set up the project structure.")

# Follow-up continues the same conversation
await ctx.talk_to("coder", "Now add the database models.", continue_conversation=True)

This is useful for multi-step tasks where the target agent needs context from earlier instructions.

How it works

When an agent calls talk_to, the message is routed through the d:spatch runtime:

1. The sender's message is packaged and delivered to the target agent.
2. The target agent processes the message as a new prompt (or continuation).
3. The target agent's response is returned to the sender.
4. The sender resumes execution with the response.

All communication happens within the workspace container. There is no network overhead — messages are routed in-process by the d:spatch runtime.

For details on how agents escalate decisions instead of delegating tasks, see Inquiry System.