Server
A2AServer wraps an existing Agent and produces a transport object you can serve directly. JSON-RPC is the default; the same A2AServer instance can also build REST and gRPC transports that share one task store.
Minimal Server#
The smallest end-to-end setup: an Agent with a tool, served over JSON-RPC on a single port via uvicorn.
After startup the agent card is reachable at http://127.0.0.1:8000/.well-known/agent-card.json. A client connects by passing that base URL to A2AConfig(card_url=...) — see the Client page.
When the model streams its answer, the server publishes the text as one artifact and closes it (last_chunk=True) before the task leaves working (completed, failed, input required or cancelled), so any A2A client can tell the answer is complete. The one exception is a cancel that reaches a different replica from the one running the task: the SDK records CANCELED in the shared store and stops the running turn, which gets no chance to send the closing chunk. The terminal status still ends the stream, so clients lose nothing but the marker.
What A2AServer Holds#
A2AServer.__init__ materialises transport-agnostic state — the executor, the task store, optional push notifications. Transport-specific parameters (URL, paths, ports) live on the build_* methods.
| Constructor argument | Purpose |
|---|---|
agent | The AG2 Agent exposed over A2A |
task_store | Shared TaskStore, or a VersionedTaskStore for several replicas. Defaults to a single InMemoryTaskStore reused across every build_* call |
event_stream | TaskEventStream that carries task events between replicas. Required with a VersionedTaskStore, rejected without one |
push_config_store | Enables push-notifications CRUD (see Tasks & Push). Optional |
push_sender | Custom delivery sender. With a push_config_store and no sender, the SDK's BasePushNotificationSender delivers |
push_url_validator | Optional async callback receiving a URL and returning bool. Rejects disallowed push-notification URLs before storing them |
extended_card | Auth-aware extra metadata returned via GetExtendedAgentCard |
card_modifier / extended_card_modifier | Per-request hooks that mutate the card before it's served |
validate_input_modes | Rejects a message part whose media type the card does not declare, with the A2A content-type error. Off by default; see Validating input media types |
card_signer | Attaches a JWS signature to every card served, on all transports (see Card Signing). Optional |
executor | Escape hatch — drop in a custom AgentExecutor (see Advanced) |
Safe push notifications#
With push notifications the server POSTs task updates to a webhook URL that the client chooses. A client can therefore point the server at internal addresses or cloud metadata endpoints (SSRF). Protect the server with a URL policy.
Server. Enable push with a store and pass push_url_validator. The SDK ships a ready-made policy, validate_push_notification_url, that allows only public http(s) hosts. You pass the function itself (no call, no URL); the SDK calls it with the client's URL on every registration:
Client. The URL is set by whoever registers the webhook, using the helpers from Tasks & Push:
Pass your own async def check(url: str) -> bool instead to apply a different policy, for example an allow-list of partner hosts. A rejected URL fails registration with the SDK's invalid-params error on JSON-RPC, REST, and gRPC.
- Off by default. Without
push_url_validatorany URL is accepted, as before; AG2 does not choose a policy for you. - Needs a store.
push_url_validatorwithoutpush_config_storeraisesValueError, because push is disabled without a store. - Hosts must resolve. The SDK policy resolves the hostname and rejects it if DNS fails or any address is private, loopback, or link-local. The client only sees
Invalid push notification URL; the reason is in the server log. - Registration and delivery. The validator screens URLs when they are registered, and the default sender checks them again before each delivery. A custom
push_senderis not covered; give it the same callback (the SDK'sBasePushNotificationSendertakespush_url_validator). - Works on every SDK
ag2[a2a]installs (a2a-sdk>=1.3.0).
Note
The default InMemoryTaskStore is materialised once at __init__ time. This is what makes JSON-RPC, REST and gRPC bound to the same A2AServer see each other's tasks — a single store, three transports.
Running on Several Replicas#
By default a task lives in the memory of the process that started it. That is enough for one process, and it breaks as soon as you run two: a request routed to the second copy answers GetTask with "not found", and a client that subscribes through it never sees the events of a task running on the first. Run several replicas of the same agent when you need to:
- Scale out — spread concurrent tasks over more processes or machines behind a load balancer.
- Survive restarts — a task and its history live in the database, so a rolling deploy or a crashed replica does not lose them, and a task that paused for a client-side tool call or for human input resumes on whichever replica receives the next request.
┌─► replica A: A2AServer(agent) ─┐
client ─► load balancer ─┼─► replica B: A2AServer(agent) ─┼─► shared database
└─► replica C: A2AServer(agent) ─┘ tasks · task_versions · task_events
A cluster here is nothing more than N copies of one agent that share two objects, both from the SDK's a2a.server.cluster:
- a versioned task store — all replicas read and write the same tasks, and two replicas writing the same task at once are detected instead of overwriting each other;
- an event stream — events produced on one replica reach subscribers connected to another.
The SDK ships SQL implementations of both. Install the driver through the SDK's own extras, for example pip install "a2a-sdk[postgresql]"; ag2[a2a] adds no database dependency.
One cluster is one agent
The shared tables are keyed by task and user, not by agent. Replicas must therefore all run the same agent. To serve several different agents, run a separate cluster for each one, with its own database or its own table names (table_name=, event_table_name= and version_table_name= on the store, table_name= on the stream). Each of those clusters can itself have any number of replicas.
Setting it up#
Every replica runs the same code: it builds the two shared objects on one database engine, creates the tables, and serves the agent as usual.
Start the script once per replica (PORT=8001 python replica.py, PORT=8002 python replica.py, ...) and put a load balancer in front. It needs no sticky routing: AG2's executor keeps no per-task state between calls, so any replica can serve any request of a task.
Trying it without a database server
sqlite+aiosqlite:///shared.db with pip install "a2a-sdk[sqlite]" works for local experiments with several processes on one machine. Use PostgreSQL or MySQL once the replicas run on different hosts.
Starting many replicas at once
Table creation is idempotent, but replicas that start at the same moment can race to create the same tables on a fresh database. Start the first replica (or run the two initialize() calls once as a deploy step) before scaling out.
JSON-RPC, REST and gRPC#
All three build_* methods hand the same store and stream to their transport, so the setup above does not change — only the build_* call and what serves the result do.
| Transport | What each replica runs | What the load balancer must do |
|---|---|---|
| JSON-RPC | app = server.build_jsonrpc(url=...) under uvicorn | Plain HTTP load balancing. Streaming responses are long-lived text/event-stream requests: disable response buffering and allow idle timeouts longer than your slowest task |
| REST | app = server.build_rest(url=...) under uvicorn | Same as JSON-RPC |
| gRPC | grpc_server = server.build_grpc(bind="0.0.0.0:50051", grpc_url=...), then await grpc_server.start() and await grpc_server.wait_for_termination() | An HTTP/2-aware balancer that spreads calls, not connections. A gRPC client keeps one connection open, so a plain TCP balancer sends every call to the same replica |
The gRPC server is not an ASGI app, so it is started from your own asyncio.run(...) entry point rather than by uvicorn; run one such process per replica. grpc_url is the balancer's address, bind is the replica's own listener address. To expose several transports from the same replicas, build one multi-transport card as described in One Server, Three Transports; every transport shares the one store and stream.
What A2AServer checks#
A2AServer refuses a configuration that cannot work, at construction time:
- A
VersionedTaskStorewithoutevent_streamraisesValueError. Without a stream, streaming would silently work only on the replica running the task. A single replica that uses a versioned store passes a stream too. - An
event_streamwithout aVersionedTaskStoreraisesValueError: the stream orders events by task version.
Push notifications stay per-replica
push_config_store and push_sender are separate from the task store and are not shared by the setup above. With the default in-memory push store, a webhook registered through replica A is unknown to replica B, so a task that finishes on B sends nothing and raises no error. If webhooks must work across replicas, pass the SDK's database push store, built on the same engine, and a sender that reads it:
AG2 does not warn about an in-memory push store: it is a valid choice when webhooks only need to work on one replica.
Server-side Tools#
Tools attached to the wrapped Agent execute on the server, just as they would for a local agent. The remote LLM picks them up automatically.
For client-side tools — declared on the caller and forwarded back from the server when the LLM calls them — see Client → Local Tools.
Choosing a Transport#
The default build_jsonrpc(...) is the right choice for most setups. JSON-RPC is the most widely-supported A2A binding, works over any HTTP infrastructure (proxies, gateways, load balancers), and is what every A2A client implementation speaks first.
Reach for an alternative transport when:
| Transport | Use when |
|---|---|
build_jsonrpc (default) | You want the simplest, most portable HTTP binding. Recommended start. |
build_rest | You need a HTTP+JSON REST surface with stable URLs (logging, cache control, route-level auth in a gateway). |
build_grpc | You need bidirectional streaming with low overhead, or your infra is gRPC-native. |
REST#
build_rest(path_prefix="/v1") mounts the routes under a sub-path; both the card and the dispatcher respect it.
gRPC#
build_grpc returns an unstarted grpc.aio.Server — the caller is responsible for start() and wait_for_termination(). bind is the listener address, grpc_url is the URL declared in the card (they're usually identical, but differ when the server sits behind a load balancer).
Note
A2A v1.x has no GetAgentCard gRPC method — the public card is always served over HTTP at /.well-known/agent-card.json. So even for a gRPC-only server clients fetch the card via HTTP first, then switch to gRPC for the actual exchange. Plan your card URL accordingly.
TLS#
build_grpc binds an insecure port by default for backwards compatibility. Pass a grpc.ServerCredentials object as server_credentials= to bind a secure port, and publish the interface with a grpcs:// or grpc+tls:// URL:
AG2 does not read certificate files or alter the credentials; certificate loading, rotation and mTLS policy remain under application control. To require client certificates, create the server credentials with root_certificates=<client CA> and require_client_auth=True. See gRPC TLS on the client for public-CA, private-CA and mTLS channels.
One Server, Three Transports#
The same A2AServer instance can back any combination of transports. Build a single multi-transport AgentCard and call each build_* against it — they share one task store.
Caching the Agent Card#
build_jsonrpc and build_rest take card_cache_control, the value of the Cache-Control header on the card endpoint and its legacy /.well-known/agent.json alias. It is unset by default, because the right max-age depends on how often your card changes. The ETag and 304 revalidation are sent either way. gRPC has no HTTP card route, so it has no such option.
Warning
A card_modifier that returns a different card per request makes a public cache entry wrong for some callers. Use private or leave the header unset.
Validating Input Media Types#
With A2AServer(agent, validate_input_modes=True) the server rejects a message part whose media_type is declared neither in the card's default_input_modes nor in any skill's input_modes. The client gets the A2A ContentTypeNotSupportedError. A card that declares no input modes accepts everything, and so does a part with no media type. Matching is exact: image/* is not understood.
build_card derives default_input_modes from the agent, so the card says what the agent can take:
text/plain,application/jsonand the fourapplication/vnd.ag2.*+jsontypes AG2 clients use for history and client-side tools.- Every media type that
agent.configaccepts as inline data (images, documents, audio, video). A config AG2 has no table for is taken to accept all of them.
input_modes=[...] replaces the derived list entirely, so keep the vnd.ag2 types in it when validation is on. A card you pass to build_jsonrpc, build_rest or build_grpc that declares input modes but omits them raises ValueError rather than failing at request time. Validation checks the card the server was built with, so a card_modifier does not widen what is accepted.
Customising the AgentCard#
build_card(agent, url=...) accepts a handful of optional kwargs to enrich the published card with discovery metadata and auth declarations.
| Argument | Purpose |
|---|---|
version | Card version (defaults to "1.0.0") |
description | Free-form description. Defaults to the first entry of the agent's system prompt, or the agent's name when it has none, since the field is required |
skills | Explicit Sequence[AgentSkill]. When None, build_card walks agent.tools for any SkillsToolkit and publishes its local skills automatically, each tagged with its own name since tags is required; falls back to a single agent-derived skill, tagged with the agent's name, if none are found |
push_notifications | Toggles capabilities.push_notifications on the card |
provider | AgentProvider block (organization, URL) |
documentation_url / icon_url | Discovery metadata |
security | Auth declarations — see below |
extensions | Sequence[AgentExtension] — protocol extensions to declare alongside AG2's own; see below |
input_modes | Replaces the derived default_input_modes — see Validating input media types |
tenants | Mapping[TransportName, str] — surface a per-transport tenant on the corresponding AgentInterface.tenant |
rest_url / rest_path_prefix / grpc_url | Per-transport URL overrides for multi-transport cards |
Declaring Authentication#
ag2.a2a.security ships factories for every A2A-recognised scheme. Each factory returns a typed Scheme object that carries its card-level binding name. Pass them to require(...) to build Requirement entries; build_card auto-derives the card's security_schemes from the schemes referenced in security= — no duplicate declarations.
| Helper | Scheme |
|---|---|
bearer_scheme(name=..., bearer_format=..., description=...) | HTTP Bearer (e.g. JWT) |
http_auth_scheme(name=..., scheme=..., ...) | Any other HTTP auth scheme (basic, digest, custom bearer formats) |
api_key_scheme(name=..., key_name=..., location=...) | API key in header / query / cookie. name is the card binding; key_name is the header/query/cookie key sent by the client. |
oauth2_scheme(name=..., flows=..., oauth2_metadata_url=...) | OAuth2 wrapping a pre-built OAuthFlows |
open_id_connect_scheme(name=..., url=...) | OpenID Connect discovery URL |
mtls_scheme(name=...) | Mutual TLS client-cert auth |
Combining requirements: AND vs OR#
The security= list holds independent rules — clients only need to satisfy one of them (entries are OR-ed). Inside a single require(...) call, all passed schemes must be presented together (arguments are AND-ed). Attach OAuth2/OIDC scopes via scheme.with_scopes(...).
Example A — accept Bearer OR API-key (two separate require() calls):
| Request headers | Accepted? |
|---|---|
Authorization: Bearer <jwt> | ✅ matches first rule |
X-API-Key: <key> | ✅ matches second rule |
| both headers present | ✅ either rule alone is enough |
| neither | ❌ no rule satisfied |
Example B — require Bearer AND API-key together (one require() with two args):
| Request headers | Accepted? |
|---|---|
only Authorization: Bearer <jwt> | ❌ missing API key |
only X-API-Key: <key> | ❌ missing Bearer |
| both headers present | ✅ both args inside the same require() satisfied |
Example C — mixing scopes (OAuth2 needs scopes, Bearer doesn't):
Scheme binding names are arbitrary strings — pass any value to name=, including non-identifier forms like "X-My-Scheme":
Note
build_card only declares auth on the card — it does not enforce it. Wire the actual check into the ASGI app (Starlette middleware, gateway, reverse proxy) or the gRPC server's interceptors.
Declaring Extensions#
A2A extensions let an agent advertise protocol behaviour beyond the base spec. AG2 always declares its own urn:ag2:client-tools:v1 as required=False; pass extensions= to declare your own alongside it.
required=True declares that the exchange genuinely breaks without the extension. AG2's client honours the flag: it refuses to connect to a card requiring a URI it hasn't activated, rather than proceeding and misbehaving mid-task. Note this is client-side only — build_card declares the requirement, it does not enforce it, and a client that ignores the flag is still served. Use required=False to let extension-unaware clients keep working.
Duplicate URIs raise ValueError, including redeclaring urn:ag2:client-tools:v1 — build_card always declares that one itself, so a card can never ship two entries for the same extension.
See Extensions for activating them on the client.
Conversation Variables#
The caller's message can carry a variables payload, which is merged into the served turn's variables before the agent runs, and the turn's variables travel back on the reply. Treat them as caller-writable and caller-readable: anything the caller should not set or see belongs in dependencies, which are never synced. Keys under the reserved ag: / a2a: prefixes are stripped in both directions. See Variables over a protocol connection.
Adding Cross-cutting Middleware#
A2A doesn't define server-side middleware. Attach CORS, auth or tracing directly to the returned transport object:
For gRPC, attach interceptors when constructing the channel via grpc.aio.Server options on build_grpc(options=...).