Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 10 of 16

A2A

0 of 16 complete

Why it matters

Multi-agent systems often start as one process calling functions, which works while every agent is yours. The moment a partner, a vendor or another team exposes an agent, the caller needs a way to describe capabilities, submit work, follow progress and collect artefacts without access to the internals. A2A exists for that boundary: it standardises the conversation between agents that do not share context or code.

Mental model

A2A is a courier contract between firms: you hand over a job description, get a tracking number and receive a parcel. The metaphor breaks because the courier may ask clarifying questions mid-job, and the parcel can be a stream of partial results rather than one object.

How it works

Discovery, task, artifact, completionInteractive

A2A 1.0.0. SendStreamingMessage opens the SSE stream; the caller answers on the same task with SendMessage. Status and artifact events arrive on that stream, not as unsolicited notifications.

Caller

planner

Remote

opaque agent

Step 1/5 · discover
agent card · A2A 1.0return · Remote → Caller
{ "name": "Billing agent",
  "description": "Reconciles invoices against payments.",
  "version": "1.0.0",
  "supportedInterfaces": [{
    "url": "https://billing.example/a2a/v1",
    "protocolBinding": "JSONRPC",
    "protocolVersion": "1.0" }],
  "provider": {
    "organization": "Acme",
    "url": "https://acme.example" },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "text/csv"],
  "skills": [{
    "id": "invoice.reconcile",
    "name": "Reconcile invoices",
    "description": "Match invoices to payments.",
    "tags": ["billing", "invoices", "reconciliation"],
    "examples": ["Reconcile March invoices"] }],
  "securitySchemes": {
    "oauth2": { "oauth2SecurityScheme": {
      "description": "OAuth 2.0 client credentials",
      "flows": { "clientCredentials": {
        "tokenUrl": "https://auth.acme.example/token",
        "scopes": {
          "invoices.write": "Reconcile invoices" } } } } } } }

Step 1: discover. Hover, tap or tab to any message to inspect its payload.

Figure. A2A 1.0 treats the remote agent as opaque: the caller fetches a card, opens a streaming task with SendStreamingMessage, answers a TASK_STATE_INPUT_REQUIRED status on the same task, and receives the artifact and completion as stream events. The task id is the correlation key; the caller never sees the remote's tools, prompt or memory.

What to notice. The failure is lost task correlation. A retry after a timeout that creates a second task performs the work twice, because task creation is not the idempotent step — the caller must reuse the task id. The second failure is card drift: an advertised skill that the endpoint no longer implements fails only after discovery.

Text version

Sequence across Caller and Remote in A2A 1.0. Step 1, discover: Caller to Remote GET /.well-known/agent-card.json with A2A-Version 1.0; Remote to Caller a card with description, version, supportedInterfaces url and JSONRPC binding, provider organization and url, capabilities streaming true, default input and output modes, a skill with name and tags, and a typed oauth2SecurityScheme with clientCredentials flows and scopes. Step 2, create: Caller to Remote SendStreamingMessage with a message carrying messageId m-01, ROLE_USER and a text part; Remote to Caller a stream event containing a task in TASK_STATE_SUBMITTED with contextId c-17 and history as a Message array. Step 3, clarify: Remote to Caller a SSE statusUpdate event with TASK_STATE_INPUT_REQUIRED and a ROLE_AGENT message asking which entity; Caller to Remote SendMessage with the answer on task t-8842. Step 4, artifact: Remote to Caller a SSE artifactUpdate event whose artifact has an artifactId, name and text part. Step 5, complete: Remote to Caller a SSE statusUpdate event with TASK_STATE_COMPLETED; the stream closes. Artifacts remain part of the task.

  1. Fetch the remote agent's card to learn its skills, endpoint, supported transports and authentication schemes.
  2. Authenticate using the scheme the card advertises, with credentials scoped to that agent rather than a shared token.
  3. Create a task by sending a message with parts, and keep the returned task id as the correlation key.
  4. Poll or subscribe for status updates, and answer input-required states with additional message parts.
  5. Collect artefacts by reference, verifying that the caller is entitled to them.
  6. Cancel or let the task expire, and record the terminal state for audit.

Trade-offs

ChoiceGood forCostFails when
Synchronous requestSimple integrationTimes out on real workThe task takes minutes
Streaming updatesProgress visibilityConnection management and reconnectsThe client is serverless or behind a proxy
Push notificationsWorks for long tasksCallback endpoint security and delivery guaranteesThe client cannot expose a public endpoint
PollingUniversal and simpleLatency and wasted requestsThe task needs near-real-time updates
Trade-off mapInteractive

Good for

Simple integration

Cost

Times out on real work

Fails when

The task takes minutes

  1. The task takes minutes
  2. The client is serverless or behind a proxy
  3. The client cannot expose a public endpoint
  4. The task needs near-real-time updates

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Synchronous request is good for Simple integration, costs Times out on real work, and fails when The task takes minutes. Streaming updates is good for Progress visibility, costs Connection management and reconnects, and fails when The client is serverless or behind a proxy. Push notifications is good for Works for long tasks, costs Callback endpoint security and delivery guarantees, and fails when The client cannot expose a public endpoint. Polling is good for Universal and simple, costs Latency and wasted requests, and fails when The task needs near-real-time updates

Failure modes

  • Lost task correlation. The client retries task creation and the remote agent performs the work twice. Debug: log task ids per client request and check for duplicate creation with identical message ids.
  • Card and endpoint disagree. The card advertises a skill the endpoint does not implement, and calls fail after discovery. Debug: run a conformance check against every advertised skill after deployment.
  • Credential reuse across agents. One token is accepted by several agents, so a compromise spreads. Debug: present the token to a different agent and confirm it is rejected.

In production

Monitor task completion time, input-required frequency and cancellation rate per remote agent. The specification fixes the states and message parts, while retry policy and push-notification signing are implementation choices, so keep a per-agent circuit breaker and a fallback path.

Common misconceptions

People think: A2A replaces MCP.

Actually: They solve different boundaries: A2A connects agents to agents, MCP connects an agent to capabilities.

People think: A2A lets you inspect the other agent's reasoning.

Actually: The protocol treats the remote agent as opaque and exchanges messages and artefacts, not internal state.

Interview angle

A strong answer explains why opacity is the design assumption and walks the task lifecycle, including input-required and cancellation. It also covers per-agent authentication. Weak answers describe A2A as a way to call another model's API.

Sources