Skip to content

Commit 324e4da

Browse files
pascalwilbrinkmaxkorp
pascalwilbrink
and
maxkorp
authored
Feat: Added Java SDK (#418)
* Feat: Added Java SDK * Added docs * update from workm8/ag-ui-4j * Updated docs (renamed io.workm8 to com.ag-ui) * Resolved merge conflicts * Delete added .DS_Store files and package-lock.json files * fix indenting in test.yml after merge conflict * Fixed parent pom, removed old examples * Fixed merge conflict, duplicate agno and llama-index in the dojo --------- Co-authored-by: Max Korp <[email protected]>
1 parent 9a47ff8 commit 324e4da

File tree

230 files changed

+33566
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

230 files changed

+33566
-3
lines changed

‎.DS_Store‎

-6 KB
Binary file not shown.

‎.github/workflows/test.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,3 +190,25 @@ jobs:
190190
else
191191
echo "✅ All $total_tests tests passed!"
192192
fi
193+
194+
java:
195+
name: Java SDK Tests
196+
runs-on: ubuntu-latest
197+
198+
defaults:
199+
run:
200+
working-directory: sdks/community/java
201+
202+
steps:
203+
- name: Checkout code
204+
uses: actions/checkout@v4
205+
206+
- name: Set up Java
207+
uses: actions/setup-java@v4
208+
with:
209+
distribution: 'temurin'
210+
java-version: '17'
211+
cache: 'maven'
212+
213+
- name: Run tests
214+
run: mvn -B -ntp test

‎docs/docs.json‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,38 @@
108108
"pages": ["sdk/python/encoder/overview"]
109109
}
110110
]
111+
},
112+
{
113+
"group": "Java",
114+
"pages": [
115+
"sdk/java/overview",
116+
{
117+
"group": "Core",
118+
"pages": [
119+
"sdk/java/core/overview",
120+
"sdk/java/core/types",
121+
"sdk/java/core/events",
122+
"sdk/java/core/stream",
123+
"sdk/java/core/subscription"
124+
]
125+
},
126+
{
127+
"group": "Client",
128+
"pages": [
129+
"sdk/java/client/overview",
130+
"sdk/java/client/abstract-agent",
131+
"sdk/java/client/http-agent",
132+
"sdk/java/client/subscriber"
133+
]
134+
},
135+
{
136+
"group": "Server",
137+
"pages": [
138+
"sdk/java/server/overview",
139+
"sdk/java/server/spring"
140+
]
141+
}
142+
]
111143
}
112144
]
113145
}
@@ -123,6 +155,11 @@
123155
"anchor": "Python SDK",
124156
"href": "https://docs.ag-ui.com/sdk/python/core/overview",
125157
"icon": "python"
158+
},
159+
{
160+
"anchor": "Java SDK",
161+
"href": "http://localhost:4000/sdk/java/overview",
162+
"icon": "java"
126163
}
127164
]
128165
}

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: "AbstractAgent"
3+
description: "Base agent implementation with core event handling (Java)"
4+
---
5+
6+
# AbstractAgent
7+
8+
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)`.
9+
10+
## Example Implementation
11+
12+
```java
13+
public class MyAgent extends AbstractAgent {
14+
public MyAgent() {
15+
super("my-agent", "A custom agent", "thread-123", List.of(), new State(), false);
16+
}
17+
18+
@Override
19+
protected void run(RunAgentInput input, IEventStream<BaseEvent> stream) {
20+
// Emit events using the stream
21+
stream.next(new RunStartedEvent(input.getThreadId(), input.getRunId()));
22+
23+
// Your agent logic here...
24+
25+
stream.next(new RunFinishedEvent(input.getThreadId(), input.getRunId()));
26+
}
27+
}
28+
```
29+
30+
## Configuration
31+
32+
Constructors take: `agentId`, `description`, `threadId`, `initialMessages`, `state`, `debug`.
33+
34+
## Core Methods
35+
36+
- `CompletableFuture<Void> runAgent(RunAgentParameters parameters, AgentSubscriber subscriber)` — orchestrates an async run and event distribution
37+
- `Subscription subscribe(AgentSubscriber subscriber)` — persistent subscriber registration
38+
- `void addMessage(BaseMessage message)` / `void addMessages(List<BaseMessage>)`
39+
- `void setMessages(List<BaseMessage>)`
40+
- `void setState(State state)` / `State getState()`
41+
42+
## Protected Methods
43+
44+
- `protected abstract void run(RunAgentInput input, IEventStream<BaseEvent> stream)` — emit events into `stream`
45+
- `protected RunAgentInput prepareRunAgentInput(RunAgentParameters parameters)`
46+
- `protected void onInitialize(RunAgentInput input, List<AgentSubscriber> subscribers)`
47+
- `protected void handleEvent(BaseEvent event, List<AgentSubscriber> subscribers, AtomicReference<IEventStream<BaseEvent>> streamRef)`
48+
- `protected void handleComplete(List<AgentSubscriber> subscribers, RunAgentInput input, CompletableFuture<Void> future)`
49+
- `protected void handleError(Throwable error, List<AgentSubscriber> subscribers, CompletableFuture<Void> future)`
50+
51+
### Text Message Helpers
52+
53+
`handleTextMessageStart`, `handleTextMessageContent`, `handleTextMessageChunk`, `handleTextMessageEnd` integrate with `MessageFactory` to assemble streamed messages and notify subscribers.
54+
55+

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: "HttpAgent"
3+
description: "HTTP-based agent for connecting to remote AI agents (Java)"
4+
---
5+
6+
# HttpAgent
7+
8+
`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.
9+
10+
## Configuration
11+
12+
Use the builder to construct an instance:
13+
14+
```java
15+
HttpAgent agent = HttpAgent.builder()
16+
.agentId("my-agent")
17+
.threadId("thread-123")
18+
.httpClient(myHttpClient)
19+
.messages(new ArrayList<>())
20+
.state(new State())
21+
.debug(true)
22+
.build();
23+
```
24+
25+
Required: `agentId`, `threadId`, `httpClient`
26+
27+
## Methods
28+
29+
- `protected void run(RunAgentInput input, IEventStream<BaseEvent> stream)` — streams events via `httpClient.streamEvents`
30+
- `void close()` — closes the underlying HTTP client
31+
32+
## Builder
33+
34+
Fluent builder with validation. Required fields must be set or an `IllegalArgumentException` is thrown.
35+
36+

