TESTING: Feat: Added Java SDK

.github/workflows/test.yml

@@ -190,3 +190,25 @@ jobs:
         else
           echo "✅ All $total_tests tests passed!"
         fi
+
+  java:
+    name: Java SDK Tests
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: sdks/community/java
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Java
+      uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+        cache: 'maven'
+
+    - name: Run tests
+      run: mvn -B -ntp test

docs/docs.json

@@ -108,6 +108,38 @@
                 "pages": ["sdk/python/encoder/overview"]
               }
             ]
+          },
+          {
+            "group": "Java",
+            "pages": [
+              "sdk/java/overview",
+              {
+                "group": "Core",
+                "pages": [
+                  "sdk/java/core/overview",
+                  "sdk/java/core/types",
+                  "sdk/java/core/events",
+                  "sdk/java/core/stream",
+                  "sdk/java/core/subscription"
+                ]
+              },
+              {
+                "group": "Client",
+                "pages": [
+                  "sdk/java/client/overview",
+                  "sdk/java/client/abstract-agent",
+                  "sdk/java/client/http-agent",
+                  "sdk/java/client/subscriber"
+                ]
+              },
+              {
+                "group": "Server",
+                "pages": [
+                  "sdk/java/server/overview",
+                  "sdk/java/server/spring"
+                ]
+              }
+            ]
           }
         ]
       }
@@ -123,6 +155,11 @@
           "anchor": "Python SDK",
           "href": "https://docs.ag-ui.com/sdk/python/core/overview",
           "icon": "python"
+        },
+        {
+          "anchor": "Java SDK",
+          "href": "http://localhost:4000/sdk/java/overview",
+          "icon": "java"
         }
       ]
     }

docs/sdk/java/client/abstract-agent.mdx

@@ -0,0 +1,55 @@
+---
+title: "AbstractAgent"
+description: "Base agent implementation with core event handling (Java)"
+---
+
+# AbstractAgent
+
+The `AbstractAgent` class provides the foundation for agent implementations. It handles event stream processing, state management, and message history. Extend it and implement `protected void run(RunAgentInput input, IEventStream<BaseEvent> stream)`.
+
+## Example Implementation
+
+```java
+public class MyAgent extends AbstractAgent {
+  public MyAgent() {
+    super("my-agent", "A custom agent", "thread-123", List.of(), new State(), false);
+  }
+
+  @Override
+  protected void run(RunAgentInput input, IEventStream<BaseEvent> stream) {
+    // Emit events using the stream
+    stream.next(new RunStartedEvent(input.getThreadId(), input.getRunId()));
+
+    // Your agent logic here...
+
+    stream.next(new RunFinishedEvent(input.getThreadId(), input.getRunId()));
+  }
+}
+```
+
+## Configuration
+
+Constructors take: `agentId`, `description`, `threadId`, `initialMessages`, `state`, `debug`.
+
+## Core Methods
+
+- `CompletableFuture<Void> runAgent(RunAgentParameters parameters, AgentSubscriber subscriber)` — orchestrates an async run and event distribution
+- `Subscription subscribe(AgentSubscriber subscriber)` — persistent subscriber registration
+- `void addMessage(BaseMessage message)` / `void addMessages(List<BaseMessage>)`
+- `void setMessages(List<BaseMessage>)`
+- `void setState(State state)` / `State getState()`
+
+## Protected Methods
+
+- `protected abstract void run(RunAgentInput input, IEventStream<BaseEvent> stream)` — emit events into `stream`
+- `protected RunAgentInput prepareRunAgentInput(RunAgentParameters parameters)`
+- `protected void onInitialize(RunAgentInput input, List<AgentSubscriber> subscribers)`
+- `protected void handleEvent(BaseEvent event, List<AgentSubscriber> subscribers, AtomicReference<IEventStream<BaseEvent>> streamRef)`
+- `protected void handleComplete(List<AgentSubscriber> subscribers, RunAgentInput input, CompletableFuture<Void> future)`
+- `protected void handleError(Throwable error, List<AgentSubscriber> subscribers, CompletableFuture<Void> future)`
+
+### Text Message Helpers
+
+`handleTextMessageStart`, `handleTextMessageContent`, `handleTextMessageChunk`, `handleTextMessageEnd` integrate with `MessageFactory` to assemble streamed messages and notify subscribers.
+
+

