Skip to content

Commit f1aa456

Browse files
kabirkabir
authored
a2a-java 1.0.0.CR1 Announcement (#2650)
1 parent 5a828b6 commit f1aa456

1 file changed

Lines changed: 213 additions & 0 deletions

File tree

‎_posts/2026-05-18-a2a-java-sdk-1-0-0-cr1-released.adoc‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
layout: post
3+
title: 'A2A Java SDK 1.0.0.CR1 Released'
4+
date: 2026-05-18
5+
tags: ai a2a
6+
synopsis: 'A2A Java SDK 1.0.0.CR1 is now available with v0.3 protocol backward compatibility, Android support, unified HTTP clients, and a spec-compliant SSE parser.'
7+
author: kkhan
8+
---
9+
10+
I am pleased to announce the release of https://github.com/a2aproject/a2a-java/releases/tag/v1.0.0.CR1[A2A Java SDK 1.0.0.CR1]. CR (Candidate Release) means all features planned for 1.0 are now complete -- this is the last step before GA. There are no breaking changes from Beta1, so upgrading is straightforward.
11+
12+
The big addition in this release is a *v0.3 protocol version compatibility layer*, so your v1.0 agents can interoperate with agents and clients still running v0.3. We also added an Android HTTP client, unified HTTP client implementations, and a spec-compliant SSE parser.
13+
14+
== What's A2A?
15+
16+
The Agent2Agent (A2A) Protocol is an open standard that enables AI agents to communicate and collaborate with one another, regardless of each agent's underlying framework, language, or vendor. The A2A Java SDK makes it easy to build A2A-compliant agents in Java, with reference implementations based on Quarkus.
17+
18+
== The Journey to 1.0
19+
20+
Since January 2026, we have gone through six pre-releases to get here. Here is a brief recap:
21+
22+
* https://quarkus.io/blog/a2a-java-sdk-1-0-0-alpha1/[*1.0.0.Alpha1*] (January 2026) -- Aligned with the draft A2A 1.0 specification: migrated to Java records, switched from Jackson to Gson, introduced BOMs, and added comprehensive Javadoc.
23+
* https://quarkus.io/blog/a2a-java-sdk-1-0-0-alpha2-released/[*1.0.0.Alpha2*] (February 2026) -- Added OpenTelemetry-based telemetry, push notification support, and the streamlined `AgentEmitter` API.
24+
* *1.0.0.Alpha3 / Alpha4* (February-March 2026) -- Maven coordinates changed to `org.a2aproject.sdk`, various protocol alignment improvements, and the addition of Docker/Podman test utilities.
25+
* https://quarkus.io/blog/a2a-java-sdk-1-0-0-beta1-released/[*1.0.0.Beta1*] (April 2026) -- Fully aligned with the final https://a2a-protocol.org/v1.0.0/specification/[A2A Specification 1.0.0], renamed Java packages to `org.a2aproject.sdk.*`, added structured error codes, and achieved equal support across all three transports.
26+
27+
Each of those blog posts covers its respective release in detail.
28+
29+
== Installation
30+
31+
To use A2A Java SDK 1.0.0.CR1, import the BOM and add the dependencies you need:
32+
33+
[source,xml]
34+
----
35+
<dependencyManagement>
36+
<dependencies>
37+
<dependency>
38+
<groupId>org.a2aproject.sdk</groupId>
39+
<artifactId>a2a-java-sdk-bom</artifactId>
40+
<version>1.0.0.CR1</version>
41+
<type>pom</type>
42+
<scope>import</scope>
43+
</dependency>
44+
</dependencies>
45+
</dependencyManagement>
46+
----
47+
48+
== Key Features in 1.0.0.CR1
49+
50+
=== v0.3 Protocol Version Compatibility Layer
51+
52+
The move from v0.3 to v1.0 of the A2A protocol introduced significant breaking changes -- different proto namespaces, renamed RPCs, changed HTTP paths, and inverted configuration semantics. Existing agents deployed with v0.3 can't all upgrade at once, so we added a compatibility layer that works across all three transports (JSON-RPC, gRPC, and REST).
53+
54+
It supports three scenarios:
55+
56+
1. Your *v1.0 client* talking to a *v0.3 server* agent
57+
2. Your *v1.0 server* accepting requests from *v0.3 clients*
58+
3. A *single server* serving both v1.0 and v0.3 simultaneously
59+
60+
==== Client: Talking to v0.3 Agents
61+
62+
Add the compat client dependency along with the transport you need:
63+
64+
[source,xml]
65+
----
66+
<dependency>
67+
<groupId>org.a2aproject.sdk</groupId>
68+
<artifactId>a2a-java-sdk-compat-0.3-client</artifactId>
69+
</dependency>
70+
<!-- Plus the desired transport -->
71+
<dependency>
72+
<groupId>org.a2aproject.sdk</groupId>
73+
<artifactId>a2a-java-sdk-compat-0.3-client-transport-jsonrpc</artifactId>
74+
</dependency>
75+
----
76+
77+
Then create a `Client_v0_3` instance. It only exposes operations available in v0.3:
78+
79+
[source,java]
80+
----
81+
// Fetch the agent card
82+
AgentCard_v0_3 card = // ... fetch from /.well-known/agent-card.json
83+
84+
// Create the v0.3 compatibility client
85+
Client_v0_3 client = Client_v0_3.builder(card)
86+
.withTransport(
87+
JSONRPCTransport_v0_3.class,
88+
new JSONRPCTransportConfigBuilder_v0_3())
89+
.build();
90+
----
91+
92+
Return types are v0.3 domain objects from the `org.a2aproject.sdk.compat03.spec` package.
93+
94+
==== Server: Accepting v0.3 Clients
95+
96+
Just add the compat reference dependency for your transport. Your existing `AgentExecutor` works unchanged -- the conversion layer handles translating between v0.3 and v1.0 transparently:
97+
98+
[source,xml]
99+
----
100+
<dependency>
101+
<groupId>org.a2aproject.sdk</groupId>
102+
<artifactId>a2a-java-sdk-compat-0.3-reference-jsonrpc</artifactId>
103+
</dependency>
104+
----
105+
106+
No code changes are needed beyond adding the dependency.
107+
108+
==== Multi-Version Deployment
109+
110+
In practice, you'll most likely want to serve both protocol versions from a single server. Multi-version convenience modules bundle v1.0 and v0.3 support with automatic version routing:
111+
112+
[source,xml]
113+
----
114+
<!-- Includes v1.0 + v0.3 JSON-RPC with automatic version routing -->
115+
<dependency>
116+
<groupId>org.a2aproject.sdk</groupId>
117+
<artifactId>a2a-java-sdk-reference-multiversion-jsonrpc</artifactId>
118+
</dependency>
119+
----
120+
121+
An equivalent module is available for REST (`a2a-java-sdk-reference-multiversion-rest`). For gRPC, version dispatch happens naturally through protobuf package namespaces (`a2a.v1` for v0.3 vs `lf.a2a.v1` for v1.0), so you just include both gRPC reference dependencies.
122+
123+
Clients indicate their protocol version via the `A2A-Version` HTTP header (or query parameter). If the header is absent, the server defaults to v0.3 for backward compatibility.
124+
125+
==== Backward-Compatible AgentCard
126+
127+
When serving both protocol versions, v0.3 clients need to be able to parse the agent card. The v1.0 `AgentCard` now has optional `url`, `preferredTransport`, and `additionalInterfaces` fields for this purpose. v1.0 clients use `supportedInterfaces` as before; v0.3 clients use the legacy fields:
128+
129+
[source,java]
130+
----
131+
List<AgentInterface> supportedInterfaces = List.of(
132+
new AgentInterface("JSONRPC", "http://localhost:9999"));
133+
134+
AgentCard card = AgentCard.builder()
135+
.name("My Agent")
136+
// ... other fields ...
137+
.supportedInterfaces(supportedInterfaces) // <1>
138+
.url("http://localhost:9999") // <2>
139+
.preferredTransport("JSONRPC") // <2>
140+
.additionalInterfaces( // <2>
141+
supportedInterfaces.stream()
142+
.map(iface -> new Legacy_0_3_AgentInterface(
143+
iface.protocolBinding(), iface.url()))
144+
.toList())
145+
.build();
146+
----
147+
<1> Used by v1.0 clients
148+
<2> Used by v0.3 clients -- `additionalInterfaces` uses `Legacy_0_3_AgentInterface` which serializes with the v0.3 field names (`transport` instead of `protocolBinding`)
149+
150+
Push notification payloads are also version-aware: they are formatted according to the protocol version used when the push notification configuration was registered. v0.3 clients receive v0.3 `Task` JSON; v1.0 clients receive the standard `StreamResponse` wrapper.
151+
152+
The entire compatibility layer is validated by multi-version integration tests and a v0.3 TCK conformance suite across all three transports.
153+
154+
=== Android HTTP Client
155+
156+
We now have an `AndroidA2AHttpClient` (artifact `a2a-java-sdk-http-client-android`) that uses `HttpURLConnection`, making the SDK usable on Android. This was contributed by https://github.com/sherryfox[@sherryfox] -- thank you!
157+
158+
=== Unified HTTP Clients
159+
160+
The HTTP client implementations (JDK, Vert.x, and Android) are shared across both v1.0 and v0.3 modules, eliminating duplicated HTTP client code and ensuring consistent behavior regardless of protocol version.
161+
162+
=== Spec-Compliant SSE Parser
163+
164+
A new `ServerSentEvent` record type replaces raw string-based SSE handling across all HTTP client implementations. The `ServerSentEventParser` is fully SSE spec-compliant, supporting multi-line data concatenation, event ID and type, retry intervals, and DoS protection limits.
165+
166+
=== Migration from Reactive Routes to Vert.x Web
167+
168+
We migrated the Quarkus reference server from Quarkus Reactive Routes to direct Vert.x Web Router usage. This gives us finer control over routing, security, and version dispatching. We also added comprehensive security tests as part of this work.
169+
170+
== Bug Fixes
171+
172+
* `historyLength` from `MessageSendConfiguration` is now correctly applied to `SendMessage` responses
173+
* The `Authorization` header is now included in push notification webhook requests when `AuthenticationInfo` is configured
174+
* Guard against `JsonNull` when parsing JSON-RPC response error fields
175+
* Jakarta compatibility fixes for WildFly integration
176+
177+
== Contributors
178+
179+
This release had seven contributors. A special thank you to our four first-time contributors:
180+
181+
* https://github.com/neo1027144-creator[@neo1027144-creator]
182+
* https://github.com/pratik3558[@pratik3558]
183+
* https://github.com/sherryfox[@sherryfox]
184+
* https://github.com/RainYuY[@RainYuY]
185+
186+
And to the returning contributors:
187+
188+
* https://github.com/jmesnil[@jmesnil]
189+
* https://github.com/kabir[@kabir]
190+
* https://github.com/ehsavoie[@ehsavoie]
191+
192+
Thank you all for your code, reviews, and feedback!
193+
194+
== What's Next: Road to 1.0.0.GA
195+
196+
CR1 includes all features planned for 1.0. The road to GA is about validation and community feedback. Please try CR1 in your projects and https://github.com/a2aproject/a2a-java/issues[let us know] if you run into any issues.
197+
198+
== Resources
199+
200+
* https://github.com/a2aproject/a2a-java/releases/tag/v1.0.0.CR1[Release Notes on GitHub]
201+
* https://central.sonatype.com/artifact/org.a2aproject.sdk/a2a-java-sdk-parent/1.0.0.CR1[Maven Central]
202+
* https://javadoc.io/doc/org.a2aproject.sdk/[JavaDoc]
203+
* https://a2a-protocol.org/v1.0.0/specification/[A2A Specification]
204+
205+
== Come Join Us
206+
207+
We value your feedback a lot so please report bugs, ask for improvements etc. Let's build something great together!
208+
209+
If you are an A2A Java SDK user or just curious, don't be shy and join our welcoming community:
210+
211+
* provide feedback on https://github.com/a2aproject/a2a-java/issues[GitHub];
212+
* craft some code and https://github.com/a2aproject/a2a-java/pulls[push a PR];
213+
* discuss with us in the `#a2a-java` channel on https://discord.gg/jTtSkJB74Q[Discord];

0 commit comments

Comments
 (0)