A2A Protocol Overview - AG2

Overview

The autogen.beta.a2a module exposes any AG2 Agent over the Agent2Agent (A2A) protocol and lets one AG2 agent talk to a remote A2A endpoint as if it were a regular LLM provider. The protocol is transport-agnostic: the same agent can be served over JSON-RPC, HTTP+JSON (REST) or gRPC, and clients pick the binding from the published AgentCard.

When To Use A2A

Reach for A2A when the agents you need to combine don't live in the same Python process:

A remote agent owned by a different team (or a different runtime) that you want to call as a tool.
A network of services that need a vendor-neutral, spec-defined wire format instead of bespoke HTTP APIs.
A long-running task that should outlive a single client request and be polled / streamed by id.

For in-process multi-agent scenarios — strict turn order, governance, audit trails — see the Multi-Agent Network instead. A2A is the cross-process / cross-host complement, not a replacement.

Mental Model

   ┌────────────────────────┐                  ┌────────────────────────┐
   │ Local Agent            │                  │ A2AServer              │
   │  config=A2AConfig(...) │  AgentCard       │  wraps an Agent        │
   │                        │  ◀──────────────▶│  + TaskStore           │
   │  send / sendStreaming  │  Task lifecycle  │  + (optional) push     │
   └──────────┬─────────────┘                  └────────────┬───────────┘
              │                                             │
              │  one of: jsonrpc / rest / grpc              │
              └──────────────────  network  ────────────────┘

The server publishes an AgentCard at /.well-known/agent-card.json. Every binding the server supports is listed in card.supported_interfaces; the client reads the card, picks one binding (via prefer=... or the first match) and uses it for the actual message/send, tasks/get and friends. URLs for individual transports are encoded in the card — the client never has to know them up front.

Core Concepts

Concept	Lives in	Purpose
`A2AServer`	`autogen.beta.a2a`	Wraps an `Agent` and produces a Starlette app (JSON-RPC / REST) or `grpc.aio.Server`
`build_card`	`autogen.beta.a2a`	Builds the `AgentCard` declaring which transports the server speaks
`A2AConfig`	`autogen.beta.a2a`	A `ModelConfig` — plug it into a local `Agent` to talk to a remote A2A server as its LLM
`TaskStore`	A2A SDK	Backs every transport on one server. Defaults to `InMemoryTaskStore`
`ClientToolsExtension`	`urn:ag2:client-tools:v1`	AG2-defined extension declared in the card. Lets a remote LLM call tools that live on the client
`list_tasks` / `get_task` / `cancel_task`	`autogen.beta.a2a.tasks`	Helpers for inspecting and aborting tasks on the remote server
`A2APushConfig`	`autogen.beta.a2a.push`	Webhook subscription config + CRUD helpers
`A2AEvent` family	`autogen.beta.a2a.events`	Typed wire events surfaced into the AG2 stream — subscribe for observability

Reading Order

Server — expose an existing Agent over A2A.
Client — connect to a remote A2A endpoint, multi-turn, client-side tools, as_tool().
Tasks & Push — inspect/cancel tasks and manage push-notification webhooks.
Advanced — HITL via input_required, streaming reconnect, custom AgentExecutor.

Public API

Top-level imports — the most commonly used entry points are re-exported from autogen.beta.a2a:


`<br>1<br>`	`<br>from autogen.beta.a2a import A2AConfig, A2AServer, build_card<br>`

Sub-modules:

Module	Contents
`autogen.beta.a2a.tasks`	`list_tasks`, `get_task`, `cancel_task`, `ListedTasks`
`autogen.beta.a2a.push`	`A2APushConfig`, `A2APushAuthentication`, CRUD helpers
`autogen.beta.a2a.security`	`Scheme` / `Requirement` types, scheme factories (`bearer_scheme`, `api_key_scheme`, `oauth2_scheme`, `mtls_scheme`, `http_auth_scheme`, `open_id_connect_scheme`) and the `require()` builder for `AgentCard` auth declarations
`autogen.beta.a2a.events`	Typed `A2AEvent` wrappers surfaced into the AG2 stream — `A2ATaskSnapshot`, `A2ATaskStatusUpdate`, `A2ATaskArtifactUpdate`, `A2ATextArtifact`, `A2AToolCallArtifact`, `A2AMessage`
`autogen.beta.a2a.errors`	Exception hierarchy — `A2AError`, `A2ATaskTerminalError`, `A2AReconnectError`, `A2AInvalidCardError`, `A2AClientToolsNotSupportedError`
`autogen.beta.a2a.transports`	`TransportName` — `Literal["jsonrpc", "rest", "grpc"]` — plus low-level `build_*` builders
`autogen.beta.a2a.testing`	In-process test helpers — `make_test_client_factory`, `make_test_rest_client_factory`, `pick_free_port`

Note

The A2A integration depends on a2a-sdk. Install with the a2a extras: pip install "ag2[a2a]". gRPC is an additional optional dependency — install with pip install "ag2[a2a-grpc]".