docs/sdk/java/client/http-agent.mdx

@@ -0,0 +1,36 @@
+---
+title: "HttpAgent"
+description: "HTTP-based agent for connecting to remote AI agents (Java)"
+---
+
+# HttpAgent
+
+`HttpAgent` extends `AbstractAgent` to provide HTTP-based connectivity to remote AI agents. It delegates streaming to a `BaseHttpClient` implementation and forwards incoming events to subscribers.
+
+## Configuration
+
+Use the builder to construct an instance:
+
+```java
+HttpAgent agent = HttpAgent.builder()
+  .agentId("my-agent")
+  .threadId("thread-123")
+  .httpClient(myHttpClient)
+  .messages(new ArrayList<>())
+  .state(new State())
+  .debug(true)
+  .build();
+```
+
+Required: `agentId`, `threadId`, `httpClient`
+
+## Methods
+
+- `protected void run(RunAgentInput input, IEventStream<BaseEvent> stream)` — streams events via `httpClient.streamEvents`
+- `void close()` — closes the underlying HTTP client
+
+## Builder
+
+Fluent builder with validation. Required fields must be set or an `IllegalArgumentException` is thrown.
+
+

docs/sdk/java/client/overview.mdx

@@ -0,0 +1,65 @@
+---
+title: "Overview"
+description: "Client package overview for the Java SDK"
+---
+
+# ag-ui-client
+
+The Java Client SDK provides agent connectivity options for AI systems. It builds on the core types and events to deliver flexible connection methods to agent implementations.
+
+## AbstractAgent
+
+`AbstractAgent` is the base agent class for implementing custom agent connectivity. Extend this class and implement `run` to bridge your service to AG-UI.
+
+- Configuration — agent ID, messages, and state
+- Core Methods — runAgent, subscribe, message/state helpers
+- Protected Methods — event handling hooks
+- Properties — state and message tracking
+
+<Card
+  title="AbstractAgent Reference"
+  icon="cube"
+  href="/sdk/java/client/abstract-agent"
+  color="#3B82F6"
+  iconType="solid"
+>
+  Base class for creating custom agent connections
+</Card>
+
+## HttpAgent
+
+Concrete implementation for HTTP-based agent connectivity using an injected `BaseHttpClient` implementation.
+
+- Configuration — agentId, threadId, httpClient
+- Methods — run via HTTP streaming, close
+- Builder — fluent configuration with validation
+
+<Card
+  title="HttpAgent Reference"
+  icon="cube"
+  href="/sdk/java/client/http-agent"
+  color="#3B82F6"
+  iconType="solid"
+>
+  Ready-to-use HTTP implementation for agent connectivity
+</Card>
+
+## AgentSubscriber
+
+Event-driven subscriber system for handling agent lifecycle events and state mutations during execution.
+
+- Event Handlers — lifecycle, message, tool call, and state events
+- Usage Examples — logging, persistence, error handling patterns
+- Integration — register and use subscribers with agents
+
+<Card
+  title="AgentSubscriber Reference"
+  icon="bolt"
+  href="/sdk/java/client/subscriber"
+  color="#3B82F6"
+  iconType="solid"
+>
+  Comprehensive event system for reactive agent interaction
+</Card>
+
+

docs/sdk/java/client/subscriber.mdx

