This is a knowledge site about messages between agents. It starts from one request and one result and climbs to topologies, task lifecycles, Agent Cards, the Agent2Agent (A2A) protocol, its boundary with the Model Context Protocol (MCP), security, reliability and tracing. At each step it asks one question: what must both sides agree on? It is written for engineers and architects who build systems in which more than one agent does the work.
One example runs through every page. An insurer receives a broker's request for a quote. An intake agent turns the email into a submission, an assessment agent collects the evidence, an underwriting agent writes a recommendation, and a human underwriter decides. The model recommends; a person decides.
What it is and is not#
| It is | It is not |
|---|---|
| A ladder: one idea per step, each word in plain English with a tiny example before it is used | A standard, or the only way to design agent communication |
One running example, twelve cases UW-401 to UW-412, followed through every chapter | A record of any real insurer. The cases, rules, fields, provider, agents and timings are invented |
| A demonstration of mechanism: how an envelope, a task, a card, a deadline and a trace fit together | A measurement of any model or product. No page reports how good a real system is |
| Code that was run: three scripted stand-in agents on an in-process message bus, standard-library Python, with real output | A framework to install. It is short so that it can be read whole, and it leaves things out |
| Standards and libraries described from their own documentation, read on the date in each fact log | A ranking or a buying guide. Nothing is called best, and no price is quoted |
| Interactive labs that run in the browser over data generated from the example | A simulator of real networks. Two labs (exchange and delivery) are arithmetic models and say so |
This is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but the cases, the rules, the fields, the provider, the agents' timings and every number are invented. The rules of the policy fixture are teaching rules, not insurance practice.
What is original here and what is not#
The concepts on this site are older than agents. Message envelopes, correlation ids, request/reply, task protocols, orchestration and choreography, idempotency keys, at-least-once delivery and distributed tracing come from decades of work on distributed systems and messaging. The A2A protocol and MCP are open standards written by others; this site describes them from their specifications and links them.
| Part | Status |
|---|---|
| The ladder of chapters, the question "what must both sides agree on?", and the order in which ideas are introduced | Original to this site |
| The insurance example, its twelve cases, the three-agent split and the policy fixture | Original and synthetic. The fixture and several case facts are shared with the sister sites of the series |
| The envelope of the example (thirteen fields around a payload) | This site's teaching design. It is not the A2A wire format; the A2A page maps it to A2A's names |
| The task state names | A2A's, version 1.0.0. The table of allowed moves is this example's design |
| The Agent Cards of the example | Field names follow A2A's AgentCard; nested shapes are simplified and not validated against an official schema |
| Statements about A2A, MCP and libraries | From their own documentation, read on 2026-11-17, logged claim by claim in docs/facts/ in the repository |
| Diagrams | Drawn for this site. No figure from a source is reproduced |
How the facts were checked#
Every statement about a protocol, a standard or a library comes from that project's own documentation, read on the day the page was written, and is logged in a fact log in the repository: the claim, the URL and the date. Where a page needed a fact that the documentation read did not state, the page says "the documentation read here does not say". Facts that surprised the writer (a deprecation, a version jump, a moved page) were fetched a second time by a different reader before publication.
Numbers come from the example. Each one was produced by running a command in a copy of the example and pasting the output; the commands are on the pages. All times are simulated milliseconds from the example's clock. The labs read data generated from the same example, and their logic is tested against the Python functions on every build.
What the example does not show#
| Leaves out | Why it matters | Where it is discussed |
|---|---|---|
| A real model | The agents follow a script, so they cannot fail the way a model fails: wrong reasoning, drifting answers, persuasion by injected text | Actors, Advanced |
| A real network | One process, one clock, fixed latency. No partial failures, no clock skew, no real connection drops | Updates, Reliability |
| A real protocol on the wire | The bus carries Python dictionaries; neither A2A nor MCP is spoken | A2A, A2A vs MCP |
| Real identity | Tokens have no signature and no expiry; there is no identity provider | Security |
| Durable storage | Tasks and rows live in memory; a restart loses them | Task lifecycle |
| Polling, streaming connections, push and queues | The example pushes every update as a message; the delivery lab models the others | Updates |
| Dead-letter queues | The bus logs undeliverable and ignored messages but keeps no queue | Reliability |
Sources and reading list#
Primary sources, read on 2026-11-17. Each page's fact log in the repository says which claim came from which page.
| Source | Link |
|---|---|
| A2A specification (version 1.0.0) | a2a-protocol.org/latest/specification |
| A2A topics: agent discovery, streaming and asynchronous operations, life of a task, A2A and MCP, enterprise features | a2a-protocol.org/latest/topics/agent-discovery · streaming-and-async · life-of-a-task · a2a-and-mcp · enterprise-ready |
| What's new in A2A version 1.0 | a2a-protocol.org/latest/whats-new-v1 |
| A2A project repository | github.com/a2aproject/A2A |
| Model Context Protocol specification (revision 2026-07-28) | modelcontextprotocol.io/specification/latest · tools |
| W3C Trace Context | w3.org/TR/trace-context |
Jakarta Messaging Message (pre-AI comparison) | jakarta.ee Message API |
| Libraries described on Frameworks | A2A Python SDK on PyPI · LangGraph · AutoGen · Microsoft Agent Framework · CrewAI |
Sister sites#
This site is one of a series. Each site takes one part of building with agents, and none repeats a chapter of another. At every seam the pages say what a concept is not and link the site that owns it.
| Site | The question it answers |
|---|---|
| Harness Engineering | What does the runtime around one model call have to do? |
| Prompt Engineering | How are instructions written, composed, ranked and versioned? |
| Context Engineering | What can the model see now, and how is that working set chosen? |
| Memory Engineering | What lasts between runs, and how is execution state saved? |
| Agent Communication, this site | What must two agents agree on to exchange work safely? |
| Observability Engineering | What evidence shows what happened? |
| Guardrails Engineering | Which enforceable checks surround a probabilistic agent? |
| Tools Engineering | How is a callable capability designed and executed? |
| Structured Output Engineering | How is typed output shaped, validated, repaired and evolved? |
| Agent Orchestration | What runs next, under which condition? |
| Agent Reliability | How does a system reach acceptable outcomes despite failure? |
| Eval Engineering | How is behavior measured, and what may a number claim? |
| Diff to Deploy | How does a change made with coding agents travel to production? |
Who wrote it#
Sam Muthu, an engineer and architect who builds agent systems and holds Anthropic's Claude Certified Architect credentials (Foundations and Professional). More of his work is at sammuthu.com.
The site is a working version. If a claim is wrong or out of date, the fix is to read the source again and correct the sentence. Every term the pages use is collected in the Glossary.