a2a-python: the official Python SDK for running agents as A2A servers

What a2a-python actually solves for Python agent builders

The Agent2Agent protocol defines how one agent talks to another: discovery, task submission, streaming updates, and the message shapes that carry them. a2a-python is the official Python implementation of that protocol, published on PyPI as a2a-sdk and maintained under the a2aproject organisation. The README describes it as "a Python library for running agentic applications as A2A Servers."

The audience is narrow and specific. If you have built an agent in Python and want it reachable by other agents that speak A2A, this package supplies the server side. If you want to call someone else's A2A agent, the same package supplies the client side. What it does not do is decide how your agent reasons, which model it calls, or how it stores memory. Those stay in your code. That separation is the point: the SDK is the wire format and the transport plumbing, not an opinion about agent design.

The compatibility table is the first thing worth reading, because it tells you the SDK implements A2A Protocol Specification 1.0 with a compatibility mode for 0.3. Both spec versions are supported across JSON-RPC, HTTP+JSON/REST and gRPC, on client and server. If you are integrating with a peer that has not moved to 1.0, the table is where you confirm you are not stranded.

How the SDK is put together: transports, extras and async Python

The dependency list in pyproject.toml is short and revealing. Core install pulls in httpx, pydantic, protobuf, google-api-core, json-rpc, googleapis-common-protos and packaging. That combination says the SDK is built around pydantic models for message validation and around JSON-RPC and protobuf as the two wire encodings. Everything heavier is optional.

The optional extras are where the architecture becomes visible. http-server brings in starlette and sse-starlette, which is how server-sent events get delivered for streaming. fastapi adds FastAPI on top of that. grpc pulls grpcio, grpcio-tools and grpcio_reflection. telemetry brings the OpenTelemetry API and SDK. postgresql, mysql and sqlite each map to a SQLAlchemy async driver (asyncpg, aiomysql, aiosqlite respectively), and sql aggregates all three. encryption adds cryptography, and signing adds PyJWT. A separate db-cli extra carries alembic for migrations.

That structure tells you the intended deployment shape. A minimal A2A server needs only the core package plus an HTTP server extra. Persistence for task state is opt-in and driver-specific. Tracing is opt-in. The README states the library is asynchronous and built on modern async Python, which matches the async SQLAlchemy drivers and the async HTTP stack. The pyproject classifiers list Python 3.10 through 3.14, with requires-python set to >=3.10. One dependency, culsans, is pinned to python_full_version < '3.13', so on 3.13 and later that package is not installed at all.

Installing a2a-sdk and running the helloworld agent

The README recommends uv, though pip works. Pick the extras you need rather than installing everything, since the SQL and gRPC stacks are not small. A core install looks like this:

uv add a2a-sdk

For an HTTP server you would instead install the http-server extra, or fastapi if you want the FastAPI integration:

uv add "a2a-sdk[fastapi]"

The README's getting-started example does not live in this repository. It points at the a2a-samples repository, under samples/python/agents/helloworld. The first step is to clone that repo and run the remote agent:

git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/helloworld
uv run .

In a second terminal, from the same directory, the client is run with uv run test_client.py. What you should see is the client sending a task to the local agent and receiving a response back over the A2A protocol. The README also mentions the a2a-inspector repository for validating your agent, which is the closest thing to a conformance tool the documentation names.

If you prefer to work inside this repository, the samples/ directory contains hello_world_agent.py and cli.py, and samples/README.md describes them. The README itself does not walk through those files, so treat them as reference code rather than a guided tutorial.

Where the documentation stops and you are on your own

The README is a good index and a poor manual. It gives installation, a compatibility matrix, a pointer to samples, and a license. It does not document how to define an agent card, how to register a task handler, how streaming updates are emitted, or how the SQL backends are configured. For those you are sent to the API reference at a2a-protocol.org/latest/sdk/python/api/ and to the a2a-samples repository.

That is a real cost. A developer who wants to expose an existing agent has to reverse-engineer the expected handler interface from samples or from the API docs, and the samples live in a different repository with its own release cadence. The README also does not document rollback, migration steps between minor versions, or what happens to in-flight tasks when a server restarts. The migration guide for 0.3 to 1.0 exists at docs/migrations/v1_0/README.md, and the README flags it as required reading, which implies the 1.0 line changed enough to break existing code.

A second limitation is scope. This is a protocol SDK. If you were hoping for orchestration, tool registration, or a planner, none of that is here. The README's feature list is about protocol compliance, extensibility and async execution. Teams that want an opinionated agent framework will find this package too low-level, and teams that want only a client will find themselves installing a dependency tree that includes protobuf and google-api-core even if they never touch gRPC.

a2a-python versus wiring agents together with MCP

The most common comparison is with the Model Context Protocol, and the topics list on the repository includes a2a-mcp, so the project itself acknowledges the adjacency. The difference in approach is horizontal versus vertical. MCP connects an agent to tools and data sources; A2A connects agents to other agents. A2A has its own notion of agent discovery and task lifecycle, which MCP does not model.

If your problem is "my agent needs to read from a database and call a search API", MCP is the fit and a2a-python is the wrong tool. If your problem is "my agent needs to hand a task to a separate agent that another team runs, and get streaming status back", that is what this SDK implements. The two are not mutually exclusive, and the repository's topic list suggests the maintainers expect both to appear in the same system, with MCP on the tool side and A2A on the agent-to-agent side.

Within Python, the alternative to a2a-python is writing the protocol yourself against the specification. That is viable for a client that only needs JSON-RPC, since the message shapes are defined by the spec and pydantic can model them. It stops being viable once you need streaming over SSE, gRPC transport, or persistent task stores, which is exactly the surface the SDK's extras cover.

Maintenance, licence and the cost of tracking the spec

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent: v1.1.4 on 2026-09-08, v1.1.3 on 2026-08-18, v1.1.2 on 2026-07-22. The versioning is release-please driven, with a .release-please-manifest.json and release-please-config.json at the top level, so changelog entries are generated from commits.

That cadence is the upgrade cost. A protocol SDK tracks an external specification, and this one supports both spec 1.0 and a 0.3 compatibility mode. When the specification moves, the SDK moves, and your code may need to as well. The 0.3 to 1.0 migration guide is the precedent: the README treats it as a mandatory stop for anyone upgrading. Budget for reading CHANGELOG.md before bumping the pin, and for testing against peers that may still be on 0.3.

The licence is Apache-2.0, declared both in the README badge and in pyproject.toml as `license = "Apache-2.0"`, with Google LLC listed as author. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you are shipping the SDK inside a commercial product. The repository also carries a SECURITY.md and a CODE_OF_CONDUCT.md, and CONTRIBUTING.md is referenced from the README. None of that is legal advice; read the LICENSE file for the actual terms.

Editorial conclusion

Adopt a2a-python if you already have an agent and need it to speak the Agent2Agent protocol over JSON-RPC, HTTP+JSON or gRPC, and you are comfortable reading the API reference at a2a-protocol.org rather than a worked tutorial. Skip it if you want a batteries-included agent framework, or if you cannot run Python 3.10 or newer. Before committing, check the compatibility table against the spec version your peers speak, confirm the extras you need (http-server, grpc, sql, telemetry) install cleanly in your environment, and read docs/migrations/v1_0/README.md if you are coming from 0.3, because the 1.0 line is a breaking change.

Frequently asked questions

Official sources

1. a2aproject/a2a-python on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases