Agent communication · from one request to the A2A protocol
One agent asks. Another answers. The rest is the contract between them.
Two agents that work together need what any two programs need: an address, a message, a way to match a reply to its request, and an agreement about what happens when the answer is late, wrong or never comes. This site starts from one request and one result and climbs, one idea at a time, to topologies, task lifecycles, Agent Cards, the Agent2Agent protocol, its boundary with the Model Context Protocol, security, reliability and tracing. At every step it asks one question: what must both sides agree on?
For engineers and architects who build systems where more than one agent does the work. One running example, and code that runs without a model, a network or an API key.
An email arrives at an insurer's submissions inbox. A broker wants a quote for an office building:
From: broker@brokerage.example
To: submissions@insurer.example
Subject: Quote request SUB-1004
Please quote property cover for a masonry office, built 2001, 20,000 sq ft, sprinklered. The owner says the roof was replaced 9 years ago. Wind zone C. No losses.
The insurer wants software to do the first pass on requests like this, so that its underwriters spend their time on the hard ones. An underwriter is the person at an insurer who decides whether to accept a risk. The software prepares a recommendation; the underwriter decides. The model recommends; a person decides.
The first version of that software was one agent. It read the email, called a roof-data service, searched the underwriting guidance, looked up similar past decisions, applied the rules and wrote a recommendation. It worked. Then the team split it in three, because three groups owned three different jobs: one group owned intake from brokers, one owned evidence and its sources, one owned the rules. On the day of the split, a question appeared that had never existed before. The evidence part now lives in a different program. The intake part sends it a request. The roof-data service is slow today, and the reply has not come back after twenty seconds. Is the request lost? Is the other agent still working? Should intake ask again, and if it does, will the evidence be collected twice?
Inside one program, none of these questions exist. A function call returns or throws. Between two programs, every one of them needs an answer that both sides agreed on in advance. That agreement is the subject of this site.
What agent-to-agent communication is#
An agent is a program that calls a language model in a loop and runs the tools the model asks for. For example, the program that reads the broker's email, asks the model which facts it contains, and calls a function to store them.
When two agents work on the same job, they need a way to pass work and results between them. They do it with messages. A message is one unit that one agent sends to another: a few fields that say who sent it, to whom and about what, plus the content itself. "Please collect the evidence for SUB-1004" is a message. "Here is the evidence, with an id for each fact" is another.
Agent communication is everything about those messages: their shape, how the sender finds the recipient, how a reply finds its request, what happens when the work takes ten minutes, when it needs a question answered, when it fails, or when the reply arrives twice. That is all this site covers. It does not cover how one agent works inside (that is the agent harness, the runtime around the model) or how a workflow decides what runs next.
Plain English. Two agents talking is two programs exchanging letters. Each letter has an address and a reference number. The reply quotes the reference number, so the sender knows which letter it answers. Most of the hard problems are about letters that arrive late, twice, out of order, or never.
Before AI. A backend engineer has seen all of this before: a REST call between two services, a message on a Kafka topic, a job submitted to a queue with a ticket number. Agents add three things. The callee decides how to do the work, so its path is not fixed. It may need minutes, not milliseconds. And it may come back with a question instead of an answer. The old patterns still apply; they apply to a less predictable partner.
The first primitive: one request, one result#
Strip every system on this site down and one exchange remains. One agent, the caller, sends a request. Another agent, the callee, does the work and sends back a result. The two messages are tied together by an id that the request carries and the reply repeats.
The lab below shows the real first request of case UW-403 from the example, and the first reply to it. Click the parts of the message. Then switch off the correlation id and see what the caller can no longer do.
| Part of the message | What it is for | Value in the UW-403 evidence request |
|---|---|---|
from, to | Sender and the recipient's address | coordinator → assessment-agent |
payload | The content the recipient works on | the submission SUB-1004 and the list of evidence needed |
message_id | Makes this one message unique | msg-0003 |
correlation_id | Ties every reply to this request | msg-0003 (a request's own id) |
run_id | Groups all messages of one execution of the workflow | run-7f3a |
deadline_ms | How long the caller waits for a final answer | 30000 (simulated) |
That one exchange is enough to build every topology on this site. Notice what it does not need: nobody in the middle. The caller and the callee talk directly. A coordinator that sends every request and receives every reply is a design choice, often a good one, and Topologies compares it with the alternatives on the same case. But the primitive is the pair, not the boss.
Common confusion. "Multi-agent" is often drawn as one big agent at the top with smaller agents below it. That picture is one topology. Two agents that ask each other for help, with nobody above them, are also a multi-agent system, and they face every problem on this site.
The example in one minute#
Every page uses the same example. The insurer, the broker, the cases, the rules and every number are synthetic: this is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but nothing here reports the quality of a real system or model.
Intake reads the email once and writes down the facts as one structured record, the submission. The scenario has 63 fields; the code carries ten. A recommendation is what the agents produce: approve, decline, request_info or escalate, with reasons and the ids of the rules it rests on. The underwriter reads it in the underwriter cockpit, a web app, and decides.
On this site the work is split across three agents and a person:
| Actor | Kind | What it owns |
|---|---|---|
| intake agent | agent | Turns the email into the submission, starts the run, talks to the broker |
| assessment agent | agent | Collects the evidence. It alone calls the read tools: roof assessment, guidance search, similar past decisions |
| underwriting agent | agent | Reads the evidence, runs the eligibility rules (plain code), writes the recommendation, escalates conflicts |
| underwriter | person | Decides, and the decision is recorded as human_decision |
The rules come from a small, illustrative rule set called the policy fixture, version 2026.2. One rule matters on this page: R-ROOF-03 says that when the roof age on the application and the roof age from the roof-data provider differ by more than 5 years, a senior underwriter must settle it. These are teaching rules, not insurance practice.
Here is the happy path of case UW-401 as a sequence: the intake agent asks, the assessment agent collects evidence with three tool calls and passes the artifact on, the underwriting agent recommends, and a person decides. This run uses the peer topology, with no agent in the middle.
Diagram: Case UW-401 in the peer topology: three agents and a person
Time runs down the page. The intake agent asks; the assessment agent collects the evidence with its tools and sends the artifact back and straight on; the underwriting agent writes a recommendation; the underwriter decides. The agents are scripted stand-ins and every time is simulated.
- Intake agent to Assessment agent: Collect the evidence for SUB-1002. A request whose message_id, msg-0001, becomes the correlation_id of every answer.
- Assessment agent to Intake agent: working, task-a1. The callee accepts the work and gives it a task id. The caller now holds an id, not yet a result.
- Assessment agent: Three tool calls. Roof assessment, guidance search, similar decisions: functions that answer, not agents that are asked.
- Assessment agent to Intake agent: Evidence artifact art-a1. The result of the task: a structured, versioned artifact with an id for every piece of evidence.
- Assessment agent to Underwriting agent: Recommend on SUB-1002. In the peer topology the artifact goes straight on; no agent sits in the middle.
- Underwriting agent: Rules, then store one row. check_eligibility is plain code; record_recommendation stores one row under an idempotency key.
- Underwriting agent to Underwriter (a person): approve, for review. The recommendation appears in the underwriter cockpit. In this case the decision is still open.
The agents are scripted stand-ins: no model is called, no key is needed, and time is a simulated clock. So every result on this site shows how a mechanism works, not how good any model is. The twelve cases have their own ids, UW-401 to UW-412; several reuse the facts of the shared series cases on eval.sammuthu.com.
An executable demonstration#
The example lives in examples/uw-agents/ in the repository: about 1,800 lines of standard-library Python. The runner prints every message of a case. This is case UW-401, the happy path, in the default orchestrator topology (a coordinator in the middle):
cd examples/uw-agents
/opt/homebrew/bin/python3 run_case.py --case UW-401 --dry-run
UW-401 · topology orchestrator · run run-2c41 · agents: scripted stand-ins (no model called)
time ms from to type state ids
50 intake-agent → coordinator task.request - msg-0001 corr msg-0001 task - try 1
70 coordinator → intake-agent task.status working msg-0002 corr msg-0001 task task-c1 try 1
70 coordinator → assessment-agent task.request - msg-0003 corr msg-0003 task - try 1
90 assessment-agent → coordinator task.status working msg-0004 corr msg-0003 task task-a1 try 1
660 assessment-agent → coordinator task.artifact completed msg-0005 corr msg-0003 task task-a1 try 1
680 coordinator → underwriting-agent task.request - msg-0006 corr msg-0006 task - try 1
700 underwriting-agent → coordinator task.status working msg-0007 corr msg-0006 task task-u1 try 1
746 underwriting-agent → coordinator task.artifact completed msg-0008 corr msg-0006 task task-u1 try 1
766 coordinator → intake-agent task.artifact completed msg-0009 corr msg-0001 task task-c1 try 1
messages: 9 sent · 9 delivered · 0 duplicates dropped · 0 stale updates ignored · 0 deadlines fired
tasks (caller's view): workflow completed · evidence completed · recommendation completed
recommendation: approve · citations - · missing - · evidence complete · routed to the underwriter · stated_confidence 0.9
tool calls: get_roof_assessment 1 · search_guidance 1 · find_similar_decisions 1 · check_eligibility 1 · record_recommendation 1
rows stored: 1 · human_decision: none (no person has decided yet)
trace: 1 trace_id · 29 spans · last message at 786 ms · run ends at 786 ms (simulated)
expected vs actual: PASS (9 of 9 checks)
Read one line at a time and the whole subject is already there. Each request (task.request) gets a task.status of working and later a task.artifact. Every reply carries the corr of its request. The callee gives each piece of work a task id. The run ends with one stored row and no human decision, because no person has decided yet. Nine messages, three exchanges, one run.
Where this fits#
This site is one of a series. Each site owns one part of building with agents and links the others at the seams instead of repeating them. The graphic shows the series; this site is marked.
Diagram: Where this fits · thirteen guides, one system
Read left to right: what happens inside one agent, what happens between agents and over time, and how the whole is checked and shipped. This site, agent communication, sits in the middle lane: the messages between agents. Its neighbors decide what runs next (orchestration) and how the whole recovers from failure (reliability).
- Inside one agent
- Harness: The loop, the tool dispatch and the limits around one agent. Owned by harness.sammuthu.com.
- Prompt: How instructions are written, composed, ranked and versioned. Owned by prompt.sammuthu.com.
- Context: Selection, retrieval, budget and compaction of the working set. Owned by context.sammuthu.com.
- Memory: Durable information and saved execution state. Owned by memory.sammuthu.com.
- Tools: Tool schemas, execution and MCP tools. Owned by tools.sammuthu.com.
- Structured output: Shape, validation, repair and evolution of typed output. Owned by schema.sammuthu.com.
- Between agents
- Agent communication: Messages between agents: envelopes, correlation, tasks, Agent Cards, the A2A protocol and its boundary with MCP.
- Orchestration: The control plane: scheduling, conditions and the state of the workflow. Owned by orchestrate.sammuthu.com.
- Reliability: Retries, load, fallbacks and budgets as a discipline. Owned by reliable.sammuthu.com.
- Checking and shipping
- Guardrails: Checks around a probabilistic agent. Owned by guardrails.sammuthu.com.
- Observability: Logs, metrics, traces, audit events and replay. Owned by observe.sammuthu.com.
- Evals: Graders, golden sets, judges, trials and release gates. Owned by eval.sammuthu.com.
- Diff to deploy: Hooks, review lanes and CI for changes made with coding agents. Owned by diff-to-deploy.sammuthu.com.
What this is not. This site is about the messages between agents. Deciding what runs next, under which condition, in which order, is orchestration, and it belongs to orchestrate.sammuthu.com. Designing a callable capability for one agent, including MCP tool design, belongs to tools.sammuthu.com. This site uses both and explains neither in depth.
How to read this site#
The chapters build on each other. Each one opens with a moment from the example where its problem bites, then the plain idea, the smallest mechanism, the code, a failure, how the A2A protocol or a library does it, a checklist, and a folded layer for experts. You can stop at any chapter and keep what you learned.
| Part | Chapters | The question |
|---|---|---|
| Foundations | Actors, Messages, Topologies | Who talks to whom, with what, through which routes? |
| Mechanics | Sync and async, Contracts, Task lifecycle, Discovery | What must both sides agree on before and during the work? |
| Protocol | A2A, A2A vs MCP, Handoffs | How does a standard write those agreements down, and where does it stop? |
| Production | Updates, Security, Reliability, Tracing | What changes when messages are late, hostile, duplicated, or have to be explained later? |
| Reference | Frameworks, Advanced, Glossary, About | Which tools carry this for you, and how do groups of agents fail together? |
The same idea for a coding agent. The pattern is not specific to insurance. A planning agent works in a repository under its repository instructions. It asks a test agent to run the test suite and report the failures, and a review agent to review a pull request. Each of those requests is a message with an address, an id, a deadline and a result; each callee may take minutes or ask a question back. CI, the judge of the change, is not an agent at all. The runtime around one of those agents is the subject of harness.sammuthu.com; shipping the change belongs to diff-to-deploy.sammuthu.com.
Why split an agent at allThe split buys ownership and isolation, and pays in messages
Every split adds the costs of this site: an envelope to design, ids to keep apart, deadlines, retries, a trace that must cross a boundary, and a security check at each hop. A single agent with more tools avoids all of them. So the burden of proof is on the split.
Good reasons are organizational and operational more than technical. Different teams own the parts and release them on different schedules. One part needs credentials the others must never hold (in the example only the assessment agent reaches the roof-data provider). One part must be replaceable by another vendor's agent. One part runs for minutes while the others answer in milliseconds, and should fail without taking the others down. Weak reasons are about the model: "the prompt got long" is usually a context problem, and splitting turns it into a communication problem with more failure modes.
A useful design-review question: if the two agents were two microservices owned by two teams, would you still draw the line there? If the answer is no, the split is probably buying less than it costs. Actors works through this on the example.
Why the pair, and not the orchestrator, is the primitiveTopologies are compositions of the same exchange
A central orchestrator, a peer chain and a hierarchy are all built from the same request and reply. What differs is who holds the correlation table, who sets the deadlines and who sees which payload. In the example the three topologies send 9, 6 and 15 messages for the same case and end with the same recommendation; only the routing differs.
Teaching the orchestrator first hides that. It also suggests that cross-agent concerns (deadlines, idempotency, trace context) are the orchestrator's job. They are properties of every exchange. A peer chain with no deadline on its first hop hangs exactly as an orchestrator would. Getting the pair right makes every topology above it correct by composition; getting only the orchestrator right leaves every direct exchange unprotected.
In one breath#
Two agents that work together are two programs that exchange messages. The smallest unit is one request and one result, tied by an id the reply repeats. An orchestrator in the middle is one way to arrange those exchanges, not a requirement. Everything harder, from long-running tasks to retries and tracing, is an agreement both sides make about that exchange before the first message is sent.
Next: before we can design messages, we need to be exact about who is sending them. Actors separates the model, the tool and the agent, and shows what changes when the thing you call is another agent that can think, wait, ask back or refuse.