Chat-Kit + AG-UI Demo

A minimal full-stack demo: Vue 3 frontend communicates with a PydanticAI agent over the AG-UI protocol, backed by the Stateful Responses API.

┌──────────────────────┐
│  Vue 3 Frontend      │  localhost:5173
│  @ag-ui/client       │
└──────────┬───────────┘
           │ AG-UI (SSE)
           ▼
┌──────────────────────┐
│  PydanticAI Agent    │  localhost:8000
│  AGUIAdapter         │
│  OpenAIResponsesModel│
└──────────┬───────────┘
           │ OpenAI Responses API
           ▼
┌──────────────────────┐
│  Stateful Responses  │  (deployed)
│  → LLM (vLLM)       │
└──────────────────────┘

Prerequisites

• Python 3.13+ with uv
• Node.js 18+
• An API token for the Stateful Responses endpoint

Quick Start

1. Agent backend

cd agent
cp .env.example .env   # then edit .env with your token
uv sync
uv run uvicorn server:app --reload

Runs at http://localhost:8000/.

2. Frontend

cd frontend
cp .env.example .env   # then edit .env with your token
npm install
npm run dev

Open http://localhost:5173.

Project Structure

├── agent/
│   ├── server.py          # FastAPI app with AG-UI endpoint
│   ├── utils.py           # Raw CoT thinking support + logging HTTP client
│   ├── pyproject.toml
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── App.vue                        # Chat UI
│   │   ├── composables/useAgentChat.ts    # AG-UI ↔ chat-kit bridge
│   │   ├── types.ts
│   │   └── main.ts
│   ├── .env.example
│   ├── package.json
│   └── vite.config.ts
└── README.md

How It Works

1. User types a message in the Vue 3 chat UI
2. @ag-ui/client HttpAgent POSTs an AG-UI RunAgentInput to the backend
3. AGUIAdapter converts AG-UI messages to PydanticAI format and runs the agent
4. The agent calls OpenAIResponsesModel which hits the Stateful Responses API
5. Stateful Responses reconstructs history, forwards to the LLM, and streams tokens back
6. AGUIAdapter translates PydanticAI output into AG-UI events (TextMessageStart / TextMessageContent / TextMessageEnd)
7. The frontend's useAgentChat composable maps AG-UI events to BaseMessage objects
8. Vue reactively renders each token as it arrives

Chat-Kit type compatibility

The frontend defines its own BaseMessage, MessageRole, and MessageStatus types in frontend/src/types.ts that mirror the exact same interfaces from @aleph-alpha/chat-kit. This means the useAgentChat composable produces messages that are directly compatible with chat-kit's components (ChatConversation, ChatInput, etc.) — in a production app you'd import the types from @aleph-alpha/chat-kit instead of duplicating them.

Key files

• agent/utils.py — Extends AGUIAdapter and AGUIEventStream to surface raw Chain-of-Thought thinking from models that store it in provider_details rather than ThinkingPart.content (context).
• frontend/src/types.ts — Local copies of chat-kit's BaseMessage, MessageRole, and MessageStatus types.
• frontend/src/composables/useAgentChat.ts — The bridge between AG-UI events and chat-kit's BaseMessage model. Maps TextMessageStart/TextMessageContent/TextMessageEnd events to BaseMessage objects with the same lifecycle statuses (started → sending → completed). In production, this composable would live inside @aleph-alpha/chat-kit as an AGUIChatService.