Merge branch 'main' into brandon/iframe-dojo

Author: brandonmcconnell

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+
+<!--
+
+**Please PLEASE reach out to us first before starting any significant work on new or existing features.**
+
+By the time you've gotten here, you're looking at creating a pull request so hopefully we're not too late.
+
+We love community contributions! That said, we want to make sure we're all on the same page before you start.
+Investing a lot of time and effort just to find out it doesn't align with the upstream project feels awful, and we don't want that to happen.
+It also helps to make sure the work you're planning isn't already in progress.
+
+As described in our contributing guide, please file an issue first: https://github.com/ag-ui-protocol/ag-ui/issues
+Or, reach out to us on Discord: https://discord.gg/Jd3FzfdJa8
+
+Take a look at the contributing guide:
+https://github.com/ag-ui-protocol/ag-ui/blob/main/CONTRIBUTING.md
+
+-->

.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

CONTRIBUTING.md

@@ -10,36 +10,46 @@ Here’s how to get involved:
 
 Pick the right spot so we can help you faster:
 
-- **🐛 Bugs / Feature Ideas** → [GitHub Issues](https://github.com/ag-ui-protocol/ag-ui/issues)  
-- **❓ "How do I...?" / General Questions** → [GitHub Discussions](https://github.com/ag-ui-protocol/ag-ui/discussions)  
+- **🐛 Bugs / Feature Ideas** → [GitHub Issues](https://github.com/ag-ui-protocol/ag-ui/issues)
+- **❓ "How do I...?" / General Questions** → [GitHub Discussions](https://github.com/ag-ui-protocol/ag-ui/discussions)
 - **💬 Quick chats / casual stuff** → [Discord](https://discord.gg/Jd3FzfdJa8) → `#-💎-contributing`
 
 ---
 
 ## 🧑‍💻 Want to Contribute Code?
 
-1. **Find Something to Work On**  
-   Browse open issues on [GitHub](https://github.com/ag-ui-protocol/ag-ui/issues).  
+First, an important plea:
+**Please PLEASE reach out to us first before starting any significant work on new or existing features.**
+
+We love community contributions! That said, we want to make sure we're all on the same page before you start.
+Investing a lot of time and effort just to find out it doesn't align with the upstream project feels awful, and we don't want that to happen.
+It also helps to make sure the work you're planning isn't already in progress.
+
+As described below, please file an issue first: https://github.com/ag-ui-protocol/ag-ui/issues
+Or, reach out to us on Discord: https://discord.gg/Jd3FzfdJa8
+
+1. **Find Something to Work On**
+   Browse open issues on [GitHub](https://github.com/ag-ui-protocol/ag-ui/issues).
    Got your own idea? Open an issue first so we can start the discussion.
 
-2. **Ask to Be Assigned**  
-   Comment on the issue and tag a code owner:  
+2. **Ask to Be Assigned**
+   Comment on the issue and tag a code owner:
    → [Code Owners](https://github.com/ag-ui-protocol/ag-ui/blob/main/.github/CODEOWNERS)
 
-3. **Get on the Roadmap**  
+3. **Get on the Roadmap**
    Once approved, you'll be assigned the issue, and it'll get added to our [roadmap](https://github.com/orgs/ag-ui-protocol/projects/1).
 
-4. **Coordinate With Others**  
-   - If you're collaborating or need feedback, start a thread in `#-💎-contributing` on Discord  
+4. **Coordinate With Others**
+   - If you're collaborating or need feedback, start a thread in `#-💎-contributing` on Discord
    - Or just DM the assignee directly
 
-5. **Open a Pull Request**  
-   - When you’re ready, submit your PR  
-   - In the description, include: `Fixes #<issue-number>`  
+5. **Open a Pull Request**
+   - When you’re ready, submit your PR
+   - In the description, include: `Fixes #<issue-number>`
      (This links your PR to the issue and closes it automatically)
 
-6. **Review & Merge**  
-   - A maintainer will review your code and leave comments if needed  
+6. **Review & Merge**
+   - A maintainer will review your code and leave comments if needed
    - Once it’s approved, we’ll merge it and move the issue to “done.”
 
 **NOTE:** All community integrations (ie, .NET, Golang SDK, etc.) will need to be maintained by the community
@@ -52,13 +62,13 @@ Docs are part of the codebase and super valuable—thanks for helping improve th
 
 Here’s how to contribute:
 
-1. **Open an Issue First**  
-   - Open a [GitHub issue](https://github.com/ag-ui-protocol/ag-ui/issues) describing what you’d like to update or add.  
+1. **Open an Issue First**
+   - Open a [GitHub issue](https://github.com/ag-ui-protocol/ag-ui/issues) describing what you’d like to update or add.
    - Then comment and ask to be assigned.
 
-2. **Submit a PR**  
+2. **Submit a PR**
    - Once assigned, make your edits and open a pull request.
-   - In the description, include: `Fixes #<issue-number>`  
+   - In the description, include: `Fixes #<issue-number>`
      (This links your PR to the issue and closes it automatically)
 
    - A maintainer will review it and merge if it looks good.
@@ -69,5 +79,5 @@ That’s it! Simple and appreciated.
 
 ## 🙌 That’s It!
 
-AG-UI is community-built, and every contribution helps shape where we go next.  
+AG-UI is community-built, and every contribution helps shape where we go next.
 Big thanks for being part of it!

docs/quickstart/clients.mdx

@@ -145,7 +145,7 @@ export const agent = new MastraAgent({
   agent: new Agent({
     name: "AG-UI Assistant",
     instructions: `
-      You are a helpful AI assistant. Be friendly, conversational, and helpful. 
+      You are a helpful AI assistant. Be friendly, conversational, and helpful.
       Answer questions to the best of your ability and engage in natural conversation.
     `,
     model: openai("gpt-4o"),
@@ -175,7 +175,7 @@ Now let's create the interactive chat interface. Create `src/index.ts`:
 ```typescript
 import * as readline from "readline"
 import { agent } from "./agent"
-import { randomUUID } from "node:crypto"
+import { randomUUID } from "@ag-ui/client"
 
 const rl = readline.createInterface({
   input: process.stdin,

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.
+
+