Skip to content

Commit ecc023f

Browse files
contextablemarkcontextablemark
authored
Merge branch 'ag-ui-protocol:main' into kotlinsdk
2 parents c0a714e + 34375ab commit ecc023f

Some content is hidden

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

41 files changed

+5403
-1019
lines changed

‎CLAUDE.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Common Development Commands
6+
7+
### TypeScript SDK (Main Development)
8+
```bash
9+
# Navigate to typescript-sdk directory for all TypeScript work
10+
cd typescript-sdk
11+
12+
# Install dependencies (using pnpm)
13+
pnpm install
14+
15+
# Build all packages
16+
pnpm build
17+
18+
# Run development mode
19+
pnpm dev
20+
21+
# Run linting
22+
pnpm lint
23+
24+
# Run type checking
25+
pnpm check-types
26+
27+
# Run tests
28+
pnpm test
29+
30+
# Format code
31+
pnpm format
32+
33+
# Clean build artifacts
34+
pnpm clean
35+
36+
# Full clean build
37+
pnpm build:clean
38+
```
39+
40+
### Python SDK
41+
```bash
42+
# Navigate to python-sdk directory
43+
cd python-sdk
44+
45+
# Install dependencies (using poetry)
46+
poetry install
47+
48+
# Run tests
49+
python -m unittest discover tests
50+
51+
# Build distribution
52+
poetry build
53+
```
54+
55+
### Running Specific Integration Tests
56+
```bash
57+
# For TypeScript packages/integrations
58+
cd typescript-sdk/packages/<package-name>
59+
pnpm test
60+
61+
# For running a single test file
62+
cd typescript-sdk/packages/<package-name>
63+
pnpm test -- path/to/test.spec.ts
64+
```
65+
66+
## High-Level Architecture
67+
68+
AG-UI is an event-based protocol that standardizes agent-user interactions. The codebase is organized as a monorepo with the following structure:
69+
70+
### Core Protocol Architecture
71+
- **Event-Driven Communication**: All agent-UI communication happens through typed events (BaseEvent and its subtypes)
72+
- **Transport Agnostic**: Protocol supports SSE, WebSockets, HTTP binary, and custom transports
73+
- **Observable Pattern**: Uses RxJS Observables for streaming agent responses
74+
75+
### Key Abstractions
76+
1. **AbstractAgent**: Base class that all agents must implement with a `run(input: RunAgentInput) -> Observable<BaseEvent>` method
77+
2. **HttpAgent**: Standard HTTP client supporting SSE and binary protocols for connecting to agent endpoints
78+
3. **Event Types**: Lifecycle events (RUN_STARTED/FINISHED), message events (TEXT_MESSAGE_*), tool events (TOOL_CALL_*), and state management events (STATE_SNAPSHOT/DELTA)
79+
80+
### Repository Structure
81+
- `/typescript-sdk/`: Main TypeScript implementation
82+
- `/packages/`: Core protocol packages (@ag-ui/core, @ag-ui/client, @ag-ui/encoder, @ag-ui/proto)
83+
- `/integrations/`: Framework integrations (langgraph, mastra, crewai, etc.)
84+
- `/apps/`: Example applications including the AG-UI Dojo demo viewer
85+
- `/python-sdk/`: Python implementation of the protocol
86+
- `/docs/`: Documentation site content
87+
88+
### Integration Pattern
89+
Each framework integration follows a similar pattern:
90+
1. Implements the AbstractAgent interface
91+
2. Translates framework-specific events to AG-UI protocol events
92+
3. Provides both TypeScript client and Python server implementations
93+
4. Includes examples demonstrating key AG-UI features (agentic chat, generative UI, human-in-the-loop, etc.)
94+
95+
### State Management
96+
- Uses STATE_SNAPSHOT for complete state representations
97+
- Uses STATE_DELTA with JSON Patch (RFC 6902) for efficient incremental updates
98+
- MESSAGES_SNAPSHOT provides conversation history
99+
100+
### Multiple Sequential Runs
101+
- AG-UI supports multiple sequential runs in a single event stream
102+
- Each run must complete (RUN_FINISHED) before a new run can start (RUN_STARTED)
103+
- Messages accumulate across runs (e.g., messages from run1 + messages from run2)
104+
- State continues to evolve across runs unless explicitly reset with STATE_SNAPSHOT
105+
- Run-specific tracking (active messages, tool calls, steps) resets between runs
106+
107+
### Development Workflow
108+
- Turbo is used for monorepo build orchestration
109+
- Each package has independent versioning
110+
- Integration tests demonstrate protocol compliance
111+
- The AG-UI Dojo app showcases all protocol features with live examples

‎README.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ Built for simplicity and flexibility, it enables seamless integration between AI
66

77
---
88

