Get Started

A2A, Agent-to-Agent Protocol

MCP is agent-to-tool. A2A (Agent2Agent) is agent-to-agent, an open protocol for letting opaque agents built on different frameworks collaborate. Released by Google in April 2025, donated to the Linux Foundation in June 2025, reaching v1.0 in April 2026 with 150+ supporters including AWS, Cisco, Microsoft, Salesforce, SAP, and ServiceNow. It absorbed IBM's ACP and added the AP2 payments extension. This lesson walks the Agent Card, Task lifecycle, and the three protocol bindings, using the A2A 1.0.1 wire names.

75 minutesBuildPython (stdlib, Agent Card + Task harness)Free lesson

Learning Objectives

  • Distinguish agent-to-tool (MCP) from agent-to-agent (A2A) use cases.
  • Publish an Agent Card at /.well-known/agent-card.json with skills and supportedInterfaces metadata.
  • Walk the Task lifecycle: TASK_STATE_SUBMITTEDTASK_STATE_WORKINGTASK_STATE_INPUT_REQUIREDand the terminal states TASK_STATE_COMPLETEDTASK_STATE_FAILEDTASK_STATE_CANCELEDTASK_STATE_REJECTED.
  • Use Messages whose Parts each hold one of textrawurlor dataand Artifacts as outputs.

The Problem

A customer-service agent needs to delegate report-writing to a specialized writer agent. Options pre-A2A:

  • Custom REST API. Works but every pairing is a one-off.
  • Shared codebase. Requires the two agents to run the same framework.
  • MCP. Doesn't fit: MCP is for calling tools, not for two agents collaborating while preserving each agent's opaque internal reasoning.

A2A fills the gap. It models the interaction as one agent sending a Task to another, with a lifecycle, messages, and artifacts. The called agent's internal state stays opaque, the caller sees only task state transitions and eventual outputs.

A2A is the "let agents across frameworks talk to each other" protocol. It does not replace MCP; the two are complementary.

The Concept

Agent Card

Every A2A-compliant agent publishes a card at /.well-known/agent-card.json:

JSON
{
  "name": "research-agent",
  "description": "Summarizes academic papers and drafts citations.",
  "version": "1.2.0",
  "supportedInterfaces": [
    {
      "url": "https://research.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {"streaming": true, "pushNotifications": true},
  "securitySchemes": {
    "bearer": {"httpAuthSecurityScheme": {"scheme": "Bearer"}}
  },
  "securityRequirements": [{"schemes": {"bearer": {"list": []}}}],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/markdown"],
  "skills": [
    {
      "id": "summarize_paper",
      "name": "Summarize a paper",
      "description": "Read a paper PDF and produce a 3-paragraph summary.",
      "tags": ["research", "summarization"],
      "inputModes": ["text/plain", "application/pdf"],
      "outputModes": ["text/markdown"]
    }
  ]
}

Discovery is URL-based: fetch the card, pick the first supportedInterfaces entry whose protocolBinding your client speaks, and enumerate skills. Input and output modes are media types.

Signed Agent Cards

A card can carry a signatures array. Each entry is a JWS (RFC 7515) computed over the card's RFC 8785 canonical JSON, with the signatures field left out. Consumers canonicalize the card the same way and verify. Prevents impersonation.

Task lifecycle

Text
TASK_STATE_SUBMITTED
  -> TASK_STATE_WORKING
  -> TASK_STATE_COMPLETED | TASK_STATE_FAILED | TASK_STATE_CANCELED | TASK_STATE_REJECTED

TASK_STATE_WORKING
  -> TASK_STATE_INPUT_REQUIRED
  -> TASK_STATE_WORKING (the client sends a message with the same taskId)

Clients initiate with SendMessageand the server creates the Task. The called agent transitions through states; clients poll with GetTask or stream over SSE with SendStreamingMessage and SubscribeToTask. A stream carries statusUpdate and artifactUpdate events and closes when the task reaches a terminal state. There is no final flag.

Messages and Parts

A message has a messageIda role (ROLE_USER or ROLE_AGENT), and one or more Parts. Each Part holds exactly one content field, and that field name is the type. There is no kind field.

  • text: plain content.
  • raw: file bytes, base64 in JSON, usually with filename and mediaType.
  • url: a link to file content.
  • data: structured JSON payload (structured input for the called agent).

Example:

JSON
{
  "messageId": "msg-001",
  "role": "ROLE_USER",
  "parts": [
    {"text": "Summarize this paper."},
    {"raw": "...", "filename": "paper.pdf", "mediaType": "application/pdf"},
    {"data": {"targetLength": "3 paragraphs"}, "mediaType": "application/json"}
  ]
}

Artifacts

Outputs are Artifacts, not raw strings. An Artifact is a named, typed output:

JSON
{
  "artifactId": "art-001",
  "name": "summary",
  "parts": [{"text": "...", "mediaType": "text/markdown"}]
}

Artifacts can be streamed as chunks. Each artifactUpdate event carries the artifact plus append and lastChunk. The caller accumulates.

Three protocol bindings

  1. JSON-RPC 2.0 over HTTP (JSONRPC). POST for requests, SSE for streaming. Methods are PascalCase: SendMessageSendStreamingMessageGetTaskListTasksCancelTaskSubscribeToTaskCreateTaskPushNotificationConfigGetTaskPushNotificationConfigListTaskPushNotificationConfigsDeleteTaskPushNotificationConfigand GetExtendedAgentCard.
  2. gRPC (GRPC). For enterprise environments where gRPC is native. Same method names.
  3. HTTP+JSON/REST (HTTP+JSON). Resource URLs such as POST /message:send and GET /tasks/{id}.

All three bindings carry the same data model. Each supportedInterfaces entry names one binding and its protocolVersion. Clients send the header A2A-Version: 1.0 on every request, because a server reads a request without it as version 0.3.

HTTP
POST /a2a HTTP/1.1
Host: research.example.com
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-001",
      "role": "ROLE_USER",
      "parts": [{"text": "Summarize this paper."}]
    }
  }
}

