Skip to content

Commit 1940494

Browse files
wdoppenbergwdoppenberg
committed
Merge remote-tracking branch 'origin/upstream'
# Conflicts: # .gitignore
2 parents d2a821e + 96830c5 commit 1940494

File tree

348 files changed

+55859
-23192
lines changed

Some content is hidden

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

348 files changed

+55859
-23192
lines changed

‎.github/workflows/dojo-e2e.yml‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
name: e2e
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
e2e:
11+
name: ${{ matrix.suite }}
12+
runs-on: depot-ubuntu-24.04
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
include:
17+
- suite: agno
18+
test_path: tests/agnoTests
19+
services: ["dojo","agno"]
20+
wait_on: http://localhost:9999,tcp:localhost:8002
21+
- suite: crew-ai
22+
test_path: tests/crewAITests
23+
services: ["dojo","crew-ai"]
24+
wait_on: http://localhost:9999,tcp:localhost:8003
25+
- suite: langgraph
26+
test_path: tests/langgraphTests
27+
services: ["dojo","langgraph-platform-python","langgraph-platform-typescript"]
28+
wait_on: http://localhost:9999,tcp:localhost:8005,tcp:localhost:8006
29+
- suite: langgraph-fastapi
30+
test_path: tests/langgraphFastAPITests
31+
services: ["dojo","langgraph-fastapi"]
32+
wait_on: http://localhost:9999,tcp:localhost:8004
33+
- suite: llama-index
34+
test_path: tests/llamaIndexTests
35+
services: ["dojo","llama-index"]
36+
wait_on: http://localhost:9999,tcp:localhost:8007
37+
- suite: mastra
38+
test_path: tests/mastraTests
39+
services: ["dojo","mastra"]
40+
wait_on: http://localhost:9999,tcp:localhost:8008
41+
- suite: mastra-agent-local
42+
test_path: tests/mastraAgentLocalTests
43+
services: ["dojo"]
44+
wait_on: http://localhost:9999
45+
- suite: middleware-starter
46+
test_path: tests/middlewareStarterTests
47+
services: ["dojo"]
48+
wait_on: http://localhost:9999
49+
- suite: pydantic-ai
50+
test_path: tests/pydanticAITests
51+
services: ["dojo","pydantic-ai"]
52+
wait_on: http://localhost:9999,tcp:localhost:8009
53+
- suite: server-starter
54+
test_path: tests/serverStarterTests
55+
services: ["dojo","server-starter"]
56+
wait_on: http://localhost:9999,tcp:localhost:8000
57+
- suite: server-starter-all
58+
test_path: tests/serverStarterAllFeaturesTests
59+
services: ["dojo","server-starter-all"]
60+
wait_on: http://localhost:9999,tcp:localhost:8001
61+
- suite: vercel-ai-sdk
62+
test_path: tests/vercelAISdkTests
63+
services: ["dojo"]
64+
wait_on: http://localhost:9999
65+
66+
steps:
67+
- name: Checkout code
68+
uses: actions/checkout@v4
69+
70+
- name: Set up Node.js
71+
uses: actions/setup-node@v4
72+
with:
73+
node-version: '22'
74+
75+
- name: Install pnpm
76+
uses: pnpm/action-setup@v4
77+
with:
78+
version: 10.13.1
79+
80+
# Now that pnpm is available, cache its store to speed installs
81+
- name: Resolve pnpm store path
82+
id: pnpm-store
83+
run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
84+
85+
- name: Cache pnpm store
86+
uses: actions/cache@v4
87+
with:
88+
path: ${{ env.STORE_PATH }}
89+
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
90+
restore-keys: |
91+
${{ runner.os }}-pnpm-store-
92+
93+
# Cache Python tool caches and virtualenvs; restore only to avoid long saves
94+
- name: Cache Python dependencies (restore-only)
95+
id: cache-python
96+
uses: actions/cache/restore@v4
97+
with:
98+
path: |
99+
~/.cache/pip
100+
~/.cache/pypoetry
101+
~/.cache/uv
102+
**/.venv
103+
key: ${{ runner.os }}-pydeps-${{ hashFiles('**/poetry.lock', '**/pyproject.toml') }}
104+
restore-keys: |
105+
${{ runner.os }}-pydeps-
106+
107+
- name: Install Poetry
108+
uses: snok/install-poetry@v1
109+
with:
110+
version: latest
111+
virtualenvs-create: true
112+
virtualenvs-in-project: true
113+
114+
- name: Install uv
115+
uses: astral-sh/setup-uv@v6
116+
117+
- name: Install dependencies
118+
working-directory: typescript-sdk
119+
run: pnpm install --frozen-lockfile
120+
121+
- name: Prepare dojo for e2e
122+
working-directory: typescript-sdk/apps/dojo
123+
if: ${{ join(matrix.services, ',') != '' }}
124+
run: node ./scripts/prep-dojo-everything.js --only ${{ join(matrix.services, ',') }}
125+
126+
- name: Install e2e dependencies
127+
working-directory: typescript-sdk/apps/dojo/e2e
128+
run: |
129+
pnpm install
130+
131+
- name: write langgraph env files
132+
working-directory: typescript-sdk/integrations/langgraph
133+
env:
134+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
135+
LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
136+
if: ${{ contains(join(matrix.services, ','), 'langgraph-fastapi') || contains(join(matrix.services, ','), 'langgraph-platform-python') || contains(join(matrix.services, ','), 'langgraph-platform-typescript') }}
137+
run: |
138+
echo "OPENAI_API_KEY=${OPENAI_API_KEY}" > examples/python/.env
139+
echo "LANGSMITH_API_KEY=${LANGSMITH_API_KEY}" >> examples/python/.env
140+
echo "OPENAI_API_KEY=${OPENAI_API_KEY}" > examples/typescript/.env
141+
echo "LANGSMITH_API_KEY=${LANGSMITH_API_KEY}" >> examples/typescript/.env
142+
echo "OPENAI_API_KEY=${OPENAI_API_KEY}" > python/ag_ui_langgraph/.env
143+
echo "LANGSMITH_API_KEY=${LANGSMITH_API_KEY}" >> python/ag_ui_langgraph/.env
144+
145+
- name: Run dojo+agents
146+
uses: JarvusInnovations/background-action@v1
147+
env:
148+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
149+
LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
150+
if: ${{ join(matrix.services, ',') != '' && contains(join(matrix.services, ','), 'dojo') }}
151+
with:
152+
run: |
153+
node ../scripts/run-dojo-everything.js --only ${{ join(matrix.services, ',') }}
154+
working-directory: typescript-sdk/apps/dojo/e2e
155+
wait-on: ${{ matrix.wait_on }}
156+
wait-for: 300000
157+
158+
- name: Run tests – ${{ matrix.suite }}
159+
working-directory: typescript-sdk/apps/dojo/e2e
160+
env:
161+
BASE_URL: http://localhost:9999
162+
PLAYWRIGHT_SUITE: ${{ matrix.suite }}
163+
run: |
164+
pnpm test -- ${{ matrix.test_path }}
165+
166+
- name: Upload traces – ${{ matrix.suite }}
167+
if: always() # Uploads artifacts even if tests fail
168+
uses: actions/upload-artifact@v4
169+
with:
170+
name: ${{ matrix.suite }}-playwright-traces
171+
path: |
172+
typescript-sdk/apps/dojo/e2e/test-results/${{ matrix.suite }}/**/*
173+
typescript-sdk/apps/dojo/e2e/playwright-report/**/*
174+
retention-days: 7

‎.github/workflows/test.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ jobs:
6969
- name: Install pnpm
7070
uses: pnpm/action-setup@v4
7171
with:
72-
version: 9.0.0
72+
version: 10.13.1
7373

7474
- name: Setup pnpm cache
7575
uses: actions/cache@v4

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
**/.claude/settings.local.json
12
.vscode/
3+
.idea/
24

35
**/target

‎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

0 commit comments

Comments
 (0)