feat: initialize AG-UI from-scratch project

2026-08-24 00:50:51 +08:00
commit e015185a59
4 changed files with 202 additions and 0 deletions
@@ -0,0 +1,202 @@
+# 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