203 lines
3.3 KiB
Markdown
203 lines
3.3 KiB
Markdown
# AGENTS.md
|
|
|
|
# Project: agui-from-scratch
|
|
|
|
## Purpose
|
|
|
|
This project is a from-scratch implementation of a minimal AG-UI
|
|
protocol runtime.
|
|
|
|
The goal is learning the protocol design, not building a production
|
|
framework.
|
|
|
|
Do NOT install or use the official `ag-ui` SDK until the final migration
|
|
step.
|
|
|
|
The project should help understand:
|
|
|
|
- SSE (Server-Sent Events) framing
|
|
- AG-UI event lifecycle
|
|
- streaming text messages
|
|
- tool call streaming
|
|
- frontend event reducers
|
|
- state synchronization
|
|
- adapter design between different agent frameworks
|
|
|
|
## Core Learning Goal
|
|
|
|
Build this pipeline:
|
|
|
|
Agent Runtime
|
|
|
|
|
v
|
|
AG-UI Event Generator
|
|
|
|
|
v
|
|
SSE Encoder
|
|
|
|
|
v
|
|
HTTP Streaming Response
|
|
|
|
|
v
|
|
Browser SSE Parser
|
|
|
|
|
v
|
|
AG-UI Event Reducer
|
|
|
|
|
v
|
|
UI State
|
|
|
|
## Repository Structure
|
|
|
|
agui-from-scratch/
|
|
|
|
├── server.py
|
|
├── index.html
|
|
├── README.md
|
|
└── AGENTS.md
|
|
|
|
Keep the repository minimal.
|
|
|
|
## Technology Constraints
|
|
|
|
Backend: - Python - FastAPI - asyncio - native JSON handling
|
|
|
|
Do not use: - ag-ui SDK - LangChain - LangGraph - agent frameworks
|
|
|
|
Frontend: - Vanilla JavaScript - Fetch API - ReadableStream -
|
|
TextDecoder
|
|
|
|
Avoid frontend frameworks.
|
|
|
|
## Development Rules
|
|
|
|
Do not hide protocol details.
|
|
|
|
Initially implement manually:
|
|
|
|
``` python
|
|
encode_sse()
|
|
```
|
|
|
|
``` javascript
|
|
parseSSE()
|
|
```
|
|
|
|
``` javascript
|
|
applyEvent()
|
|
```
|
|
|
|
## Commit Plan
|
|
|
|
### Commit 1
|
|
|
|
feat: implement SSE framing
|
|
|
|
Implement: - FastAPI endpoint - text/event-stream response - SSE frame
|
|
encoding
|
|
|
|
Understand:
|
|
|
|
HTTP chunk -\> SSE frame -\> JSON payload
|
|
|
|
### Commit 2
|
|
|
|
feat: implement AG-UI text events
|
|
|
|
Implement:
|
|
|
|
- RUN_STARTED
|
|
- TEXT_MESSAGE_START
|
|
- TEXT_MESSAGE_CONTENT
|
|
- TEXT_MESSAGE_END
|
|
- RUN_FINISHED
|
|
|
|
Frontend maintains streaming messages.
|
|
|
|
### Commit 3
|
|
|
|
feat: implement AG-UI tool call events
|
|
|
|
Implement:
|
|
|
|
- TOOL_CALL_START
|
|
- TOOL_CALL_ARGS
|
|
- TOOL_CALL_END
|
|
- TOOL_CALL_RESULT
|
|
|
|
Remember: tool arguments are streamed and may arrive in multiple chunks.
|
|
|
|
### Commit 4
|
|
|
|
feat: implement AG-UI state reducer
|
|
|
|
Implement:
|
|
|
|
- STATE_SNAPSHOT
|
|
- STATE_DELTA
|
|
|
|
Maintain runtime state:
|
|
|
|
``` javascript
|
|
{
|
|
running:false,
|
|
messages:{},
|
|
toolCalls:{},
|
|
state:{}
|
|
}
|
|
```
|
|
|
|
## Final Migration
|
|
|
|
Only after all milestones:
|
|
|
|
Install the official ag-ui SDK.
|
|
|
|
Replace:
|
|
|
|
- encode_sse()
|
|
- parseSSE()
|
|
- applyEvent()
|
|
|
|
with official implementations.
|
|
|
|
Compare: - abstraction choices - protocol decisions - problems solved by
|
|
the SDK
|
|
|
|
## Debugging Rules
|
|
|
|
Inspect in order:
|
|
|
|
1. raw HTTP chunks
|
|
2. SSE frames
|
|
3. parsed JSON events
|
|
4. reducer state changes
|
|
5. UI rendering
|
|
|
|
## Future Extensions
|
|
|
|
Add adapters:
|
|
|
|
AgentScope Event
|
|
|
|
|
v
|
|
AG-UI Event
|
|
|
|
OpenCode Event
|
|
|
|
|
v
|
|
AG-UI Event
|
|
|
|
Later replace fake agent streaming with: - OpenAI Realtime API - Qwen
|
|
Realtime Agent - local LLM runtime
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] SSE stream works without SDK
|
|
- [ ] Text streaming works
|
|
- [ ] Tool calls stream correctly
|
|
- [ ] Frontend maintains runtime state
|
|
- [ ] Different agent backends can be adapted into AG-UI events
|
|
- [ ] Official SDK can replace handwritten components
|
|
- [ ] README explains protocol design decisions
|