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:

``` 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