@@ -0,0 +1,35 @@
+---
+title: "AgentSubscriber"
+description: "Event subscriber interface for reactive agent interaction (Java)"
+---
+
+# AgentSubscriber
+
+Implement `AgentSubscriber` to handle lifecycle, message, tool call, and state events during agent execution.
+
+## Event Handlers
+
+- Request lifecycle: `onRunInitialized`, `onRunFailed`, `onRunFinalized`
+- Lifecycle events: `onRunStartedEvent`, `onRunFinishedEvent`, `onRunErrorEvent`, `onStepStartedEvent`, `onStepFinishedEvent`
+- Text messages: `onTextMessageStartEvent`, `onTextMessageContentEvent`, `onTextMessageEndEvent`
+- Tool calls: `onToolCallStartEvent`, `onToolCallArgsEvent`, `onToolCallEndEvent`, `onToolCallResultEvent`
+- State: `onStateSnapshotEvent`, `onStateDeltaEvent`, `onMessagesSnapshotEvent`, `onMessagesChanged`, `onStateChanged`
+- Special: `onRawEvent`, `onCustomEvent`, and catch-all `onEvent`
+
+## Usage Example
+
+```java
+agent.subscribe(new AgentSubscriber() {
+  @Override
+  public void onRunStartedEvent(RunStartedEvent event) {
+    System.out.println("Run started: " + event.getRunId());
+  }
+
+  @Override
+  public void onTextMessageContentEvent(TextMessageContentEvent event) {
+    System.out.print(event.getDelta());
+  }
+});
+```
+
+

docs/sdk/java/core/events.mdx

@@ -0,0 +1,44 @@
+---
+title: "Events"
+description: "Java event types used by the Agent User Interaction Protocol"
+---
+
+# Events
+
+All events live in `com.agui.core.event` and share `BaseEvent` with a `type` and `timestamp`.
+
+## Lifecycle Events
+
+- `RunStartedEvent`
+- `RunFinishedEvent`
+- `RunErrorEvent`
+- `StepStartedEvent`
+- `StepFinishedEvent`
+
+## Text Message Events
+
+- `TextMessageStartEvent` — Begin of a streamed assistant message
+- `TextMessageContentEvent` — Incremental content chunks (`delta`)
+- `TextMessageEndEvent` — Message finished
+
+## Tool Call Events
+
+- `ToolCallStartEvent`
+- `ToolCallArgsEvent`
+- `ToolCallEndEvent`
+- `ToolCallResultEvent`
+
+## State Management Events
+
+- `StateSnapshotEvent`
+- `StateDeltaEvent`
+- `MessagesSnapshotEvent`
+
+## Special Events
+
+- `RawEvent` — Raw payload passthrough
+- `CustomEvent` — Application-specific event
+
+See also: `AgentSubscriber` callbacks in the client docs for handling these events.
+
+

docs/sdk/java/core/overview.mdx

@@ -0,0 +1,59 @@
+---
+title: "Overview"
+description: "Core concepts in the Agent User Interaction Protocol SDK"
+---
+
+# ag-ui-core
+
+
+The Agent User Interaction Protocol SDK uses a streaming event-based
+architecture with strongly typed data structures. This package provides the
+foundation for connecting to agent systems.
+
+```xml
+<dependency>
+  <groupId>com.ag-ui</groupId>
+  <artifactId>core</artifactId>
+  <version>0.0.1</version>
+</dependency>
+```
+
+## Types
+
+Core data structures that represent the building blocks of the system:
+
+- RunAgentInput — Input parameters for running agents
+- Message — User/assistant communication and tool usage
+- Context — Contextual information provided to agents
+- Tool — Defines functions that agents can call
+- State — Agent state management
+
+<Card
+  title="Types Reference"
+  icon="cube"
+  href="/sdk/java/core/types"
+  color="#3B82F6"
+  iconType="solid"
+>
+  Complete documentation of core types in the Java SDK
+</Card>
+
+## Events
+
+Events that power communication between agents and frontends:
+
+- Lifecycle Events — Run and step tracking
+- Text Message Events — Assistant message streaming
+- Tool Call Events — Function call lifecycle
+- State Management Events — Agent state updates
+- Special Events — Raw and custom events
+
+<Card
+  title="Events Reference"
+  icon="cube"
+  href="/sdk/java/core/events"
+  color="#3B82F6"
+  iconType="solid"
+>
+  Complete documentation of all events in the Java SDK
+</Card>