A2A Java SDK

A Java library that helps run agentic applications as A2AServers following the Agent2Agent (A2A) Protocol.

Installation

You can build the A2A Java SDK using mvn:

mvn clean install

Regeneration of gRPC files

We copy https://github.com/a2aproject/A2A/blob/main/specification/grpc/a2a.proto to the spec-grpc/ project, and adjust the java_package option to be as follows:

option java_package = "io.a2a.grpc";

Then build the spec-grpc module with mvn clean install -Pproto-compile to regenerate the gRPC classes in the io.a2a.grpc package.

Examples

You can find examples of how to use the A2A Java SDK in the a2a-samples repository.

More examples will be added soon.

A2A Server

The A2A Java SDK provides a Java server implementation of the Agent2Agent (A2A) Protocol. To run your agentic Java application as an A2A server, simply follow the steps below.

• Add an A2A Java SDK Server Maven dependency to your project
• Add a class that creates an A2A Agent Card
• Add a class that creates an A2A Agent Executor

1. Add an A2A Java SDK Reference Server dependency to your project

Adding a dependency on an A2A Java SDK Reference Server will provide access to the core classes that make up the A2A specification and allow you to run your agentic Java application as an A2A server agent.

The A2A Java SDK provides reference A2A server implementations based on Quarkus for use with our tests and examples. However, the project is designed in such a way that it is trivial to integrate with various Java runtimes.

Server Integrations contains a list of community contributed integrations of the server with various runtimes. You might be able to use one of these for your target runtime, or you can use them as inspiration to create your own.

Server Transports

The A2A Java SDK Reference Server implementations support the following transports:

• JSON-RPC 2.0
• gRPC
• HTTP+JSON/REST

To use the reference implementation with the JSON-RPC protocol, add the following dependency to your project:

⚠️ The io.github.a2asdkgroupId below is temporary and will likely change for future releases.

<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>
<!-- Use a released version from https://github.com/a2aproject/a2a-java/releases --> <version>${io.a2a.sdk.version}</version>
</dependency>

To use the reference implementation with the gRPC protocol, add the following dependency to your project:

⚠️ The io.github.a2asdkgroupId below is temporary and will likely change for future releases.

<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-reference-grpc</artifactId>
<!-- Use a released version from https://github.com/a2aproject/a2a-java/releases --> <version>${io.a2a.sdk.version}</version>
</dependency>

To use the reference implementation with the HTTP+JSON/REST protocol, add the following dependency to your project:

⚠️ The io.github.a2asdkgroupId below is temporary and will likely change for future releases.

<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-reference-rest</artifactId>
<!-- Use a released version from https://github.com/a2aproject/a2a-java/releases --> <version>${io.a2a.sdk.version}</version>
</dependency>

Note that you can add more than one of the above dependencies to your project depending on the transports you'd like to support.

2. Add a class that creates an A2A Agent Card

importio.a2a.server.PublicAgentCard;
importio.a2a.spec.AgentCapabilities;
importio.a2a.spec.AgentCard;
importio.a2a.spec.AgentSkill;
...
@ApplicationScopedpublicclassWeatherAgentCardProducer {
@Produces@PublicAgentCardpublicAgentCardagentCard() {
returnnewAgentCard.Builder()
.name("Weather Agent")
.description("Helps with weather")
.url("http://localhost:10001")
.version("1.0.0")
.capabilities(newAgentCapabilities.Builder()
.streaming(true)
.pushNotifications(false)
.stateTransitionHistory(false)
.build())
.defaultInputModes(Collections.singletonList("text"))
.defaultOutputModes(Collections.singletonList("text"))
.skills(Collections.singletonList(newAgentSkill.Builder()
.id("weather_search")
.name("Search weather")
.description("Helps with weather in city, or states")
.tags(Collections.singletonList("weather"))
.examples(List.of("weather in LA, CA"))
.build()))
.protocolVersion("0.3.0")
.build();
}
}

