Skip to content

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.

import uvicorn

from ag2 import Agent
from ag2.a2a import A2AServer, build_card
from ag2.config import AnthropicConfig
from ag2.tools import tool

@tool(description="Add two integers and return the sum as a string.")
async def calc_add(a: int, b: int) -> str:
    return f"{a + b}"

async def main() -> None:
    agent = Agent(
        name="claude",
        config=AnthropicConfig(model="claude-sonnet-5"),
        tools=[calc_add],
    )
    server = A2AServer(agent)
    card = build_card(agent, url="http://127.0.0.1:8000")
    asgi = server.build_jsonrpc(url="http://127.0.0.1:8000", card=card)

    await uvicorn.Server(uvicorn.Config(asgi, host="127.0.0.1", port=8000)).serve()

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:

from a2a.server.tasks import InMemoryPushNotificationConfigStore
from a2a.utils.push_url_validator import validate_push_notification_url

from ag2.a2a import A2AServer

server = A2AServer(
    agent,
    push_config_store=InMemoryPushNotificationConfigStore(),
    push_url_validator=validate_push_notification_url,
)

Client. The URL is set by whoever registers the webhook, using the helpers from Tasks & Push:

from ag2.a2a import A2AConfig
from ag2.a2a.push import A2APushConfig, create_push_notification_config

client = A2AConfig(card_url="http://127.0.0.1:8000")

await create_push_notification_config(
    client, task_id, A2APushConfig(url="https://my-app.example.com/a2a-hook")
)  # accepted

