Agent Communication — Reference
See Execution transport is below team coordination for the shared visual model.
See Coordinator-mediated dispatch, observations and steering for the shared visual model.
See Decision inbox, ledger, memory and curation for the shared visual model.
This reference maps Agentweaver's shared-state, addressed-message, handoff, and execution transport surfaces. The existing diagrams describe coordinator handoffs and execution transport, not the addressed mailbox.
The original three agent communication channels to its concrete surfaces: MCP tools and HTTP API endpoints. For the conceptual model and the reasoning behind it, read the Agent Communication deep dive.
The three pre-existing channels are:
- Indirect / shared-state coordination — the decisions ledger and cross-agent memory (the team's shared brain).
- Coordinator-mediated handoffs — the WorkPlan / subtask DAG and child-run dispatch.
- Direct transport (A2A) — the worker↔sandbox-pod execution transport for a single agent turn.
Addressed messages are a separate, durable mailbox for one named teammate and one target run. They are neither decisions nor coordinator steering. REST POST /api/projects/{id}/agent-messages persists a send with recipient, target_run_id, content, idempotency_key, and optional reply_to_id, reference_kind, reference_id, or expires_at. An authenticated source run determines the sender; the client does not choose one. A repeated key from the same sender returns the original logical message; a conflicting payload is rejected. GET /api/projects/{id}/agent-messages and GET /{messageId} expose project-visible history and diagnostics. Native and MCP tools expose corresponding send, list and get operations. MCP writes require forwarded, valid run-capability headers; an operator's broker token alone cannot impersonate a run, and stdio mode without a run identity cannot send. A reply uses the original message ID and preserves its thread.
States are accepted, claimed, delivered, acknowledged, expired, and undeliverable. Recipient-run-bound POST /claim leases a message; POST /{messageId}/deliver needs the matching owner and fence; POST /{messageId}/acknowledge records receipt and can be repeated safely. Their MCP/native counterparts follow the same checks. A lease expiry allows reclaim after a crash, but callers must only claim and present messages at a safe turn boundary. No runtime turn-boundary injection or scheduled idle wake is connected yet. A manual claim is not proof that the model saw the content, and a delivered mark is only as reliable as the caller's presentation. Until that integration lands, use list/get to inspect messages and do not interpret accepted as delivered. There is no paid wake loop.
Human notifications surface activity to operators; they are not addressed messages or acknowledgment receipts. Backlog/work-plan references link existing tasks without moving them; the decision inbox is for knowledge proposals; steering redirects a coordinator; A2A only executes a single agent turn. The handoff diagram below continues to describe coordinator-owned task dispatch, not mailbox delivery.
Precision note. Channels 1 and 2 are how the team coordinates. Channel 3 is how a single agent turn is executed. A2A is not a way for two agents to chat. Do not map agent-to-agent coordination onto the A2A surfaces. The A2A turn surface is
RemoteAgentProxy → Authorization: Bearer {per-run token} → AgentHost message:stream; each AgentHost pod accepts only its own run's token.
Channel 1 — Shared-state coordination
Agents coordinate indirectly by reading the project's decisions and memory at turn start (and mid-run) and by writing proposals back into the decision inbox. The conceptual model is in the Memory & Decisions deep dive; the full tool catalog is in the MCP reference and the API reference. The surfaces below are the ones that constitute cross-agent communication.
Decision inbox — propose, list, promote, reject
The inbox is the durable drop-box in front of the canonical ledger. Agents submit proposals here; reviewers and the Scribe merge or reject them.
| MCP tool | API endpoint | Purpose |
|---|---|---|
decision_inbox_submit | POST /api/projects/{id}/decisions/inbox | Submit a decision or learning proposal (slug-keyed, idempotent) |
decision_inbox_list | GET /api/projects/{id}/decisions/inbox | List entries (?agent=, ?type=, ?status=; default pending) |
decision_inbox_merge | POST /api/projects/{id}/decisions/inbox/{entryId}/merge | Promote a pending entry into a canonical decision |
| (merge alias) | POST /api/projects/{id}/decisions/inbox/{entryId}/promote | Alias for merge/promote |
decision_inbox_reject | POST /api/projects/{id}/decisions/inbox/{entryId}/reject | Reject a pending entry (retained for audit) |
decision_inbox_submit parameters: project_id, agent_name, slug (unique, for idempotency), type (learning · pattern · update · architectural · scope · process · technical), title, content, optional rationale. Re-submitting the same agent_name + slug while still pending updates the entry in place; a different agent reusing the same slug is de-collided into a new entry. See the slug de-collision logic in the Memory & Decisions deep dive.
Decisions ledger — create, list, update
Promoted entries become canonical decisions. The coordinator and Scribe paths may also create decisions directly, and decisions can be superseded or archived.
| MCP tool | API endpoint | Purpose |
|---|---|---|
decision_create | POST /api/projects/{id}/decisions | Create a decision directly (coordinator / Scribe path) |
decision_list | GET /api/projects/{id}/decisions | List decisions (?type=, ?agent=) |
| (get one) | GET /api/projects/{id}/decisions/{decisionId} | Get a single decision |
decision_update | PUT /api/projects/{id}/decisions/{decisionId} | Update status/content; set superseded_by_id |
decision_update accepts status (active, superseded, archived), replacement content, and superseded_by_id.
Active, approved architectural and scope decisions are eligible for team-wide context compilation. They remain untrusted historical data, not executable prompt instructions. Coordinator children receive approved-decisions context without the full memory/session selection.
Cross-agent memory — record, list, get, search
memory_search queries across project agents. Search visibility is not prompt eligibility: another agent's learning or pattern must be high importance, approved, and tagged cross-team to enter context selection. Eligible records remain subject to the compiler's item/token budget.
| MCP tool | API endpoint | Purpose |
|---|---|---|
memory_record | POST /api/projects/{id}/agents/{name}/memory | Add a memory entry for an agent |
memory_list | GET /api/projects/{id}/agents/{name}/memory | List one agent's memories (?type=, ?importance=) |
memory_get | GET /api/projects/{id}/agents/{name}/memory/{memId} | Get a single memory entry |
memory_search | GET /api/projects/{id}/memory | Cross-agent search across the whole project (?type=, ?tags=) |
memory_record parameters: project_id, agent_name, type (learning · pattern · core_context · update), content, optional importance (low · medium · high) and comma-separated tags. memory_search parameters: project_id, optional type, optional tags (comma-separated, OR semantics) — and it returns entries from all agents.
GET /api/projects/{id}/memoryis the cross-agent search surface. It is the endpoint behindmemory_searchand the one place a caller reads the team's accumulated memory without naming a specific agent.
Curation — the Scribe and export
After a run, the Scribe lists pending inbox entries, merges low-risk learning / pattern / update entries, updates the session, and exports DB state to files. Architectural and scope entries are left for review. Export and import bridge the DB to the .squad/ and .agentweaver/context/ mirrors:
| API endpoint | Purpose |
|---|---|
POST /api/projects/{id}/memory/export | Export DB memory → .squad/ + .agentweaver/context/ |
POST /api/projects/{id}/memory/import | Import .squad/decisions/inbox/*.md → DB |
The Scribe's role and the four-layer context build are documented in the Memory reference.
Channel 2 — Coordinator-mediated handoffs
The coordinator decomposes a goal into a WorkPlan / subtask DAG, dispatches child runs, observes them, and steers them. Children report results up to the coordinator; they never message each other. These tools are thin proxies over the Coordinator endpoints — see the Coordinator reference, the MCP reference, and the API table in the API reference.
Start and intent
| MCP tool | API endpoint | Purpose |
|---|---|---|
coordinator_start | POST /api/projects/{id}/orchestrations | Start a coordinator orchestration from a plain-language goal |
coordinator_outcome_spec_get | GET /api/runs/{id}/outcome-spec | Read the persisted OutcomeSpec (intent contract) |
coordinator_outcome_spec_confirm | POST /api/runs/{id}/outcome-spec/confirm | Confirm the spec, resuming past the gate |
coordinator_outcome_spec_revise | POST /api/runs/{id}/outcome-spec/revise | Re-draft the spec from feedback |
Interactive defineOutcome waits for confirmation. direct skips that drafted-outcome gate, while launch Autopilot can confirm defineOutcome unattended; dispatch/review/merge boundaries remain.
Plan, children, and dispatch
| MCP tool | API endpoint | Purpose |
|---|---|---|
coordinator_work_plan_get | GET /api/runs/{id}/work-plan | The subtask DAG: subtasks (with assignedAgent, phase, isolation, status, childRunId) and dependencies edges |
coordinator_children_get | GET /api/runs/{id}/children | Dispatched child runs, each with subtaskId, childRunId, subtaskStatus, assignedAgent, childRunStatus, worktreeBranch |
orchestration_topology | GET /api/runs/{id}/work-plan + GET /api/runs/{id}/children | One-shot { coordinatorRunId, workPlan, children } snapshot |
Each child run carries a ParentRunId and a SubtaskId. Children stop at the assemble-ready boundary — they do not run review, merge, or Scribe; the coordinator assembles. The full dispatch and assembly model is in Coordinator Internals.
Steering — coordinator-mediated, not peer-to-peer
Steering is how an operator redirects in-flight work. It always goes through the coordinator, which relays to the targeted child — siblings never steer each other.
| MCP tool | API endpoint | Purpose |
|---|---|---|
coordinator_steer | POST /api/runs/{id}/steer | Send stop, redirect, amend, or a recovery directive. Omit target_child_run_id to broadcast. |
coordinator_steer accepts run_id, kind, instruction, and optional target_child_run_id. kind is stop, redirect, amend, or a recovery verb such as recover. instruction is required for redirect and amend. It is optional for stop and recovery directives. A stop cancels the targeted turn immediately. Other directives apply at the next turn boundary. Pause is not supported. Directive progress streams as coordinator.steering (pending → queued → relayed → applied).
Observing the topology
A coordinator run is an ordinary run, so there is no separate streaming tool — point run_watch at the coordinator run_id.
| MCP tool | API endpoint | Purpose |
|---|---|---|
run_watch | GET /api/runs/{id}/stream | Live stream; carries coordinator.work_plan, coordinator.topology, subtask.*, and coordinator.steering events |
The subtask.* family (subtask.dispatched, subtask.running, subtask.assemble_ready, subtask.completed, subtask.failed) is how results and status flow up to the coordinator view. Child clarifying questions and tool approvals are re-emitted on this stream and routed back to the originating child — never sideways. See Coordinator Internals.
Channel 3 — Direct transport (A2A)
A2A is a leaf-turn transport below team coordination. AgentHost exposes A2ATurnBridgeAgent through a purpose-routing runner for workflow execution or the Operator Assistant MCP loop. Its provider boundary may use a run-bound Copilot capability or BYOK; orchestration and checkpoint persistence stay outside the pod.
A2A has its own dedicated surfaces and is documented separately:
- A2A bridge deep dive — the conceptual transport model (worker tier, sandbox-pod AgentHost, remote agent proxy).
- A2A reference — the concrete transport endpoints and wiring.
- A2A turn and event transport — the rationale for A2A as the sole worker→AgentHost wire transport.
Because A2A operates below team coordination, none of the Channel 1 or Channel 2 surfaces change when a turn runs in a remote pod versus locally. The shared-state tools and coordinator tools are identical either way.
Channel-to-surface summary
| Concern | Channel | MCP tools | Key endpoints |
|---|---|---|---|
| Propose / promote boundaries | 1 | decision_inbox_submit, decision_inbox_list, decision_inbox_merge, decision_inbox_reject | /api/projects/{id}/decisions/inbox* |
| Canonical decisions | 1 | decision_create, decision_list, decision_update | /api/projects/{id}/decisions* |
| Cross-agent memory | 1 | memory_record, memory_list, memory_get, memory_search | /api/projects/{id}/agents/{name}/memory*, GET /api/projects/{id}/memory |
| Decompose & dispatch | 2 | coordinator_start, coordinator_work_plan_get, coordinator_children_get, orchestration_topology | /api/projects/{id}/orchestrations, /api/runs/{id}/work-plan, /api/runs/{id}/children |
| Steer & observe | 2 | coordinator_steer, run_watch | /api/runs/{id}/steer, /api/runs/{id}/stream |
| Execute one agent turn | 3 | see A2A reference | see A2A reference |
Related reading
- Agent Communication deep dive — the conceptual model and why indirect coordination beats direct chat.
- Agent Communication experience — what these surfaces look like to a user.
- Memory reference and Memory & Decisions deep dive.
- Coordinator reference, MCP reference, and API reference.
- A2A bridge deep dive and A2A reference.
Diagram details and constraints
| Element | Contract |
|---|---|
| title | Handoffs, not peer chat |
| subtitle | The Coordinator owns the dependency frontier and assembles child results. |
| group-title0 | Intent → execution contract |
| group-title1 | Children and assembly |
| Human goal | Human goal |
| Human goal | Define the desired outcome |
| Human goal | intent input |
| OutcomeSpec | OutcomeSpec |
| OutcomeSpec | Confirm before dispatch |
| OutcomeSpec | confirmation gate |
| WorkPlan DAG | WorkPlan DAG |
| WorkPlan DAG | Subtasks + dependencies |
| WorkPlan DAG | eligible frontier |
| Child run A | Child run A |
| Child run A | One assigned subtask |
| Child run A | isolated worktree |
| Child run B | Child run B |
| Child run B | Another eligible subtask |
| Collective assembly | Collective assembly |
| Collective assembly | Integrate settled work |
| Collective assembly | one reviewed integration |
| e1 | draft |
| e2 | confirm |
| e3 | dispatch A |
| e4 | dispatch B |
| e5 | result A |
| e6 | result B |
| assurance-title | DEPENDENCIES ARE CONTROL |
| assurance-line1 | A dependency edge is scheduling, not a conversation channel. |
| assurance-line2 | A2A transports one agent turn between worker and sandbox; it is not peer chat. |
| Human goal | Input |
| Human goal | Desired outcome |
| Human goal | Scope |
| Human goal | Human intent |
| Human goal | Gate |
| Human goal | Confirm or revise |
| Human goal | Owner |
| Human goal | Coordinator intake |
| OutcomeSpec | State |
| OutcomeSpec | Persisted contract |
| OutcomeSpec | Fields |
| OutcomeSpec | Scope / assumptions |
| OutcomeSpec | Human confirmation |
| OutcomeSpec | Next |
| OutcomeSpec | Workflow selection |
| WorkPlan DAG | Model |
| WorkPlan DAG | Subtasks + edges |
| WorkPlan DAG | Bounded assignee |
| WorkPlan DAG | Ready |
| WorkPlan DAG | Dependencies satisfied |
| WorkPlan DAG | Store |
| WorkPlan DAG | Persisted WorkPlan |
| Child run A | Binding |
| Child run A | ParentRunId / SubtaskId |
| Child run A | Files |
| Child run A | Per-child worktree |
| Child run A | Charter + decisions |
| Child run A | Output |
| Child run A | Result to parent |
| Child run B | Eligible frontier only |
| Child run B | Failure |
| Child run B | Blocks dependents |
| Child run B | Chat |
| Child run B | No sibling channel |
| Collective assembly | Settled child branches |
| Collective assembly | Action |
| Collective assembly | Integrate collective work |
| Collective assembly | Gates |
| Collective assembly | Configured checks |
| Collective assembly | Review |
| Collective assembly | One human decision |
| goal | Outcome, scope, assumptions; Coordinator drafts the contract |
| spec | Human confirms or revises; Persisted intent, not execution |
| plan | One owner per bounded subtask; Only satisfied dependencies run |
| a | Active decisions + charter; Result returned to Coordinator |
| b | Parallel only when eligible; No direct child-to-child chat |
| assembly | Child results flow upward; Failed / RAI child blocks dependents |
| notes | DEPENDENCIES ARE CONTROL; A dependency edge is scheduling, not a conversation channel.; A2A transports one agent turn between worker and sandbox; it is not peer chat. |
| groups | Intent → execution contract; Isolated work → collective assembly |
Diagram details and constraints
| Element | Contract |
|---|---|
| title | A2A remotes a leaf turn, not the graph |
| takeaway | Setup and task cross to AgentHost; assistant output and structured events return. |
| Workflow graph | Workflow graph |
| Workflow graph | Host owns gates/checkpoints |
| Workflow graph | Five factory-created leaf types |
| RemoteAgentProxy | RemoteAgentProxy |
| RemoteAgentProxy | Build setup DataContent |
| RemoteAgentProxy | Task TextContent in same message |
| AgentHost bridge | AgentHost bridge |
| AgentHost bridge | message:stream over HTTP+JSON |
| AgentHost bridge | Apply per-turn context |
| Caller event pipeline | Caller event pipeline |
| Caller event pipeline | Decoded structured events |
| Caller event pipeline | Durable state outside pod |
| Proxy stream decoder | Proxy stream decoder |
| Proxy stream decoder | Output + RunEventDataPart |
| Proxy stream decoder | Check definitive turn end |
| Leaf runtime | Leaf runtime |
| Leaf runtime | Execute provider/tool loop |
| Leaf runtime | Stream updates and events |
| arrow-1 | invoke |
| arrow-2 | send |
| arrow-3 | run |
| arrow-4 | stream |
| arrow-5 | append |
| note-0 | Claim/configure is a separate lifecycle, completed before this exchange. |
| note-1 | EOF alone is not successful completion; structured failures remain failures. |
| notes | Claim/configure is a separate lifecycle, completed before this exchange.; EOF alone is not successful completion; structured failures remain failures. |