Java SDK

The AG-UI Java SDK is a modular library for the Agent User Interaction Protocol. You can use it to call a remote AG-UI agent from Java, to serve your own agent to any AG-UI front end, or both. Note: This SDK is community contributed and maintained. Source code lives in sdks/community/java. The SDK is built around a few design choices:

Plain JDK streaming. An agent run is a java.util.concurrent.Flow.Publisher<Event>, the Reactive Streams interface that ships with the JDK. The core needs no Reactor, RxJava or coroutines, and you can adapt the publisher to any of them.
No runtime dependencies in the core. java-core, java-client and java-server depend only on the JDK. JSON goes through a Serializer interface that you plug in. A ready-made Jackson implementation is available.
Sealed, record-based model. Event and Message are sealed interfaces implemented by records, so you can handle them with an exhaustive switch.
Transport-neutral server. The server core does not depend on any HTTP framework. It ships an adapter for the JDK’s built-in HTTP server, and separate Spring WebFlux, Spring WebMVC and Spring AI integrations.

Requirements

Java 17 or later
For the Spring modules: Spring Boot 4.1.x, and Spring AI 2.x for the Spring AI modules

Modules

All artifacts are published to Maven Central under the com.ag-ui.community group ID.

Core library

Artifact	Version	Description
`java-core`	`0.1.1`	Protocol types: `Agent`, `RunAgentInput`, messages, tools, events, interrupts, and the `Serializer` interface.
`java-client`	`0.1.1`	`HttpAgent`, an `Agent` that calls a remote AG-UI endpoint over HTTP and SSE using the JDK `HttpClient`.
`java-server`	`0.1.1`	Transport-neutral server machinery and a handler for the JDK’s built-in `HttpServer`.

Spring integration

Artifact	Version	Description
`ag-ui-spring-server-core`	`4.1.0`	`JacksonSerializer`, a Jackson-backed `Serializer`. It has no Spring dependency, so you can also use it outside Spring.
`ag-ui-spring-webflux-server`	`4.1.0`	Reactive (WebFlux) SSE endpoint plus auto-configuration.
`ag-ui-spring-webmvc-server`	`4.1.0`	Servlet (WebMVC) SSE endpoint plus auto-configuration.
`ag-ui-spring-webflux-boot-starter`	`4.1.0`	Starter: add it, define an `Agent` bean, and get a reactive `/agent` endpoint.
`ag-ui-spring-webmvc-boot-starter`	`4.1.0`	Starter: the Servlet equivalent of the WebFlux starter.
`ag-ui-spring-ai`	`2.0.0`	`SpringAiAgent`, which adapts a Spring AI `ChatClient` into an AG-UI `Agent`.
`ag-ui-spring-ai-spring-boot-starter`	`2.0.0`	Starter that exposes a Spring AI model at `/agent` over WebFlux without any application code.
`ag-ui-spring-ai-webmvc-boot-starter`	`2.0.0`	Starter: the Servlet equivalent of the Spring AI starter.

The Spring modules are versioned in two lines. The Spring Boot line follows the Spring Boot version it targets, and the Spring AI line follows the Spring AI version.

Installation

Add the modules you need. java-client and java-server pull in java-core transitively.

<!-- Call a remote agent -->
<dependency>
  <groupId>com.ag-ui.community</groupId>
  <artifactId>java-client</artifactId>
  <version>0.1.1</version>
</dependency>

<!-- Serve an agent -->
<dependency>
  <groupId>com.ag-ui.community</groupId>
  <artifactId>java-server</artifactId>
  <version>0.1.1</version>
</dependency>

<!-- A Jackson-backed Serializer (no Spring required) -->
<dependency>
  <groupId>com.ag-ui.community</groupId>
  <artifactId>ag-ui-spring-server-core</artifactId>
  <version>4.1.0</version>
</dependency>

With Gradle:

dependencies {
    implementation("com.ag-ui.community:java-client:0.1.1")
    implementation("com.ag-ui.community:java-server:0.1.1")
    implementation("com.ag-ui.community:ag-ui-spring-server-core:4.1.0")
}

Quick start

Implement an agent

