Agent-to-Agent Protocols
A shared envelope format that tells each agent who sent a message, what to do with it, and where the task stands, so handoffs keep their context.
Why Does This Exist?
You split the job across specialists. A researcher digs up facts, a writer turns them into prose, and a checker verifies names before anything ships. That team is what multi-agent systems describes: small agents with narrow jobs, passing work along.
The lazy wiring is to pipe raw text. Take whatever the researcher generated and paste it into the writer's prompt. You'll see it work twice. Then the writer has to guess: who sent this, what am I supposed to do, which draft does it continue, and are these numbers checked or just collected. None of that was written down, so every agent re-reads the whole thread, repeats questions, and sometimes redoes work someone already finished.
This page covers the agent-to-agent protocol: the envelope every message travels in and how the receiver reads it. The delegation moment itself lives in sub-agents and handoffs, and the separate standard for plugging agents into tools lives in Model Context Protocol.
Think of It Like This
The office memo
Plain text from a coworker is a sticky note on your keyboard that says 500. The memo version of the same number reads: To: you. From: Accounting. Subject: Q3 expenses. Action: approve by Friday. Step: 2 of 4. Same number, zero guessing.
An agent envelope maps the same way. From is the sender, To is the receiver, Subject plus Action is the intent, the body is the payload, and the stamp in the corner is the task state. Your writer agent reads it the way you read the memo: who it is from, what to do, and where things stand.
It stops where all paperwork stops. A perfect memo can't fix a vague body, a wrong address, or a forged signature. You still need clear payloads, correct routing, and a check that the sender is who the header claims.
How It Actually Works
Call one handoff message . It carries five fields: , the sender id, which is plainly which agent wrote it; , the receiver id, which agent must act next; , the intent, one word from a fixed list saying what kind of message this is; , the payload, the actual facts or text; and , the task state, the step counter plus a pointer to shared memory. The harness parses , checks it, and only then wakes . That check-before-wake order is the whole reliability gain, and it's what agent harness design implements.
The envelope
Every uses the same shape, validated the way structured outputs are validated: against a schema, not by hope. The fixed intent vocabulary stays small on purpose:
ASSIGN_TASK: start this subtask and report back.PROVIDE_INFO: here are facts you asked for, no action required.REPORT_ERROR: something failed, here is what and where.FINAL_RESULT: the work is done, here is the deliverable.
A small list matters. With four intents the receiver routes without guessing, and anything outside the list is rejected instead of misread.
How the receiver reads it
When receives , the harness runs four steps in order. First it parses the envelope and confirms the shape. Then it validates: must be in the allowlist, must be a known sender, and the step inside must fall within range. Third, it fetches the shared state through the pointer in instead of rereading the thread. Last, it builds 's prompt from the verified pieces: who sent this, what kind, where the task stands, and the payload. Then acts and emits the next with the step counter moved forward.
Worked example: a 160 token handoff
Suppose a realistic payload runs 120 tokens, and the header fields cost what they cost in this design: takes 8 tokens, takes 8, takes 6, and takes 18. These are assumed budgets for counting, stated so you can check the sums:
So each handoff carries 40 header tokens on a 120 token payload: one third of overhead, about 33 percent. The diagram draws exactly this message, from researcher to writer, intent ASSIGN_TASK, at step 2 of 4.
The pointer inside is where the saving hides. Suppose the full shared history is 1800 tokens and the task needs 4 handoffs. Forwarding everything every time resends:
Sending a 20 token pointer per handoff plus one 1800 token fetch costs:
You save 5320 tokens, close to three quarters of the naive cost. That's the trade, stated plainly: you pay about one third extra per message plus schema upkeep, and you buy handoffs that route without rereading history. Skip the protocol for a single agent or a fixed two-step chain, where a direct call is cheaper. Use it once three or more agents hand work back and forth.
This rests on two assumptions: the shared store answers when asked, and senders tell the truth about their state. When the store is stale, the receiver does competent work on an old step. When a header lies, routing follows the lie. Both failures look like good work on the wrong task, which is why validation runs before execution.
Code
The point of this snippet is the check, not the arithmetic. It builds the same envelope the diagram draws, rejects bad intents and out-of-range steps, and confirms the wire cost from the worked example.
from dataclasses import dataclass
ALLOWED_INTENTS = {"ASSIGN_TASK", "PROVIDE_INFO", "REPORT_ERROR", "FINAL_RESULT"}
@dataclassclass Envelope: sender: str receiver: str intent: str payload: str step: int steps: int
def build(sender: str, receiver: str, intent: str, payload: str, step: int, steps: int) -> Envelope: if intent not in ALLOWED_INTENTS: raise ValueError(f"unknown intent: {intent}") if not 1 <= step <= steps: raise ValueError("step out of range") return Envelope(sender, receiver, intent, payload, step, steps)
msg = build("researcher", "writer", "ASSIGN_TASK", "Paris is the capital. Population 2.1M.", 2, 4)print(f"{msg.sender} -> {msg.receiver} [{msg.intent}] step {msg.step}/{msg.steps}")# -> researcher -> writer [ASSIGN_TASK] step 2/4print(f"payload chars: {len(msg.payload)}")# -> payload chars: 38print(f"tokens per handoff: {8 + 8 + 6 + 18 + 120}")# -> tokens per handoff: 160The 38 characters are the short demo string doing its job. The 160 tokens use the assumed budgets from the worked example: a 40 token header plus a 120 token payload.
Watch Out For
Passing the full history in every envelope
The symptom is a bill and a slowdown that grow with every step. Each handoff gets longer because it carries the entire thread so far, and by step five or six the receiver spends most of its window rereading. Planning math like context budgeting falls apart because no step costs what you estimated.
Never forward full history. Send a short session pointer and the step number inside , keep the one shared copy in a store the harness owns, and cap to what this step needs. The worked example shows the prize: 1880 tokens with pointers against 7200 without.
Believing the intent label without checking
The symptom is confident work on the wrong job. A sloppy or forged ASSIGN_TASK tells the writer to publish a draft the researcher only meant as notes, or two agents assign tasks to each other and loop. Nothing crashes, so it reads as progress until someone checks the log. The failure catalog for this shape is agent failure modes.
Validate every intent. Allowlist the four intents and the known senders, schema-check each before waking , and reject anything outside the list with a clarification instead of a guess.
The Quick Version
- An agent-to-agent protocol is a typed envelope around each handoff: sender, receiver, intent, payload, and task state.
- Raw text piping works for two steps and rots after that, because the next agent cannot tell who sent what or what to do.
- A small fixed intent vocabulary of assign, inform, error, and final lets the harness route without guessing.
- A state pointer beats full history forwarding: 4 handoffs of an 1800 token history resend 7200 tokens, while pointers cost 80 plus one fetch.
- A single agent or a fixed two-step chain doesn't need this; three or more agents handing work back and forth does.