a2a-java: The Official Java SDK for Running Agents as A2A Servers

What a2a-java Solves for Java Agent Developers

The Agent2Agent protocol defines how one agent talks to another: task submission, streaming updates, and transport-level message exchange. a2a-java is the official Java SDK for that protocol. Its stated purpose is narrow and concrete: a Java library that helps run agentic applications as A2A servers, plus the matching client side to call any A2A-compliant agent. If you have an existing Java service that already does useful work and you want it reachable by other agents, this is the layer that turns it into an A2A endpoint.

The audience is Java teams. The README requires Java 17 or later, and the build is Maven. That excludes anyone on Java 11 or 8, which matters for enterprise shops with long upgrade cycles. It also excludes polyglot teams whose agents are written in Python or TypeScript, though the examples folder shows a Java server paired with a Python client and the reverse, so interoperability across languages is part of the intended picture rather than an afterthought.

Modules, Transports and the compat-0.3 Layer

The repository is a multi-module Maven build. The README names three transports: JSON-RPC, gRPC, and REST. The top-level entries show how that splits: spec/ and spec-grpc/ hold the protocol definitions and generated gRPC classes, transport/ and jsonrpc-common/ hold transport plumbing, client/ and server-common/ hold the two sides of the API, and reference/ contains the reference server implementations for each transport. There is also a boms/ directory, so a Maven BOM is available to align versions across the SDK modules.

Two entries deserve attention. compat-0.3/ exists because the protocol moved past the 0.3 line, and the module name signals that some compatibility path is maintained for peers still on that version. The README does not describe what compat-0.3 actually covers, which is a gap if you have to interoperate with an older deployment. The tck/ directory holds a technology compatibility kit, and itk/ is present as well; the README does not explain either, so treat them as repository structure rather than documented features.

For gRPC specifically, the README is explicit about the regeneration workflow: the project copies a2a.proto from the specification repository into spec-grpc/ and adjusts the java_package option to org.a2aproject.sdk.grpc. That means the generated classes live under a package name this project controls, not the one in the upstream proto. If you generate your own stubs from the upstream proto without that adjustment, you will get a package mismatch against the SDK's gRPC types.

Installing a2a-java and Starting a JSON-RPC Server

The README gives one dependency snippet, for the reference JSON-RPC server. It requires Java 17 or later and a Maven project. Note the version placeholder: the README points you at the releases page instead of pinning a number, so you must choose a released version yourself.

<dependency>
    <groupId>org.a2aproject.sdk</groupId>
    <artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>
    <version>${org.a2aproject.sdk.version}</version>
</dependency>

The README says to see the Server Guide for full setup instructions, and that guide lives on the documentation site rather than in the repository. That is the honest boundary here: the dependency coordinates are in the README, the wiring is not. If you want a working end-to-end example instead of prose, the examples/helloworld/server/ directory is described as a Java A2A server with a Python client, and examples/helloworld/client/ is the mirror image. Those two are the fastest way to see what a running server looks like, because the README itself stops at the dependency block.

To build the SDK from source rather than consume it, the README gives a single command:

mvn clean install

For gRPC class regeneration, the build takes a flag that the README states explicitly:

mvn clean install -Dskip.protobuf.generate=false

Run that in the spec-grpc module after copying the upstream proto and changing java_package. The default build skips protobuf generation, so a plain mvn clean install will not regenerate those classes.

Where a2a-java Is the Wrong Choice

The most concrete limitation is the one the README states without softening it: the dependency snippet carries a placeholder version and defers to the releases page. If you are looking for a drop-in artifact with a documented stable API, this is a project where the API surface has been moving. The release history shows three releases inside roughly two weeks in August and September 2026, all on the 1.3 line. Frequent point releases on a young protocol implementation mean you should expect to track versions rather than pin once and forget.

Java 17 is a hard floor. Teams on Java 11 cannot use it at all, and the README offers no shaded or backported variant.

The transport split is another decision the README does not make for you. It lists JSON-RPC, gRPC, and REST as supported, and the reference implementations live under reference/, but it does not say which one to pick for a given deployment. REST is the easiest to debug with ordinary HTTP tooling; gRPC brings protobuf code generation and the package-adjustment step described above. Choosing badly means rewriting the server integration later, because the transport is not a runtime toggle in the dependency coordinates shown.

Finally, the README does not document rollback, migration between protocol versions, or what compat-0.3 actually guarantees. If you need a documented upgrade path before adopting, that documentation is not in the repository README.

a2a-java Against a Jakarta EE Integration Like a2a-jakarta

The README names one alternative directly: a2a-jakarta, hosted under wildfly-extras, described as working with any runtime supporting the Jakarta EE Web Profile. The difference is architectural, not cosmetic. a2a-java ships reference implementations for JSON-RPC, gRPC, and HTTP+JSON (REST) transports, and the README associates those reference implementations with Quarkus. a2a-jakarta takes the same protocol and targets the Jakarta EE programming model instead.

That distinction decides your deployment. If your service is already a Quarkus application, the reference implementations in this repository are the natural fit and the transport modules line up with what you have. If your service runs on a Jakarta EE Web Profile container, pulling in the Quarkus-oriented reference server means bringing a runtime you did not choose. The README also points to CONTRIBUTING_INTEGRATIONS.md for adding further integrations, which tells you the project expects the integration surface to be plural rather than single-runtime.

The other comparison worth naming is language, not framework. The examples pair Java on one side with Python on the other, so if your agents are Python-first, the A2A protocol itself is the interop layer and this SDK is only relevant for the Java half. Nothing in the README suggests a2a-java is meant to replace a Python A2A implementation; it is meant to sit on the Java side of the same conversation.

Extras, Licence and What an Upgrade Costs

The extras/ folder holds optional add-ons the README enumerates: OpenTelemetry, a JPA-backed task store, a Kafka-based replicated queue manager, and Vert.x and Android HTTP clients. These are the pieces that turn a reference server into something production-shaped. A JPA task store means task state survives restarts; the Kafka queue manager means more than one server instance can share work. The README lists them without versioning guidance, so the practical question is whether each extra is released in lockstep with the core modules or independently. The boms/ directory suggests the project intends to give you a way to align them, but the README does not spell out which artifacts the BOM covers.

The licence is Apache-2.0, stated in the README and in the LICENSE file. That is a permissive licence with an explicit patent grant, which is the common choice for protocol SDKs that want broad adoption. It does not impose copyleft obligations on your own code. This is a description of the licence text, not legal advice; if your organisation has specific policy about patent clauses or attribution, read the LICENSE file rather than this summary.

Upgrade cost is the real unknown. Three releases on the 1.3 line within two weeks indicates active iteration, and the presence of compat-0.3/ indicates the project has already crossed one protocol version boundary. The README does not describe how a 0.3 peer and a 1.3 peer interoperate, so if your ecosystem is mixed, that is the first thing to test rather than assume.

Editorial conclusion

Adopt a2a-java if you already run a Java 17+ service and want it to speak the A2A protocol without writing transport code, and check the release page for the current version rather than copying a placeholder. Do not adopt it if you need a stable API surface before 1.0 or if you cannot run Java 17. Before committing, verify which transport artifacts your runtime needs, whether the compat-0.3 module is relevant to your peers, and how the extras you plan to use (JPA task store, Kafka queue manager) are versioned against the core.

Frequently asked questions

Official sources

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