Opacity preservation

A key design principle: the called agent's internal state is opaque. The caller sees task state and artifacts. The called agent's chain-of-thought, its tool calls, its sub-agent delegation, all invisible. This is different from MCP, where tool calls are transparent.

Rationale: A2A enables competitors to collaborate without revealing internals. A2A can be "call this customer-service agent" without the caller learning how that agent implements the service.

Timeline

  • 2025-04-09. Google announces A2A.
  • 2025-06-23. Donated to Linux Foundation.
  • 2025-08. Absorbs IBM's ACP.
  • 2025-09. AP2 extension (Agent Payments) ships.
  • 2026-04. v1.0 released with 150+ supporting organizations.

Relationship to MCP

DimensionMCPA2A
Use caseAgent-to-toolAgent-to-agent
OpacityTransparent tool callsOpaque inner reasoning
Typical callerAgent runtimeAnother agent
StateTool-call resultTask with lifecycle
AuthorizationOAuth 2.1 (Phase 13 · 16)Agent Card securitySchemes + securityRequirements
TransportStdio / Streamable HTTPJSON-RPC / gRPC / HTTP+JSON

Use MCP when you want to invoke a specific tool. Use A2A when you want to delegate a whole task to another agent. Many production systems use both: an agent uses MCP for its tool layer and A2A for its collaboration layer.

Use It

code/main.py implements a minimal A2A harness: the writer agent publishes its card, the research agent sends it a SendMessage request with a PDF part and a text instruction, and the task moves through TASK_STATE_WORKING → TASK_STATE_INPUT_REQUIRED → TASK_STATE_WORKING → TASK_STATE_COMPLETED before returning a text artifact. All stdlib; uses an in-memory transport to focus on message shapes.

What to look at:

  • Agent Card JSON shape.
  • Server-side task id assignment and state transitions.
  • Parts typed by which content field is present.
  • TASK_STATE_INPUT_REQUIRED branch mid-task.
  • Artifact return on completion.

Ship It

This lesson produces outputs/skill-a2a-agent-spec.md. Given a new agent that should be callable by other agents, the skill produces the Agent Card JSON, skills schema, and endpoint blueprint.

Exercises

  1. Run code/main.py. Trace the full Task lifecycle, including the TASK_STATE_INPUT_REQUIRED pause where the called agent asks for a clarification.
  2. Add a signed Agent Card. Put one JWS entry in signatures with alg set to HS256signing the card's canonical JSON without the signatures field. Write a verifier and confirm it fails on a mutated card.
  3. Implement task streaming with SendStreamingMessage: the writer agent emits the taskthree artifactUpdate chunks, and a statusUpdate with TASK_STATE_COMPLETEDthen closes the stream. The caller accumulates the chunks.
  4. Design an A2A agent that wraps an MCP server. Map each MCP tool to an A2A skill. Note the trade-offs, what opacity is lost?
  5. Read the A2A v1.0 announcement and identify the one feature that is not yet implemented by any framework as of April 2026. (Hint: it relates to multi-hop task delegation.)

Key Terms

TermWhat people sayWhat it actually means
A2A"Agent-to-Agent protocol"Open protocol for opaque agent collaboration
Agent Card"/.well-known/agent-card.json"Published metadata describing an agent's skills and supportedInterfaces
Skill"A callable unit"A named operation the agent supports (analog to MCP tool)
Task"Unit of delegation"A work item with a lifecycle and final artifact
Message"Task input"Carries Parts (textrawurldata)
Part"Typed chunk"Exactly one of text / raw / url / dataplus optional mediaType; no kind field
Artifact"Task output"Named, typed output returned on completion
AP2"Agent Payments Protocol"Payments extension built on A2A; card signing is core A2A (signatures)
Opacity"Black-box collaboration"Called agent's internals are hidden from caller
TASK_STATE_INPUT_REQUIRED"Task pause"Interrupted state when the agent needs more info

Further Reading

The full code

Every file for this lesson. Copy it, run it, then change it.

main.py
"""Phase 13 Lesson 19 - A2A agent-to-agent protocol.

Research agent calls writer agent via A2A 1.0:
  1. Research agent fetches writer's Agent Card
  2. Sends SendMessage with text + file parts
  3. Writer task moves TASK_STATE_WORKING -> TASK_STATE_INPUT_REQUIRED
     -> TASK_STATE_WORKING -> TASK_STATE_COMPLETED
  4. Research agent receives an Artifact

Stdlib only; in-process transport stands in for JSON-RPC over HTTP.
Wire names follow A2A 1.0.1: docs/specification.md and specification/a2a.proto.

Run: python code/main.py
"""

from __future__ import annotations

import base64
import json
import uuid


A2A_VERSION = "1.0"

WRITER_AGENT_CARD = {
    "name": "writer-agent",
    "description": "Drafts technical summaries and reports from source material.",
    "version": "1.0.0",
    "supportedInterfaces": [
        {
            "url": "https://writer.example.com/a2a",
            "protocolBinding": "JSONRPC",
            "protocolVersion": A2A_VERSION,
        }
    ],
    "capabilities": {"streaming": True, "pushNotifications": False},
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/markdown"],
    "skills": [
        {
            "id": "draft_report",
            "name": "Draft report",
            "description": "Given source material and a target length, produce a report.",
            "tags": ["writing", "summarization"],
            "inputModes": ["text/plain", "application/pdf", "application/json"],
            "outputModes": ["text/markdown"],
        }
    ],
}

PART_CONTENT_FIELDS = ("text", "raw", "url", "data")


def part_content(part: dict) -> str:
    present = [name for name in PART_CONTENT_FIELDS if name in part]
    if len(present) != 1:
        raise ValueError(f"a Part holds exactly one of text, raw, url, data; got {present}")
    return present[0]


def new_message(role: str, parts: list[dict], task_id: str | None = None) -> dict:
    message = {"messageId": str(uuid.uuid4()), "role": role, "parts": parts}
    if task_id:
        message["taskId"] = task_id
    return message


TASK_STORE: dict[str, dict] = {}


def transition(task: dict, state: str, message: dict | None = None) -> None:
    print(f"    WRITER  : {task['status']['state']} -> {state}")
    task["status"] = {"state": state}
    if message:
        task["status"]["message"] = message
        task["history"].append(message)