Agent is a functional interface. It takes a RunAgentInput and returns a Flow.Publisher<Event>. Each subscription to that publisher is one run. The JDK’s SubmissionPublisher is the simplest way to produce events:

import com.agui.community.core.agent.Agent;
import com.agui.community.core.event.*;
import com.agui.community.core.message.Role;

import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.SubmissionPublisher;

Agent echoAgent = input -> subscriber -> {
    SubmissionPublisher<Event> publisher = new SubmissionPublisher<>();
    publisher.subscribe(subscriber);
    CompletableFuture.runAsync(() -> {
        try {
            String messageId = UUID.randomUUID().toString();
            String lastUserMessage = input.messages().isEmpty()
                    ? "" : input.messages().get(input.messages().size() - 1).content();

            publisher.submit(new RunStartedEvent(input.threadId(), input.runId()));
            publisher.submit(new TextMessageStartEvent(messageId, Role.ASSISTANT));
            publisher.submit(new TextMessageContentEvent(messageId, "You said: " + lastUserMessage));
            publisher.submit(new TextMessageEndEvent(messageId));
            publisher.submit(new RunFinishedEvent(input.threadId(), input.runId()));
            publisher.close();
        } catch (Exception e) {
            publisher.closeExceptionally(e);
        }
    });
};

Serve it

The JDK’s built-in HTTP server is enough to expose the agent as an SSE endpoint:

import com.agui.community.core.serialization.Serializer;
import com.agui.community.server.jdk.JdkAgentHttpHandler;
import com.agui.community.spring.server.core.JacksonSerializer;
import com.sun.net.httpserver.HttpServer;

import java.net.InetSocketAddress;

Serializer serializer = new JacksonSerializer();

HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
server.createContext("/agent", new JdkAgentHttpHandler(echoAgent, serializer));
server.start();

Any AG-UI client can now POST a RunAgentInput to http://localhost:8080/agent.

Call it

HttpAgent is the client side. It is also an Agent, so it is consumed the same way as a local agent:

import com.agui.community.client.HttpAgent;
import com.agui.community.core.agent.RunAgentInput;
import com.agui.community.core.message.UserMessage;

import java.net.URI;
import java.util.List;
import java.util.concurrent.Flow;

Agent agent = new HttpAgent(URI.create("http://localhost:8080/agent"), serializer);

RunAgentInput input = new RunAgentInput(
        "thread-1", "run-1",
        List.of(new UserMessage("msg-1", "Hello!")),
        List.of());

agent.run(input).subscribe(new Flow.Subscriber<>() {
    @Override public void onSubscribe(Flow.Subscription s) { s.request(Long.MAX_VALUE); }
    @Override public void onNext(Event event) {
        if (event instanceof TextMessageContentEvent text) {
            System.out.print(text.delta());
        }
    }
    @Override public void onError(Throwable t) { t.printStackTrace(); }
    @Override public void onComplete() { System.out.println(); }
});

Use Spring AI without writing code

To serve an LLM through Spring AI, add ag-ui-spring-ai-spring-boot-starter (or ag-ui-spring-ai-webmvc-boot-starter for a Servlet app) together with a Spring AI model starter such as spring-ai-starter-model-openai. A SpringAiAgent is registered from the auto-configured ChatClient.Builder and served at /agent. See Spring AI.

Next steps

Core: the Agent interface, streaming, and serialization
Types: RunAgentInput, messages, tools, and interrupts
Events: every event record and its fields
Client: calling remote agents with HttpAgent
Server: serving agents with the JDK server or your own transport
Spring: WebFlux and WebMVC endpoints and starters
Spring AI: turning a ChatClient into an AG-UI agent

TypeScript

Python

.NET

Java SDK Overview

Java SDK

Requirements

Modules

Core library

Spring integration

Installation

Quick start

Implement an agent

Serve it

Call it

Use Spring AI without writing code

Next steps

​Java SDK

​Requirements

​Modules

​Core library

​Spring integration

​Installation

​Quick start

​Implement an agent

​Serve it

​Call it

​Use Spring AI without writing code

​Next steps

Java SDK

Requirements

Modules

Core library

Spring integration

Installation

Quick start

Implement an agent

Serve it

Call it

Use Spring AI without writing code

Next steps