# Agent-UI Protocols Demo

> 演示三种智能体前端交互协议：**AG-UI**、**A2UI**、**MCP-UI**

## 🎯 项目简介

本项目通过统一的餐厅搜索场景，展示三种 Agent-to-UI 协议的核心差异：

| 协议 | 来源 | 核心理念 | 数据格式 |
|------|------|----------|----------|
| **AG-UI** | CopilotKit | 事件驱动的双向通信 | SSE 事件流 (~16种事件类型) |
| **A2UI** | Google | 声明式 UI 组件规范 | JSONL (邻接表模型) |
| **MCP-UI** | 社区 | MCP Tool 的 UI 扩展 | UIResource (HTML/URI/RemoteDOM) |

## 📁 项目结构

```
demo-agent-ui-protocols/
├── apps/web/                # Next.js 前端 (port 3000)
├── agents/
│   ├── ag-ui-agent/         # AG-UI Python Agent (port 8001)
│   ├── a2ui-agent/          # A2UI Python Agent (port 8002)
│   └── mcp-ui-agent/        # MCP-UI Python Agent (port 8003)
├── packages/shared/         # 共享类型定义
├── install.sh               # 一键安装依赖
├── run.sh                   # 一键启动所有服务
└── .env.example             # 环境变量模板
```

## 🚀 快速开始

### 1️⃣ 克隆项目

```bash
git clone <repo-url>
cd demo-agent-ui-protocols
```

### 2️⃣ 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的 API 配置：

```env
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
```

### 3️⃣ 安装依赖

```bash
chmod +x install.sh run.sh
./install.sh
```

### 4️⃣ 启动服务

```bash
./run.sh
```

所有服务将自动启动，按 `Ctrl+C` 可停止全部服务。

### 5️⃣ 访问 Demo

| 页面 | 地址 |
|------|------|
| 首页 | http://localhost:3000 |
| AG-UI Demo | http://localhost:3000/ag-ui-demo |
| A2UI Demo | http://localhost:3000/a2ui-demo |
| MCP-UI Demo | http://localhost:3000/mcp-ui-demo |

## 📡 协议核心特性

### AG-UI (CopilotKit)

事件驱动的流式协议，前端控制 UI 渲染：

```
事件类型:
├── 生命周期: RUN_STARTED / RUN_FINISHED / RUN_ERROR
├── 文本消息: TEXT_MESSAGE_START / CONTENT / END
├── 工具调用: TOOL_CALL_START / ARGS / END / RESULT
└── 状态管理: STATE_SNAPSHOT / STATE_DELTA
```

### A2UI (Google)

声明式 UI 规范，Agent 生成组件定义：

```
消息类型:
├── surfaceUpdate    # 组件定义 (邻接表模型)
├── dataModelUpdate  # 数据模型更新
├── beginRendering   # 触发渲染信号
└── deleteSurface    # 删除 UI 区域
```

### MCP-UI (社区)

MCP 协议的 UI 扩展，Tool 返回可渲染内容：

```
UIResource:
├── mimeType: text/html          # iframe srcDoc
├── mimeType: text/uri-list      # iframe src
└── mimeType: remote-dom         # Shopify RemoteDOM

UI Actions: tool / prompt / notify / link
```

## 🛠 环境要求

- **Node.js** 18+
- **pnpm** 9+ (自动安装)
- **Python** 3.10+
- **uv** (自动安装)

## 📝 手动启动 (可选)

如果需要分别启动各服务：

```bash
# 终端 1: 前端
pnpm dev:web

# 终端 2: AG-UI Agent
cd agents/ag-ui-agent && source .venv/bin/activate && python server.py

# 终端 3: A2UI Agent
cd agents/a2ui-agent && source .venv/bin/activate && python server.py

# 终端 4: MCP-UI Agent
cd agents/mcp-ui-agent && source .venv/bin/activate && python server.py
```

## 📚 参考资料

- [AG-UI Protocol](https://github.com/CopilotKit/ag-ui)
- [A2UI Specification](https://github.com/nicholastmosher/A2UI)
- [MCP-UI Proposal](https://github.com/nicholastmosher/mcp-ui)

## 📄 License

MIT