‎docs/sdk/java/client/overview.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: "Overview"
3+
description: "Client package overview for the Java SDK"
4+
---
5+
6+
# ag-ui-client
7+
8+
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.
9+
10+
## AbstractAgent
11+
12+
`AbstractAgent` is the base agent class for implementing custom agent connectivity. Extend this class and implement `run` to bridge your service to AG-UI.
13+
14+
- Configuration — agent ID, messages, and state
15+
- Core Methods — runAgent, subscribe, message/state helpers
16+
- Protected Methods — event handling hooks
17+
- Properties — state and message tracking
18+
19+
<Card
20+
title="AbstractAgent Reference"
21+
icon="cube"
22+
href="/sdk/java/client/abstract-agent"
23+
color="#3B82F6"
24+
iconType="solid"
25+
>
26+
Base class for creating custom agent connections
27+
</Card>
28+
29+
## HttpAgent
30+
31+
Concrete implementation for HTTP-based agent connectivity using an injected `BaseHttpClient` implementation.
32+
33+
- Configuration — agentId, threadId, httpClient
34+
- Methods — run via HTTP streaming, close
35+
- Builder — fluent configuration with validation
36+
37+
<Card
38+
title="HttpAgent Reference"
39+
icon="cube"
40+
href="/sdk/java/client/http-agent"
41+
color="#3B82F6"
42+
iconType="solid"
43+
>
44+
Ready-to-use HTTP implementation for agent connectivity
45+
</Card>
46+
47+
## AgentSubscriber
48+
49+
Event-driven subscriber system for handling agent lifecycle events and state mutations during execution.
50+
51+
- Event Handlers — lifecycle, message, tool call, and state events
52+
- Usage Examples — logging, persistence, error handling patterns
53+
- Integration — register and use subscribers with agents
54+
55+
<Card
56+
title="AgentSubscriber Reference"
57+
icon="bolt"
58+
href="/sdk/java/client/subscriber"
59+
color="#3B82F6"
60+
iconType="solid"
61+
>
62+
Comprehensive event system for reactive agent interaction
63+
</Card>
64+
65+