9-
[📅 Upcoming Event: August 6th - AG-UI + Mastra: Build a Project Management Canvas](https://lu.ma/94688z7e)
109

1110
<br>
1211

@@ -86,16 +85,16 @@ AG-UI is complementary to the other 2 top agentic protocols
8685

8786
AG-UI was born from CopilotKit's initial partnership with LangGraph and CrewAI - and brings the incredibly popular agent-user-interactivity infrastructure to the wider agentic ecosystem.
8887

89-
| Framework | Status | AG-UI Resources | Integrations |
88+
| Framework | Status | AG-UI Resources | Integrations |
9089
| ------------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------- | ------------------------ |
9190
| No-framework | ✅ Supported | ➡️ Docs coming soon | |
92-
| [LangGraph](https://www.langchain.com/langgraph) | ✅ Supported | ➡️ [Demo](https://v0-langgraph-land.vercel.app/) | Partnership |
93-
| [CrewAI](https://crewai.com/) | ✅ Supported | ➡️ [Demo](https://v0-crew-land.vercel.app/) | Partnership |
94-
| [Mastra](https://mastra.ai/) | ✅ Supported | ➡️ [Demo](https://v0-mastra-land.vercel.app/) | 1st party |
95-
| [AG2](https://ag2.ai/) | ✅ Supported | ➡️ [Demo](https://v0-ag2-land.vercel.app/) | 1st party |
96-
| [Agno](https://github.com/agno-agi/agno) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/agno) | 1st party |
97-
| [LlamaIndex](https://github.com/run-llama/llama_index) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/llamaindex) | 1st party |
98-
| [Pydantic AI](https://github.com/pydantic/pydantic-ai) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/pydantic-ai) | 1st party |
91+
| [LangGraph](https://www.langchain.com/langgraph) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/langgraph/) [Demos](https://dojo.ag-ui.com/langgraph-fastapi/feature/shared_state) | Partnership |
92+
| [CrewAI](https://crewai.com/) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/crewai-flows) [Demos](https://dojo.ag-ui.com/crewai/feature/shared_state) | Partnership |
93+
| [Mastra](https://mastra.ai/) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/mastra/) [Demos](https://dojo.ag-ui.com/mastra/feature/shared_state) | 1st party |
94+
| [AG2](https://ag2.ai/) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/ag2/) [Demos](https://dojo.ag-ui.com/ag2/feature/shared_state) | 1st party |
95+
| [Agno](https://github.com/agno-agi/agno) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/agno/) [Demos](https://dojo.ag-ui.com/agno/feature/shared_state) | 1st party |
96+
| [LlamaIndex](https://github.com/run-llama/llama_index) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/llamaindex/) [Demos](https://dojo.ag-ui.com/llamaindex/feature/shared_state) | 1st party |
97+
| [Pydantic AI](https://github.com/pydantic/pydantic-ai) | ✅ Supported | ➡️ [Docs](https://docs.copilotkit.ai/pydantic-ai/) [Demos](https://dojo.ag-ui.com/pydantic-ai/feature/shared_state) | 1st party |
9998
| [Vercel AI SDK](https://github.com/vercel/ai) | 🛠️ In Progress | – | Community |
10099
| [Google ADK](https://google.github.io/adk-docs/get-started/) | 🛠️ [PR](https://github.com/ag-ui-protocol/ag-ui/pull/274) | – | Community |
101100
| [OpenAI Agent SDK](https://openai.github.io/openai-agents-python/) | 🛠️ In Progress | – | Community |
@@ -131,7 +130,7 @@ https://agui-demo.vercel.app/
131130

132131

133132
## 🧩 AG-UI Showcase: The AG-UI Dojo (Building-Blocks Viewer)
134-
The [AG-UI Dojo](https://copilotkit-feature-viewer.vercel.app/) showcases many of the building blocks that AG-UI supports ([AG-UI Dojo Source Code](https://github.com/ag-ui-protocol/ag-ui/tree/main/typescript-sdk/apps/dojo)).
133+
The [AG-UI Dojo](https://dojo.ag-ui.com/langgraph-fastapi/feature/shared_state) showcases many of the building blocks that AG-UI supports ([AG-UI Dojo Source Code](https://github.com/ag-ui-protocol/ag-ui/tree/main/typescript-sdk/apps/dojo)) with each Agent Framework integration.
135134

136135
The building blocks are designed to be simple and focused -- between 50-200 lines of code.
137136

@@ -142,7 +141,7 @@ https://github.com/user-attachments/assets/a67d3d54-36b2-4c7a-ac69-a0ca01365d5b
142141

143142
Check out the [Contributing guide](https://github.com/ag-ui-protocol/ag-ui/blob/main/CONTRIBUTING.md)
144143

145-
- **[Weekely AG-UI Working Group](https://lu.ma/CopilotKit?k=c)**
144+
- **[Bi-Weekely AG-UI Working Group](https://lu.ma/CopilotKit?k=c)**
146145
📅 Follow the CopilotKit Luma Events Calendar
147146

148147
## Roadmap

‎docs/concepts/events.mdx‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -194,10 +194,10 @@ for an incoming message, such as creating a new message bubble with a loading
194194
indicator. The `role` property identifies whether the message is coming from the
195195
assistant or potentially another participant in the conversation.
196196

197-
| Property | Description |
198-
| ----------- | ---------------------------------------------- |
199-
| `messageId` | Unique identifier for the message |
200-
| `role` | Role of the message sender (e.g., "assistant") |
197+
| Property | Description |
198+
| ----------- | --------------------------------------------------------------------------------- |
199+
| `messageId` | Unique identifier for the message |
200+
| `role` | Role of the message sender ("developer", "system", "assistant", "user", "tool") |
201201

202202
### TextMessageContent
203203

@@ -231,6 +231,22 @@ automatic scrolling to ensure the full message is visible.
231231
| ----------- | -------------------------------------- |
232232
| `messageId` | Matches the ID from `TextMessageStart` |
233233

234+
### TextMessageChunk
235+
236+
A self-contained text message event that combines start, content, and end.
237+
238+
The `TextMessageChunk` event provides a convenient way to send complete text messages
239+
in a single event instead of the three-event sequence (start, content, end). This is
240+
particularly useful for simple messages or when the entire content is available at once.
241+
The event includes both the message metadata and content, making it more efficient for
242+
non-streaming scenarios.
243+
244+
| Property | Description |
245+
| ----------- | ------------------------------------------------------------------------------------- |
246+
| `messageId` | Optional unique identifier for the message |
247+
| `role` | Optional role of the sender ("developer", "system", "assistant", "user", "tool") |
248+
| `delta` | Optional text content of the message |
249+
234250
## Tool Call Events
235251

236252
These events represent the lifecycle of tool calls made by agents. Tool calls

‎docs/development/roadmap.mdx‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,11 @@ title: Roadmap
33
description: Our plans for evolving Agent User Interaction Protocol
44
---
55

6-
The Agent User Interaction Protocol is rapidly evolving. This page outlines our
7-
current thinking on key priorities and future direction.
8-
9-
<Note>
10-
The ideas presented here are not commitments—we may solve these challenges
11-
differently than described, or some may not materialize at all. This is also
12-
not an _exhaustive_ list; we may incorporate work that isn't mentioned here.
13-
</Note>
6+
You can follow the progress of the AG-UI Protocol on our
7+
[public roadmap](https://github.com/orgs/ag-ui-protocol/projects/1).
148

159
## Get Involved
1610

17-
We welcome community participation in shaping AG-UI's future. Visit our
18-
[GitHub Discussions](https://github.com/orgs/ag-ui-protocol/discussions) to join
19-
the conversation and contribute your ideas.
11+
If you’d like to contribute ideas, feature requests, or bug reports to
12+
the roadmap, please see the [Contributing Guide](https://github.com/ag-ui-protocol/ag-ui/blob/main/CONTRIBUTING.md)
13+
for details on how to get involved.

‎python-sdk/ag_ui/core/events.py‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,10 @@
77

88
from pydantic import Field
99

10-
from .types import ConfiguredBaseModel, Message, State
10+
from .types import ConfiguredBaseModel, Message, State, Role
11+
12+
# Text messages can have any role except "tool"
13+
TextMessageRole = Literal["developer", "system", "assistant", "user"]
1114

1215

1316
class EventType(str, Enum):
@@ -55,7 +58,7 @@ class TextMessageStartEvent(BaseEvent):
5558
"""
5659
type: Literal[EventType.TEXT_MESSAGE_START] = EventType.TEXT_MESSAGE_START # pyright: ignore[reportIncompatibleVariableOverride]
5760
message_id: str
58-
role: Literal["assistant"] = "assistant"
61+
role: TextMessageRole = "assistant"
5962

6063

6164
class TextMessageContentEvent(BaseEvent):
@@ -80,7 +83,7 @@ class TextMessageChunkEvent(BaseEvent):
8083
"""
8184
type: Literal[EventType.TEXT_MESSAGE_CHUNK] = EventType.TEXT_MESSAGE_CHUNK # pyright: ignore[reportIncompatibleVariableOverride]
8285
message_id: Optional[str] = None
83-
role: Optional[Literal["assistant"]] = None
86+
role: Optional[TextMessageRole] = None
8487
delta: Optional[str] = None
8588

8689
class ThinkingTextMessageStartEvent(BaseEvent):

0 commit comments

Comments
 (0)