await create_push_notification_config(
    client, task_id, A2APushConfig(url="http://169.254.169.254/latest/meta-data")
)  # raises InvalidParamsError, nothing is stored

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_validator any URL is accepted, as before; AG2 does not choose a policy for you.
  • Needs a store. push_url_validator without push_config_store raises ValueError, 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_sender is not covered; give it the same callback (the SDK's BasePushNotificationSender takes push_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.

import asyncio
import os

import uvicorn
from a2a.server.cluster import DatabaseTaskEventStream, VersionedDatabaseTaskStore
from sqlalchemy.ext.asyncio import create_async_engine

from ag2 import Agent
from ag2.a2a import A2AServer
from ag2.config import OpenAICompletionsConfig

agent = Agent("assistant", config=OpenAICompletionsConfig("gpt-5"))

async def main() -> None:
    engine = create_async_engine("postgresql+asyncpg://user:password@db/a2a")
    task_store = VersionedDatabaseTaskStore(engine)
    event_stream = DatabaseTaskEventStream(engine)

    # Create the tables at startup, before serving. The SDK creates only the
    # `tasks` table on first use; without these calls the first request fails with
    # `no such table: task_versions`.
    await task_store.initialize()
    await event_stream.initialize()

    server = A2AServer(agent, task_store=task_store, event_stream=event_stream)
    # The load balancer's URL, not this replica's: clients keep talking to the balancer.
    app = server.build_jsonrpc(url="https://my-agent.example.com")

    port = int(os.environ["PORT"])
    await uvicorn.Server(uvicorn.Config(app, host="0.0.0.0", port=port)).serve()

asyncio.run(main())

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 VersionedTaskStore without event_stream raises ValueError. 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_stream without a VersionedTaskStore raises ValueError: 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:

from a2a.server.tasks import BasePushNotificationSender, DatabasePushNotificationConfigStore

push_store = DatabasePushNotificationConfigStore(engine)
await push_store.initialize()

server = A2AServer(
    agent,
    task_store=task_store,
    event_stream=event_stream,
    push_config_store=push_store,
    push_sender=BasePushNotificationSender(http_client, push_store),
)

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.

from ag2 import Agent
from ag2.a2a import A2AServer
from ag2.config import AnthropicConfig
from ag2.tools import tool
from ag2.tools.builtin import WebSearchTool

agent = Agent(
    name="claude",
    config=AnthropicConfig(model="claude-sonnet-5"),
    tools=[
        WebSearchTool(),  # built-in provider tool — runs on Anthropic's side
        calc_add,         # @tool — runs on this server
    ],
)
server = A2AServer(agent)

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#

1
2
3
card = build_card(agent, url="http://127.0.0.1:8001", transports=("rest",))
rest_app = server.build_rest(url="http://127.0.0.1:8001", card=card)
await uvicorn.Server(uvicorn.Config(rest_app, host="127.0.0.1", port=8001)).serve()

build_rest(path_prefix="/v1") mounts the routes under a sub-path; both the card and the dispatcher respect it.

gRPC#

card = build_card(
    agent,
    url="grpc://127.0.0.1:50051",
    transports=("grpc",),
    grpc_url="grpc://127.0.0.1:50051",
)
grpc_server = server.build_grpc(
    bind="127.0.0.1:50051",
    grpc_url="grpc://127.0.0.1:50051",
    card=card,
)
await grpc_server.start()
await grpc_server.wait_for_termination()

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:

from pathlib import Path

import grpc

from ag2.a2a import build_card

private_key = Path("certs/server-key.pem").read_bytes()
certificate = Path("certs/server.pem").read_bytes()
credentials = grpc.ssl_server_credentials([(private_key, certificate)])

grpc_url = "grpcs://agents.example.com:50051"
card = build_card(agent, url="https://agents.example.com", transports=("grpc",), grpc_url=grpc_url)
grpc_server = server.build_grpc(
    bind="0.0.0.0:50051",
    grpc_url=grpc_url,
    card=card,
    server_credentials=credentials,
)
await grpc_server.start()
await grpc_server.wait_for_termination()

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.

from a2a.server.tasks import InMemoryPushNotificationConfigStore

server = A2AServer(agent, push_config_store=InMemoryPushNotificationConfigStore())
card = build_card(
    agent,
    url="http://127.0.0.1:8000",
    transports=("jsonrpc", "rest", "grpc"),
    rest_url="http://127.0.0.1:8001",
    grpc_url="grpc://127.0.0.1:50051",
)

asgi = server.build_jsonrpc(url="http://127.0.0.1:8000", card=card)
rest = server.build_rest(url="http://127.0.0.1:8001", card=card)
grpc = server.build_grpc(bind="127.0.0.1:50051", grpc_url="grpc://127.0.0.1:50051", card=card)

await grpc.start()
await asyncio.gather(
    uvicorn.Server(uvicorn.Config(asgi, host="127.0.0.1", port=8000)).serve(),
    uvicorn.Server(uvicorn.Config(rest, host="127.0.0.1", port=8001)).serve(),
    grpc.wait_for_termination(),
)

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.

1
2
3
4
5
6
7
from ag2 import Agent
from ag2.a2a import A2AServer
from ag2.config import AnthropicConfig

agent = Agent(name="claude", config=AnthropicConfig(model="claude-sonnet-5"))
server = A2AServer(agent)
app = server.build_jsonrpc(url="https://agents.example.com", card_cache_control="public, max-age=3600")

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/json and the four application/vnd.ag2.*+json types AG2 clients use for history and client-side tools.
  • Every media type that agent.config accepts as inline data (images, documents, audio, video). A config AG2 has no table for is taken to accept all of them.
from ag2 import Agent
from ag2.a2a import A2AServer, build_card
from ag2.config import AnthropicConfig

agent = Agent(name="claude", config=AnthropicConfig(model="claude-sonnet-5"))
server = A2AServer(agent, validate_input_modes=True)
url = "https://agents.example.com"

# An explicit list replaces the one derived from the model.
card = build_card(
    agent,
    url=url,
    input_modes=[
        "text/plain",
        "application/json",
        "application/vnd.ag2.history+json",
        "application/vnd.ag2.tool-call+json",
        "application/vnd.ag2.tool-result+json",
        "application/vnd.ag2.tool-schemas+json",
        "image/png",
        "image/svg+xml",
    ],
)
app = server.build_jsonrpc(url=url, card=card)

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.

from ag2.a2a import A2AServer, build_card
from ag2.a2a.security import (
    bearer_scheme,
    api_key_scheme,
    require,
)

bearer = bearer_scheme(name="bearer", bearer_format="JWT")
api_key = api_key_scheme(name="x_api_key", key_name="X-API-Key", location="header")

card = build_card(
    agent,
    url="http://127.0.0.1:8000",
    security=[require(bearer), require(api_key)],
)
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):

1
2
3
4
security=[
    require(bearer),
    require(api_key),
]
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):

1
2
3
security=[
    require(bearer, api_key),
]
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):

1
2
3
security=[
    require(bearer, oauth.with_scopes("read", "write")),
]

Scheme binding names are arbitrary strings — pass any value to name=, including non-identifier forms like "X-My-Scheme":

custom = bearer_scheme(name="X-My-Scheme")
require(custom)

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.

from a2a.types import AgentExtension

from ag2.a2a import build_card

card = build_card(
    agent,
    url="http://127.0.0.1:8000",
    extensions=[
        AgentExtension(
            uri="urn:acme:billing:v1",
            description="Attaches a cost breakdown to every reply",
            required=True,
        ),
    ],
)

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:

1
2
3
4
from starlette.middleware.cors import CORSMiddleware

asgi = server.build_jsonrpc(url="http://127.0.0.1:8000")
asgi.add_middleware(CORSMiddleware, allow_origins=["*"])

For gRPC, attach interceptors when constructing the channel via grpc.aio.Server options on build_grpc(options=...).