‎docs/sdk/java/client/subscriber.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: "AgentSubscriber"
3+
description: "Event subscriber interface for reactive agent interaction (Java)"
4+
---
5+
6+
# AgentSubscriber
7+
8+
Implement `AgentSubscriber` to handle lifecycle, message, tool call, and state events during agent execution.
9+
10+
## Event Handlers
11+
12+
- Request lifecycle: `onRunInitialized`, `onRunFailed`, `onRunFinalized`
13+
- Lifecycle events: `onRunStartedEvent`, `onRunFinishedEvent`, `onRunErrorEvent`, `onStepStartedEvent`, `onStepFinishedEvent`
14+
- Text messages: `onTextMessageStartEvent`, `onTextMessageContentEvent`, `onTextMessageEndEvent`
15+
- Tool calls: `onToolCallStartEvent`, `onToolCallArgsEvent`, `onToolCallEndEvent`, `onToolCallResultEvent`
16+
- State: `onStateSnapshotEvent`, `onStateDeltaEvent`, `onMessagesSnapshotEvent`, `onMessagesChanged`, `onStateChanged`
17+
- Special: `onRawEvent`, `onCustomEvent`, and catch-all `onEvent`
18+
19+
## Usage Example
20+
21+
```java
22+
agent.subscribe(new AgentSubscriber() {
23+
@Override
24+
public void onRunStartedEvent(RunStartedEvent event) {
25+
System.out.println("Run started: " + event.getRunId());
26+
}
27+
28+
@Override
29+
public void onTextMessageContentEvent(TextMessageContentEvent event) {
30+
System.out.print(event.getDelta());
31+
}
32+
});
33+
```
34+
35+

‎docs/sdk/java/core/events.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: "Events"
3+
description: "Java event types used by the Agent User Interaction Protocol"
4+
---
5+
6+
# Events
7+
8+
All events live in `com.agui.core.event` and share `BaseEvent` with a `type` and `timestamp`.
9+
10+
## Lifecycle Events
11+
12+
- `RunStartedEvent`
13+
- `RunFinishedEvent`
14+
- `RunErrorEvent`
15+
- `StepStartedEvent`
16+
- `StepFinishedEvent`
17+
18+
## Text Message Events
19+
20+
- `TextMessageStartEvent` — Begin of a streamed assistant message
21+
- `TextMessageContentEvent` — Incremental content chunks (`delta`)
22+
- `TextMessageEndEvent` — Message finished
23+
24+
## Tool Call Events
25+
26+
- `ToolCallStartEvent`
27+
- `ToolCallArgsEvent`
28+
- `ToolCallEndEvent`
29+
- `ToolCallResultEvent`
30+
31+
## State Management Events
32+
33+
- `StateSnapshotEvent`
34+
- `StateDeltaEvent`
35+
- `MessagesSnapshotEvent`
36+
37+
## Special Events
38+
39+
- `RawEvent` — Raw payload passthrough
40+
- `CustomEvent` — Application-specific event
41+
42+
See also: `AgentSubscriber` callbacks in the client docs for handling these events.
43+
44+

‎docs/sdk/java/core/overview.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Overview"
3+
description: "Core concepts in the Agent User Interaction Protocol SDK"
4+
---
5+
6+
# ag-ui-core
7+
8+
9+
The Agent User Interaction Protocol SDK uses a streaming event-based
10+
architecture with strongly typed data structures. This package provides the
11+
foundation for connecting to agent systems.
12+
13+
```xml
14+
<dependency>
15+
<groupId>com.ag-ui</groupId>
16+
<artifactId>core</artifactId>
17+
<version>0.0.1</version>
18+
</dependency>
19+
```
20+
21+
## Types
22+
23+
Core data structures that represent the building blocks of the system:
24+
25+
- RunAgentInput — Input parameters for running agents
26+
- Message — User/assistant communication and tool usage
27+
- Context — Contextual information provided to agents
28+
- Tool — Defines functions that agents can call
29+
- State — Agent state management
30+
31+
<Card
32+
title="Types Reference"
33+
icon="cube"
34+
href="/sdk/java/core/types"
35+
color="#3B82F6"
36+
iconType="solid"
37+
>
38+
Complete documentation of core types in the Java SDK
39+
</Card>
40+
41+
## Events
42+
43+
Events that power communication between agents and frontends:
44+
45+
- Lifecycle Events — Run and step tracking
46+
- Text Message Events — Assistant message streaming
47+
- Tool Call Events — Function call lifecycle
48+
- State Management Events — Agent state updates
49+
- Special Events — Raw and custom events
50+
51+
<Card
52+
title="Events Reference"
53+
icon="cube"
54+
href="/sdk/java/core/events"
55+
color="#3B82F6"
56+
iconType="solid"
57+
>
58+
Complete documentation of all events in the Java SDK
59+
</Card>

0 commit comments

Comments
 (0)