Skip to content

Commit 7d34ef7

Browse files
fjumafjuma
committed
Add a blog post on how to get started with A2A Java SDK 0.3.0
1 parent f353945 commit 7d34ef7

File tree

1 file changed

+244
-0
lines changed

1 file changed

+244
-0
lines changed

‎_posts/2025-08-28-quarkus-a2a-java-0-3-0-alpha-release.adoc

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
layout: post
3+
title: 'Getting Started with Quarkus and A2A Java SDK 0.3.0'
4+
date: 2025-08-28
5+
tags: ai a2a
6+
synopsis: 'Today, we released A2A Java SDK 0.3.0.Alpha1. This makes it possible to quickly get started with Quarkus and A2A using the latest, more stable version of the A2A protocol.'
7+
author: fjuma
8+
---
9+
10+
Today, we have released A2A Java SDK 0.3.0.Alpha1, which aligns with the v0.3.0 version of the https://github.com/a2aproject/A2A/tree/v0.3.0[A2A specification]. This https://cloud.google.com/blog/products/ai-machine-learning/agent2agent-protocol-is-getting-an-upgrade[latest version] of the A2A protocol is more stable and introduces new features like support for the gRPC transport.
11+
12+
We've made significant changes to the A2A Java SDK to support the new protocol version and improve
13+
the user experience for both the client side and server side. In this post, we'll cover what's changed
14+
since our last release.
15+
16+
== Recap: What's A2A?
17+
18+
Before we dive into the details, let's quickly recap what https://a2aproject.github.io/A2A/specification/[A2A] is. The Agent2Agent (A2A) Protocol is an open standard initially developed by Google and is now part of the Linux Foundation. It enables AI agents to communicate and collaborate with one another, regardless of each agent's underlying framework, language, or vendor. This is very important, as it's paving the way for polyglot multi-agent systems. The A2A protocol has been gaining a lot of traction since being announced just a few months ago.
19+
20+
21+
== What's new in the A2A Java SDK?
22+
23+
Let's take a look at what's new for both A2A server agents and A2A clients.
24+
25+
=== A2A Server Agent Updates
26+
27+
==== Supported Transports
28+
29+
The A2A Java SDK now supports the gRPC transport protocol in addition to JSON-RPC.
30+
31+
To turn your Quarkus application into an A2A server agent, you simply need to add one or more dependencies on our A2A Java SDK Server Reference implementations, depending on the transport(s) you'd like your agent to support.
32+
33+
The A2A Java SDK Server Reference implementations are based on Quarkus. If you're not using Quarkus,
34+
check out the https://github.com/wildfly-extras/a2a-java-sdk-server-jakarta[A2A Java SDK for Jakarta Servers].
35+
36+
[NOTE]
37+
====
38+
The `io.github.a2asdk` `groupId` is temporary and will likely change for future releases. Keep an eye on the `a2a-java` https://github.com/a2aproject/a2a-java/blob/main/README.md[README] for up-to-date documentation.
39+
====
40+
41+
===== JSON-RPC 2.0 Transport
42+
43+
To allow your A2A server agent to support communication using JSON-RPC, add the following dependency:
44+
45+
[source,xml]
46+
----
47+
<dependency>
48+
<groupId>io.github.a2asdk</groupId>
49+
<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId> <1>
50+
</dependency>
51+
----
52+
53+
<1> `a2a-java-sdk-reference-jsonrpc` provides access to the core classes that make up the A2A specification and provides the HTTP endpoint that implements the A2A protocol using the JSON-RPC transport. If you're not using Quarkus, the `org.wildfly.a2a:a2a-java-sdk-jakarta-jsonrpc` dependency from the https://github.com/wildfly-extras/a2a-java-sdk-server-jakarta[A2A Java SDK for Jakarta Servers] project can be used instead.
54+
55+
[NOTE]
56+
====
57+
Once you've added a CDI producer that creates an `AgentCard`, the A2A Java SDK will automatically expose your agent card at the server agent's `.well-known/agent-card.json` URI.
58+
====
59+
60+
===== gRPC Transport
61+
62+
To allow your A2A server agent to support communication using gRPC, add the following dependency:
63+
64+
[source,xml]
65+
----
66+
<dependency>
67+
<groupId>io.github.a2asdk</groupId>
68+
<artifactId>a2a-java-sdk-reference-grpc</artifactId> <1>
69+
</dependency>
70+
----
71+
72+
<1> `a2a-java-sdk-reference-grpc` provides access to the core classes that make up the A2A specification and provides the gRPC service that implements the A2A protocol using the gRPC transport. If you're not using Quarkus, the `org.wildfly.a2a:a2a-java-sdk-jakarta-grpc` dependency from the https://github.com/wildfly-extras/a2a-java-sdk-server-jakarta[A2A Java SDK for Jakarta Servers] project can be used instead.
73+
74+
===== Multiple Transports
75+
76+
You can add dependencies on both `a2a-java-sdk-reference-jsonrpc` and `a2a-java-sdk-reference-grpc` if you'd like your A2A server agent to be able to communicate with clients using either transport.
77+
78+
Support for the HTTP+JSON/REST transport will also be added to the A2A Java SDK very soon, keep an eye out for that!
79+
80+
==== Declaring Supported Transports in the `AgentCard`
81+
82+
The `AgentCard` is a class that describes the capabilities of an A2A server agent. Other agents or clients will use this to understand what our agent can do. Once you've added one or more dependencies on the A2A Java SDK Server Reference implementations, the next step is to add a class that creates an `AgentCard`.
83+
84+
When creating your `AgentCard`, you must specify the primary endpoint for your A2A server agent and if your server agent supports multiple transports, these need to be specified as additional interfaces in your `AgentCard` as shown in the example below:
85+
86+
[source,java]
87+
----
88+
import io.a2a.server.PublicAgentCard;
89+
import io.a2a.spec.AgentCapabilities;
90+
import io.a2a.spec.AgentCard;
91+
import io.a2a.spec.AgentSkill;
92+
...
93+
94+
@ApplicationScoped
95+
public class WeatherAgentCardProducer {
96+
97+
@Produces
98+
@PublicAgentCard
99+
public AgentCard agentCard() {
100+
return new AgentCard.Builder()
101+
.name("Weather Agent")
102+
.description("Helps with weather")
103+
.url("http://localhost:10001") <1>
104+
.preferredTransport(TransportProtocol.JSONRPC.asString()) <2>
105+
.additionalInterfaces(List.of( <3>
106+
new AgentInterface(TransportProtocol.JSONRPC.asString(), "http://localhost:10001"), <4>
107+
new AgentInterface(TransportProtocol.GRPC.asString(), "localhost:9000") <5>
108+
))
109+
.version("1.0.0")
110+
.capabilities(new AgentCapabilities.Builder()
111+
.streaming(true)
112+
.pushNotifications(false)
113+
.stateTransitionHistory(false)
114+
.build())
115+
.defaultInputModes(Collections.singletonList("text"))
116+
.defaultOutputModes(Collections.singletonList("text"))
117+
.skills(Collections.singletonList(new AgentSkill.Builder()
118+
.id("weather_search")
119+
.name("Search weather")
120+
.description("Helps with weather in city, or states")
121+
.tags(Collections.singletonList("weather"))
122+
.examples(List.of("weather in LA, CA"))
123+
.build()))
124+
.protocolVersion("0.3.0")
125+
.build();
126+
}
127+
}
128+
----
129+
<1> The primary endpoint URL for our A2A server agent, `http://localhost:10001` in this example.
130+
<2> The preferred transport for our A2A server agent, `JSON-RPC` in this example. This is the transport protocol available at the primary endpoint URL.
131+
<3> The optional additional interfaces supported by our A2A server agent. This should include all supported transports.
132+
<4> The primary endpoint URL should also be specified here for completeness.
133+
<5> The gRPC transport URL, `localhost:9000`, indicating that our A2A server agent also supports gRPC.
134+
135+
=== A2A Client Updates
136+
137+
To make use of an A2A client using the A2A Java SDK, add the following dependency to your project:
138+
139+
[source,xml]
140+
----
141+
<dependency>
142+
<groupId>io.github.a2asdk</groupId>
143+
<artifactId>a2a-java-sdk-client</artifactId> <1>
144+
</dependency>
145+
----
146+
<1> The `a2a-java-sdk-client` dependency provides access to a `ClientBuilder` that you can use to create your A2A `Client`.
147+
148+
==== Supported Transports
149+
150+
The A2A Java SDK client implementation now supports the gRPC transport protocol in addition to JSON-RPC.
151+
152+
As mentioned previously, support for the HTTP+JSON/REST transport will be coming soon!
153+
154+
===== JSON-RPC 2.0 Transport
155+
156+
To allow your client to support the JSON-RPC transport for communication, just `a2a-java-sdk-client` is needed. No additional dependencies need to be manually added to your project.
157+
158+
===== gRPC Transport
159+
160+
To allow your client to support the gRPC transport for communication, simply add the following dependency to your project:
161+
162+
[source,xml]
163+
----
164+
<dependency>
165+
<groupId>io.github.a2asdk</groupId>
166+
<artifactId>a2a-java-sdk-client-transport-grpc</artifactId>
167+
</dependency>
168+
----
169+
170+
==== Creating a `Client`
171+
172+
An A2A `Client` can now be created using a `ClientBuilder`. The `ClientBuilder` will select the appropriate transport protocol to use based on information obtained from the `AgentCard` for the A2A server agent that this client will be communicating with, also taking into account client-specified transport configuration. The `ClientBuilder` will then create a `Client` that will use the selected transport to communicate with the A2A server and the `Client` will also make use of any other client-specified configuration like whether to use streaming (`true` by default), accepted output modes, history length for messages, and so on.
173+
174+
We want to give a shoutout to David Brassely, one of our community contributors, for working with us on improving the `Client` creation experience!
175+
176+
Let's take a look at an example to see how a `Client` can now be created using the `ClientBuilder`:
177+
178+
[source,java]
179+
----
180+
// First, get the agent card for the A2A server agent you want to connect to
181+
AgentCard agentCard = new A2ACardResolver("http://localhost:1234").getAgentCard();
182+
183+
// Specify general client configuration and preferences for the ClientBuilder
184+
ClientConfig clientConfig = new ClientConfig.Builder()
185+
.setAcceptedOutputModes(List.of("text"))
186+
...
187+
.build();
188+
189+
// Create event consumers to handle responses that will be received from the A2A server
190+
// (these consumers will be used for both streaming and non-streaming responses)
191+
List<BiConsumer<ClientEvent, AgentCard>> consumers = List.of(
192+
(event, card) -> {
193+
if (event instanceof MessageEvent messageEvent) {
194+
// handle the messageEvent.getMessage()
195+
...
196+
} else if (event instanceof TaskEvent taskEvent) {
197+
// handle the taskEvent.getTask()
198+
...
199+
} else if (event instanceof TaskUpdateEvent updateEvent) {
200+
// handle the updateEvent.getTask()
201+
...
202+
}
203+
}
204+
);
205+
206+
// Create a handler that will be used for any errors that occur during streaming
207+
Consumer<Throwable> errorHandler = error -> {
208+
// handle the error.getMessage()
209+
...
210+
};
211+
212+
// Optional: Create a channel factory function that takes the agent URL and returns a Channel for gRPC
213+
Function<String, Channel> channelFactory = agentUrl -> {
214+
return ManagedChannelBuilder.forTarget(agentUrl)
215+
...
216+
.build();
217+
};
218+
219+
// Create the client using the builder
220+
Client client = Client
221+
.builder(agentCard)
222+
.clientConfig(clientConfig)
223+
.withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig()) <1>
224+
.withTransport(GrpcTransport.class, new GrpcTransportConfig(channelFactory)) <2>
225+
.addConsumers(consumers)
226+
.streamingErrorHandler(errorHandler)
227+
.build();
228+
----
229+
<1> This specifies that our client can support the `JSON-RPC` transport. At least one transport must be configured using the `withTransport` method.
230+
<2> This specifies that our client can support the `gRPC` transport.
231+
232+
Once created, the `Client` can be used to send messages, get the current state of a task, cancel an ongoing task, get, set, and delete push notification configuration, and resubscribe to a task.
233+
234+
== Conclusion
235+
236+
We've taken a look at the key updates in A2A Java SDK 0.3.0, including the new gRPC transport and changes to how you configure both A2A server agents and A2A clients. To quickly get started creating your own A2A agents with Quarkus, check out the resources below.
237+
238+
=== Further Reading
239+
240+
* https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents[A2A Java SDK Samples]
241+
* https://github.com/a2aproject/a2a-java/blob/main/README.md[A2A Java SDK Documentation]
242+
* https://a2aproject.github.io/A2A/specification/[A2A Specification]
243+
244+

0 commit comments

Comments
 (0)