3. Add a class that creates an A2A Agent Executor

importio.a2a.server.agentexecution.AgentExecutor;
importio.a2a.server.agentexecution.RequestContext;
importio.a2a.server.events.EventQueue;
importio.a2a.server.tasks.TaskUpdater;
importio.a2a.spec.JSONRPCError;
importio.a2a.spec.Message;
importio.a2a.spec.Part;
importio.a2a.spec.Task;
importio.a2a.spec.TaskNotCancelableError;
importio.a2a.spec.TaskState;
importio.a2a.spec.TextPart;
...
@ApplicationScopedpublicclassWeatherAgentExecutorProducer {
@InjectWeatherAgentweatherAgent;
@ProducespublicAgentExecutoragentExecutor() {
returnnewWeatherAgentExecutor(weatherAgent);
}
privatestaticclassWeatherAgentExecutorimplementsAgentExecutor {
privatefinalWeatherAgentweatherAgent;
publicWeatherAgentExecutor(WeatherAgentweatherAgent) {
this.weatherAgent = weatherAgent;
}
@Overridepublicvoidexecute(RequestContextcontext, EventQueueeventQueue) throwsJSONRPCError {
TaskUpdaterupdater = newTaskUpdater(context, eventQueue);
// mark the task as submitted and start working on itif (context.getTask() == null) {
updater.submit();
}
updater.startWork();
// extract the text from the messageStringuserMessage = extractTextFromMessage(context.getMessage());
// call the weather agent with the user's messageStringresponse = weatherAgent.chat(userMessage);
// create the response partTextPartresponsePart = newTextPart(response, null);
List<Part<?>> parts = List.of(responsePart);
// add the response as an artifact and complete the taskupdater.addArtifact(parts, null, null, null);
updater.complete();
}
@Overridepublicvoidcancel(RequestContextcontext, EventQueueeventQueue) throwsJSONRPCError {
Tasktask = context.getTask();
if (task.getStatus().state() == TaskState.CANCELED) {
// task already cancelledthrownewTaskNotCancelableError();
}
if (task.getStatus().state() == TaskState.COMPLETED) {
// task already completedthrownewTaskNotCancelableError();
}
// cancel the taskTaskUpdaterupdater = newTaskUpdater(context, eventQueue);
updater.cancel();
}
privateStringextractTextFromMessage(Messagemessage) {
StringBuildertextBuilder = newStringBuilder();
if (message.getParts() != null) {
for (Partpart : message.getParts()) {
if (partinstanceofTextParttextPart) {
textBuilder.append(textPart.getText());
}
}
}
returntextBuilder.toString();
}
}
}

A2A Client

The A2A Java SDK provides a Java client implementation of the Agent2Agent (A2A) Protocol, allowing communication with A2A servers. The Java client implementation supports the following transports:

• JSON-RPC 2.0
• gRPC
• HTTP+JSON/REST

To make use of the Java Client:

1. Add the A2A Java SDK Client dependency to your project

Adding a dependency on a2a-java-sdk-client will provide access to a ClientBuilder that you can use to create your A2A Client.

---

⚠️ The io.github.a2asdkgroupId below is temporary and will likely change for future releases.

---

<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-client</artifactId>
<!-- Use a released version from https://github.com/a2aproject/a2a-java/releases -->
<version>${io.a2a.sdk.version}</version>
</dependency>

2. Add one or more dependencies on the A2A Java SDK Client Transport(s) you'd like to use

By default, the sdk-client is coming with the JSONRPC transport dependency. Despite the fact that the JSONRPC transport dependency is included by default, you still need to add the transport to the Client as described in JSON-RPC Transport section.

If you want to use the gRPC transport, you'll need to add a relevant dependency:

---

⚠️ The io.github.a2asdkgroupId below is temporary and will likely change for future releases.

---

