All chapters
  1. Start hereOne agent asks. Another answers. The rest is the contract between them
  2. Foundations · 1One model, one tool, two agents: who is who, and who is responsible
  3. Foundations · 2Message passing: sender, recipient, payload, address and correlation
  4. Foundations · 3Topologies: central orchestrator, peer-to-peer and hierarchy
  5. Mechanics · 4Request and reply, or a task: synchronous versus asynchronous exchange
  6. Mechanics · 5Contracts: messages, artifacts, typed schemas, errors and versions
  7. Mechanics · 6The task lifecycle: submitted, working, input-required, completed, failed, canceled
  8. Mechanics · 7Discovery: Agent Cards, skills and how an agent says what it can do
  9. Protocol · 8A2A: the Agent2Agent protocol, part by part
  10. Protocol · 9A2A versus MCP: delegating to an agent versus calling a tool
  11. Protocol · 10Handoff, delegation or shared state: three ways to work together
  12. Production · 11How updates arrive: streaming, push notifications, callbacks, polling and queues
  13. Production · 12Security: identity, delegated scopes, trust across domains, authorization
  14. Production · 13Reliability: retries, idempotency, order, timeouts and compensation
  15. Production · 14Observability: one trace across three agents
  16. Reference · 15Frameworks: A2A SDKs, LangGraph, AutoGen, CrewAI and plain code
  17. Reference · 16Advanced: consensus claims, coordination failure, cost and isolation
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
About

About this site and its sources

What this site is, what it is not, where its ideas come from, how the facts were checked, and the sister sites of the series.

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 isIt is not
A ladder: one idea per step, each word in plain English with a tiny example before it is usedA standard, or the only way to design agent communication
One running example, twelve cases UW-401 to UW-412, followed through every chapterA 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 togetherA 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 outputA 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 logA 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 exampleA 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.

PartStatus
The ladder of chapters, the question "what must both sides agree on?", and the order in which ideas are introducedOriginal to this site
The insurance example, its twelve cases, the three-agent split and the policy fixtureOriginal 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 namesA2A's, version 1.0.0. The table of allowed moves is this example's design
The Agent Cards of the exampleField names follow A2A's AgentCard; nested shapes are simplified and not validated against an official schema
Statements about A2A, MCP and librariesFrom their own documentation, read on 2026-11-17, logged claim by claim in docs/facts/ in the repository
DiagramsDrawn 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 outWhy it mattersWhere it is discussed
A real modelThe agents follow a script, so they cannot fail the way a model fails: wrong reasoning, drifting answers, persuasion by injected textActors, Advanced
A real networkOne process, one clock, fixed latency. No partial failures, no clock skew, no real connection dropsUpdates, Reliability
A real protocol on the wireThe bus carries Python dictionaries; neither A2A nor MCP is spokenA2A, A2A vs MCP
Real identityTokens have no signature and no expiry; there is no identity providerSecurity
Durable storageTasks and rows live in memory; a restart loses themTask lifecycle
Polling, streaming connections, push and queuesThe example pushes every update as a message; the delivery lab models the othersUpdates
Dead-letter queuesThe bus logs undeliverable and ignored messages but keeps no queueReliability

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.

SourceLink
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 featuresa2a-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.0a2a-protocol.org/latest/whats-new-v1
A2A project repositorygithub.com/a2aproject/A2A
Model Context Protocol specification (revision 2026-07-28)modelcontextprotocol.io/specification/latest · tools
W3C Trace Contextw3.org/TR/trace-context
Jakarta Messaging Message (pre-AI comparison)jakarta.ee Message API
Libraries described on FrameworksA2A 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.

SiteThe question it answers
Harness EngineeringWhat does the runtime around one model call have to do?
Prompt EngineeringHow are instructions written, composed, ranked and versioned?
Context EngineeringWhat can the model see now, and how is that working set chosen?
Memory EngineeringWhat lasts between runs, and how is execution state saved?
Agent Communication, this siteWhat must two agents agree on to exchange work safely?
Observability EngineeringWhat evidence shows what happened?
Guardrails EngineeringWhich enforceable checks surround a probabilistic agent?
Tools EngineeringHow is a callable capability designed and executed?
Structured Output EngineeringHow is typed output shaped, validated, repaired and evolved?
Agent OrchestrationWhat runs next, under which condition?
Agent ReliabilityHow does a system reach acceptable outcomes despite failure?
Eval EngineeringHow is behavior measured, and what may a number claim?
Diff to DeployHow 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.