agui-from-scratch/AGENTS.md

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:

encode_sse()

parseSSE()

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:

{
 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