<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-client-transport-grpc</artifactId>
<!-- Use a released version from https://github.com/a2aproject/a2a-java/releases -->
<version>${io.a2a.sdk.version}</version>
</dependency>

If you want to use the HTTP+JSON/REST transport, you'll need to add a relevant dependency:

---

⚠️ The io.github.a2asdkgroupId below is temporary and will likely change for future releases.

---

<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-client-transport-rest</artifactId>
<!-- Use a released version from https://github.com/a2aproject/a2a-java/releases -->
<version>${io.a2a.sdk.version}</version>
</dependency>

Sample Usage

Create a Client using the ClientBuilder

// First, get the agent card for the A2A server agent you want to connect toAgentCardagentCard = newA2ACardResolver("http://localhost:1234").getAgentCard();
// Specify configuration for the ClientBuilderClientConfigclientConfig = newClientConfig.Builder()
.setAcceptedOutputModes(List.of("text"))
.build();
// Create event consumers to handle responses that will be received from the A2A server// (these consumers will be used for both streaming and non-streaming responses)List<BiConsumer<ClientEvent, AgentCard>> consumers = List.of(
(event, card) -> {
if (eventinstanceofMessageEventmessageEvent) {
// handle the messageEvent.getMessage()
...
} elseif (eventinstanceofTaskEventtaskEvent) {
// handle the taskEvent.getTask()
...
} elseif (eventinstanceofTaskUpdateEventupdateEvent) {
// handle the updateEvent.getTask()
...
}
}
);
// Create a handler that will be used for any errors that occur during streamingConsumer<Throwable> errorHandler = error -> {
// handle the error.getMessage()
...
};
// Create the client using the builderClientclient = Client
.builder(agentCard)
.clientConfig(clientConfig)
.withTransport(JSONRPCTransport.class, newJSONRPCTransportConfig())
.addConsumers(consumers)
.streamingErrorHandler(errorHandler)
.build();

Configuring Transport-Specific Settings

Different transport protocols can be configured with specific settings using specific ClientTransportConfig implementations. The A2A Java SDK provides JSONRPCTransportConfig for the JSON-RPC transport and GrpcTransportConfig for the gRPC transport.

JSON-RPC Transport Configuration

For the JSON-RPC transport, to use the default JdkA2AHttpClient, provide a JSONRPCTransportConfig created with its default constructor.

To use a custom HTTP client implementation, simply create a JSONRPCTransportConfig as follows:

// Create a custom HTTP clientA2AHttpClientcustomHttpClient = ...
// Configure the client settingsClientConfigclientConfig = newClientConfig.Builder()
.setAcceptedOutputModes(List.of("text"))
.build();
Clientclient = Client
.builder(agentCard)
.clientConfig(clientConfig)
.withTransport(JSONRPCTransport.class, newJSONRPCTransportConfig(customHttpClient))
.build();

gRPC Transport Configuration

For the gRPC transport, you must configure a channel factory:

// Create a channel factory function that takes the agent URL and returns a ChannelFunction<String, Channel> channelFactory = agentUrl -> {
returnManagedChannelBuilder.forTarget(agentUrl)
...
.build();
};
// Configure the client with transport-specific settingsClientConfigclientConfig = newClientConfig.Builder()
.setAcceptedOutputModes(List.of("text"))
.build();
Clientclient = Client
.builder(agentCard)
.clientConfig(clientConfig)
.withTransport(GrpcTransport.class, newGrpcTransportConfig(channelFactory))
.build();

HTTP+JSON/REST Transport Configuration

For the HTTP+JSON/REST transport, if you'd like to use the default JdkA2AHttpClient, provide a RestTransportConfig created with its default constructor.

To use a custom HTTP client implementation, simply create a RestTransportConfig as follows:

// Create a custom HTTP clientA2AHttpClientcustomHttpClient = ...
// Configure the client settingsClientConfigclientConfig = newClientConfig.Builder()
.setAcceptedOutputModes(List.of("text"))
.build();
Clientclient = Client
.builder(agentCard)
.clientConfig(clientConfig)
.withTransport(RestTransport.class, newRestTransportConfig(customHttpClient))
.build();

