Handbooks  /  A2A Agent Interop
Handbook~15 min readAgentsworked math + runnable code
The A2A Agent Interop Handbook

Agents that
call agents.

One team builds a research agent; another builds a coding agent; a third wants to combine them. Today that means bespoke glue for every pairing — a brittle integration written by hand. Agent-to-agent interop replaces the glue with a protocol: agents advertise what they can do so others can find them, and speak a shared format so one's output slots into another's input. It's the same move that turned isolated services into the web. Get the two agreements right — discovery and schema — and independent agents compose into an ecosystem. Here's how the handshake works.

01

From glue to protocol

As agents proliferate, the interesting systems are ones where agents use other agents — a coordinator delegating a sub-task to a specialist built by someone else. But if every pair of agents needs custom integration code, the effort grows with the number of pairs (the same quadratic wall that bites multi-agent systems), and nothing composes. The web solved this exact problem for services with shared protocols; A2A interop is the analogous move for agents.

The idea is to replace bespoke glue with two standard agreements. First, agents must be findable: each publishes what it can do, so another agent can discover a suitable partner without prior knowledge of it. Second, agents must be speakable-to: they share a message format, so one agent's output can be consumed directly by another. Discovery answers "who can do this?"; the shared schema answers "how do I talk to them?". Both are required — a capable agent you can't communicate with is as useless as a reachable one that can't do the task.

The one-sentence version

A2A interop needs two agreements — agents advertise capabilities so others can discover and route to them, and share a message schema so one agent's output chains into another's input.

02

Advertise and discover

The first half is capability discovery. Each agent publishes a capability card — a machine-readable description of its skills: what tasks it handles, what inputs it needs, what it returns. To delegate a task, a coordinator looks up the registry of cards, finds agents whose advertised skills include the required capability, and routes the task to one of them.

Discover, match, route
AdvertiseEach agent publishes a capability card — its skills and I/O.
MatchA task's required capability is looked up against advertised skills.
RouteSend the task to an agent that lists that capability.
No matchIf no agent advertises it, there's nowhere to route — fail explicitly.

The rule is crisp: an agent can handle a task if and only if the required capability appears in its advertised skills. So discovery is a lookup — scan the registry for agents that list the capability, and route to a capable one (or report that none exists). This decouples the caller from the callee: the coordinator doesn't need to know which agents exist ahead of time, only what capability it needs; new agents can join the registry and become usable without changing the caller. But finding the right agent is only half the handshake — you still have to be able to talk to it.

03

Speak the same language

The second half is a shared message schema. Discovery finds a capable agent, but delegation still fails if the two agents can't understand each other's messages. If agent A emits results in one format and agent B expects another, A's output can't feed B's input — the capability match is wasted. So A2A protocols standardize the message envelope: an agreed structure for requests, results, streaming updates, and errors.

With a shared schema, one agent's output is directly consumable as another's input, so tasks can chain across agents — research agent produces a report in the standard format, coding agent consumes it, and so on. This is the same discipline as structured outputs applied at the agent boundary: agree on the shape so machines can hand work to each other without a translator. The interop condition is simple and unforgiving — two agents can chain only if their schemas line up. Mismatch the versions or the format and the pipeline breaks even when every capability is present.

04

The interop rules

Capability discovery is set membership. An agent with advertised skills S can handle a task requiring capability c exactly when c ∈ S; discovery collects all such agents from the registry:

can_handle(S, c) = [ c ∈ S ]     discover(registry, c) = { a : c ∈ Sa }

Routing picks a member of that set; if it's empty, there's no agent for the task — fail explicitly rather than guessing.

But delegation succeeds only if both conditions hold — a capable partner and a compatible schema:

delegable(A→B)  =  ( c ∈ SB )  AND  ( schemaA.out = schemaB.in )

Capability without a shared schema can't chain; a shared schema without the capability has nothing to do. Both are necessary. The runnable version below discovers capable agents, routes a task, and checks schema compatibility.

RUN IT YOURSELF

Discover, route, chain

A2A interop is two lookups. Discovery scans a registry of capability cards and returns every agent whose advertised skills include the required capability; routing picks one, or reports none exists. That decouples the caller from the callee — it names a capability, not a specific agent. But delegation also needs a shared message schema: two agents can chain their output-to-input only if their schemas match, so a capability match with mismatched formats still fails. Change the registry, the required capability, or the schemas and watch routing and compatibility decide.

CPython · WebAssembly
05

The A2A stack

A working A2A protocol standardizes a handful of things so heterogeneous agents compose:

ElementWhat it standardizes
Capability cardHow an agent advertises its skills, inputs, and outputs so others can discover it.
Message envelopeThe shared schema for requests, results, streaming updates, and errors.
Task lifecycleHow a delegated task is created, tracked, streamed, and completed or cancelled.
Identity & authHow agents authenticate each other and authorize a delegation — trust across boundaries.
Discovery mechanismHow agents publish and find cards (a registry, a well-known endpoint).

A2A sits alongside MCP in the protocol picture: MCP standardizes the agent-to-tool interface (how an agent reaches a database or API), while A2A standardizes the agent-to-agent interface (how an agent delegates to a peer). An agent might use MCP to call a tool and A2A to hand a sub-task to another agent. Both share one philosophy — agree on discovery plus a message schema so independently-built components compose without custom glue. And the trust dimension is real: delegating to an agent you didn't build means authenticating it and bounding what it can do, so identity and authorization are first-class, not afterthoughts.

06

Pitfalls

The interop-specific trap is schema drift: two agents that once chained stop working when one updates its message format, silently. Version the schema and negotiate versions at connect time, so a mismatch is a clear error, not a corrupted payload. A close cousin is capability lies: an agent advertises a skill it does poorly (or maliciously), and discovery routes to it in good faith — so advertised capability is a claim to be verified, not trusted, with evals and reputation, not just the card.

Two more. Trust across boundaries: delegating to a third-party agent means its output flows back into your system and possibly your model's context — treat it as untrusted, authenticate the peer, and bound what a delegation can do (an agent you didn't build is a guardrail and sandbox concern). And over-federating: not every system needs an agent mesh — the coordination cost of many agents still applies, so reach for A2A when you genuinely want independently-built agents to compose, not to over-engineer a task one agent could do. Used where it fits, A2A turns a pile of bespoke integrations into an open ecosystem — the difference between wiring two agents together and letting any agent find and use any other.

Worth knowing

An advertised capability is a claim, not a guarantee — discovery routes on trust, so verify partners with evals and reputation, version schemas so drift is a clear error, and treat a third-party agent's output as untrusted (authenticate it, bound the delegation).

Frequently asked

Quick answers

What is A2A interop?

Letting agents built by different teams work together — one delegating a sub-task to another — via a protocol for discovery and messaging, not bespoke glue.

What is capability discovery?

Agents advertise their skills in a capability card; a coordinator matches a task's required capability and routes to an agent that lists it.

Why a shared schema?

Finding a capable agent isn't enough — a shared message format lets one agent's output feed another's input, so tasks chain across agents.

A2A vs MCP?

MCP standardizes agent-to-tool connections; A2A standardizes agent-to-agent connections. Same philosophy: agree on a protocol so components compose.

Finished this one? 0 / 99 Handbooks done

Explore the topic

See this alongside everything else on the same subject — handbooks, system designs, challenges and tools, in one place.