def writer_send_message(params: dict) -> dict:
    message = params["message"]
    task_id = message.get("taskId")
    if task_id:
        task = TASK_STORE[task_id]
    else:
        task = {
            "id": f"task_{uuid.uuid4().hex[:10]}",
            "contextId": str(uuid.uuid4()),
            "status": {"state": "TASK_STATE_SUBMITTED"},
            "artifacts": [],
            "history": [],
        }
        TASK_STORE[task["id"]] = task
        print(f"    WRITER  : created task {task['id']}")
    task["history"].append(message)
    transition(task, "TASK_STATE_WORKING")
    data_payloads = [p["data"] for p in message["parts"] if part_content(p) == "data"]
    if not data_payloads or "targetLength" not in data_payloads[0]:
        transition(task, "TASK_STATE_INPUT_REQUIRED", new_message("ROLE_AGENT", [
            {"text": "Please specify targetLength as a data part."}
        ], task["id"]))
    else:
        finish(task, data_payloads[0]["targetLength"])
    return {"task": task}


def finish(task: dict, length: str) -> None:
    text = f"[writer agent] {length} summary of provided source: "\
           f"topic identified, key points extracted, conclusion drafted."
    task["artifacts"].append({
        "artifactId": str(uuid.uuid4()),
        "name": "summary",
        "parts": [{"text": text, "mediaType": "text/markdown"}],
    })
    transition(task, "TASK_STATE_COMPLETED")


def writer_endpoint(headers: dict, request: dict) -> dict:
    response = {"jsonrpc": "2.0", "id": request["id"]}
    if headers.get("A2A-Version") != A2A_VERSION:
        response["error"] = {"code": -32009, "message": "Version not supported"}
    elif request["method"] != "SendMessage":
        response["error"] = {"code": -32601, "message": "Method not found"}
    else:
        response["result"] = writer_send_message(request["params"])
    return response


def send_message(request_id: int, message: dict) -> dict:
    request = {"jsonrpc": "2.0", "id": request_id, "method": "SendMessage",
               "params": {"message": message}}
    print(f"  research : {request['method']} (A2A-Version: {A2A_VERSION})")
    response = writer_endpoint({"A2A-Version": A2A_VERSION}, request)
    return response["result"]["task"]


def research_agent_flow() -> None:
    print("=" * 72)
    print("PHASE 13 LESSON 18 - A2A CALL FROM RESEARCH TO WRITER")
    print("=" * 72)

    print("\n--- research agent fetches writer Agent Card ---")
    print(json.dumps({k: WRITER_AGENT_CARD[k] for k in ("name", "supportedInterfaces", "skills")},
                     indent=2))

    skill = WRITER_AGENT_CARD["skills"][0]
    skill_id = skill["id"]
    print(f"\n  research agent will invoke skill: {skill_id}")

    msg = new_message("ROLE_USER", [
        {"text": "Summarize the attached paper."},
        {"raw": base64.b64encode(b"fake-pdf").decode(), "filename": "paper.pdf",
         "mediaType": "application/pdf"},
    ])
    task = send_message(1, msg)
    print(f"  research : task state = {task['status']['state']}")

    if task["status"]["state"] == "TASK_STATE_INPUT_REQUIRED":
        print("\n--- research agent supplies the missing data ---")
        followup = new_message("ROLE_USER", [
            {"data": {"targetLength": "3 paragraphs"}, "mediaType": "application/json"},
        ], task["id"])
        task = send_message(2, followup)
        print(f"  research : task state = {task['status']['state']}")

    print("\n--- research agent reads artifact ---")
    if task["artifacts"]:
        artifact = task["artifacts"][0]
        print(f"  name      : {artifact['name']}")
        print(f"  mediaType : {artifact['parts'][0]['mediaType']}")
        print(f"  content   : {artifact['parts'][0]['text']}")

    print("\n--- lifecycle observation ---")
    print(f"  final state : {task['status']['state']}")
    print(f"  history     : {len(task['history'])}")


if __name__ == "__main__":
    research_agent_flow()