Multiple Transport Configurations

You can specify configuration for multiple transports, the appropriate configuration will be used based on the selected transport:

// Configure both JSON-RPC and gRPC transportsClientclient = Client
.builder(agentCard)
.withTransport(GrpcTransport.class, newGrpcTransportConfig(channelFactory))
.withTransport(JSONRPCTransport.class, newJSONRPCTransportConfig())
.withTransport(RestTransport.class, newRestTransportConfig())
.build();

Send a message to the A2A server agent

// Send a text message to the A2A server agentMessagemessage = A2A.toUserMessage("tell me a joke");
// Send the message (uses configured consumers to handle responses)// Streaming will automatically be used if supported by both client and server,// otherwise the non-streaming send message method will be used automaticallyclient.sendMessage(message);
// You can also optionally specify a ClientCallContext with call-specific config to useclient.sendMessage(message, clientCallContext);

Send a message with custom event handling

// Create custom consumers for this specific messageList<BiConsumer<ClientEvent, AgentCard>> customConsumers = List.of(
(event, card) -> {
// handle this specific message's responses
...
}
);
// Create custom error handlerConsumer<Throwable> customErrorHandler = error -> {
// handle the error
...
};
Messagemessage = A2A.toUserMessage("tell me a joke");
client.sendMessage(message, customConsumers, customErrorHandler);

Get the current state of a task

// Retrieve the task with id "task-1234"Tasktask = client.getTask(newTaskQueryParams("task-1234"));
// You can also specify the maximum number of items of history for the task// to include in the response and Tasktask = client.getTask(newTaskQueryParams("task-1234", 10));
// You can also optionally specify a ClientCallContext with call-specific config to useTasktask = client.getTask(newTaskQueryParams("task-1234"), clientCallContext);

Cancel an ongoing task

// Cancel the task we previously submitted with id "task-1234"TaskcancelledTask = client.cancelTask(newTaskIdParams("task-1234"));
// You can also specify additional properties using a mapMap<String, Object> metadata = Map.of("reason", "user_requested");
TaskcancelledTask = client.cancelTask(newTaskIdParams("task-1234", metadata));
// You can also optionally specify a ClientCallContext with call-specific config to useTaskcancelledTask = client.cancelTask(newTaskIdParams("task-1234"), clientCallContext);

Get a push notification configuration for a task

// Get task push notification configurationTaskPushNotificationConfigconfig = client.getTaskPushNotificationConfiguration(
newGetTaskPushNotificationConfigParams("task-1234"));
// The push notification configuration ID can also be optionally specifiedTaskPushNotificationConfigconfig = client.getTaskPushNotificationConfiguration(
newGetTaskPushNotificationConfigParams("task-1234", "config-4567"));
// Additional properties can be specified using a mapMap<String, Object> metadata = Map.of("source", "client");
TaskPushNotificationConfigconfig = client.getTaskPushNotificationConfiguration(
newGetTaskPushNotificationConfigParams("task-1234", "config-1234", metadata));
// You can also optionally specify a ClientCallContext with call-specific config to useTaskPushNotificationConfigconfig = client.getTaskPushNotificationConfiguration(
newGetTaskPushNotificationConfigParams("task-1234"), clientCallContext);

Set a push notification configuration for a task

// Set task push notification configurationPushNotificationConfigpushNotificationConfig = newPushNotificationConfig.Builder()
.url("https://example.com/callback")
.authenticationInfo(newAuthenticationInfo(Collections.singletonList("jwt"), null))
.build();
TaskPushNotificationConfigtaskConfig = newTaskPushNotificationConfig.Builder()
.taskId("task-1234")
.pushNotificationConfig(pushNotificationConfig)
.build();
TaskPushNotificationConfigresult = client.setTaskPushNotificationConfiguration(taskConfig);
// You can also optionally specify a ClientCallContext with call-specific config to useTaskPushNotificationConfigresult = client.setTaskPushNotificationConfiguration(taskConfig, clientCallContext);

List the push notification configurations for a task

List<TaskPushNotificationConfig> configs = client.listTaskPushNotificationConfigurations(
newListTaskPushNotificationConfigParams("task-1234"));
// Additional properties can be specified using a mapMap<String, Object> metadata = Map.of("filter", "active");
List<TaskPushNotificationConfig> configs = client.listTaskPushNotificationConfigurations(
newListTaskPushNotificationConfigParams("task-1234", metadata));
// You can also optionally specify a ClientCallContext with call-specific config to useList<TaskPushNotificationConfig> configs = client.listTaskPushNotificationConfigurations(
newListTaskPushNotificationConfigParams("task-1234"), clientCallContext);

Delete a push notification configuration for a task

client.deleteTaskPushNotificationConfigurations(
newDeleteTaskPushNotificationConfigParams("task-1234", "config-4567"));
// Additional properties can be specified using a mapMap<String, Object> metadata = Map.of("reason", "cleanup");
client.deleteTaskPushNotificationConfigurations(
newDeleteTaskPushNotificationConfigParams("task-1234", "config-4567", metadata));
// You can also optionally specify a ClientCallContext with call-specific config to useclient.deleteTaskPushNotificationConfigurations(
newDeleteTaskPushNotificationConfigParams("task-1234", "config-4567", clientCallContext);

Resubscribe to a task

// Resubscribe to an ongoing task with id "task-1234" using configured consumersTaskIdParamstaskIdParams = newTaskIdParams("task-1234");
client.resubscribe(taskIdParams);
// Or resubscribe with custom consumers and error handlerList<BiConsumer<ClientEvent, AgentCard>> customConsumers = List.of(
(event, card) -> System.out.println("Resubscribe event: " + event)
);
Consumer<Throwable> customErrorHandler = error -> System.err.println("Resubscribe error: " + error.getMessage());
client.resubscribe(taskIdParams, customConsumers, customErrorHandler);
// You can also optionally specify a ClientCallContext with call-specific config to useclient.resubscribe(taskIdParams, clientCallContext);

Retrieve details about the server agent that this client agent is communicating with

AgentCardserverAgentCard = client.getAgentCard();

Additional Examples

Hello World Client Example

A complete example of a Java A2A client communicating with a Python A2A server is available in the examples/helloworld/client directory. This example demonstrates:

• Setting up and using the A2A Java client
• Sending regular and streaming messages to a Python A2A server
• Receiving and processing responses from the Python A2A server

The example includes detailed instructions on how to run the Python A2A server and how to run the Java A2A client using JBang.

Check out the example's README for more information.

Hello World Server Example

A complete example of a Python A2A client communicating with a Java A2A server is available in the examples/helloworld/server directory. This example demonstrates:

• A sample AgentCard producer
• A sample AgentExecutor producer
• A Java A2A server receiving regular and streaming messages from a Python A2A client

Check out the example's README for more information.

Community Articles

See COMMUNITY_ARTICLES.md for a list of community articles and videos.

License

This project is licensed under the terms of the Apache 2.0 License.

Contributing

See CONTRIBUTING.md for contribution guidelines.

Server Integrations

The following list contains community contributed integrations with various Java Runtimes.

To contribute an integration, please see CONTRIBUTING_INTEGRATIONS.md.

• reference/jsonrpc/README.md - JSON-RPC 2.0 Reference implementation, based on Quarkus.
• reference/grpc/README.md - gRPC Reference implementation, based on Quarkus.
• https://github.com/wildfly-extras/a2a-java-sdk-server-jakarta - This integration is based on Jakarta EE, and should work in all runtimes supporting the Jakarta EE Web Profile.

Extras

See the extras folder for extra functionality not provided by the SDK itself!