social-app/.opencode/skills/ag-ui/SKILL.md

---
name: ag-ui
description: AG-UI protocol for agent-user interaction. Use when implementing agent chat, streaming events, tool calls, state synchronization, SSE, multimodal messages, MCP/A2A integration, or any AG-UI protocol development.
---

# AG-UI Skills

AG-UI 协议开发权威指南。**必须使用**场景：构建 agentic 应用、实现 agent 与用户交互、处理流式事件、工具调用生命周期、状态同步、多模态消息、MCP/A2A 集成。提供完整模块索引与源文件行号映射。

## 何时使用

**必须使用**的场景：
- 实现 Agent 与前端的流式交互
- 处理 Agent 生命周期事件（RunStarted/Finished、StepStarted/Finished）
- 实现工具调用（ToolCall 事件流）
- Agent 状态管理与前端同步
- 集成 MCP/A2A 协议的 agent 应用
- 实现人机协作（Interrupts、Approval 流程）
- 处理多模态消息（文本、图片、音频、视频）

**查询模式**：
- "如何实现 agent 流式响应"
- "tool call 事件流程"
- "agent state delta 同步"
- "human-in-the-loop interrupt"
- "AG-UI 与 MCP 集成"

## 模块索引

按功能模块查看源文件对应章节：

| 模块 | 作用 | 源文件行号 |
|------|------|------------|
| [protocol](modules/protocol.md) | 协议概述，与 MCP、A2A 关系 | 1-33 |
| [agents](modules/agents.md) | Agent 概念、架构、类型、实现 | 35-451 |
| [architecture](modules/architecture.md) | 核心架构、设计原则、运行机制 | 453-679 |
| [events](modules/events.md) | 所有事件类型详解 | 680-1475 |
| [generative-ui](modules/generative-ui.md) | 生成式 UI 规范（A2UI/MCP-UI） | 1476-1496 |
| [messages](modules/messages.md) | 消息结构、类型、同步机制 | 1498-1952 |
| [middleware](modules/middleware.md) | 中间件：转换、过滤、增强事件流 | 1954-2158 |
| [reasoning](modules/reasoning.md) | LLM 推理支持，加密推理内容 | 2160-2638 |
| [serialization](modules/serialization.md) | 事件流序列化、压缩、分支 | 2640-2827 |
| [state](modules/state.md) | Agent 与前端状态同步 | 2829-3080 |
| [tools](modules/tools.md) | 工具定义、调用生命周期 | 3082-3441 |
| [drafts](modules/drafts.md) | 提案功能：Generative UI, Interrupts, Meta Events, Multimodal | 3492-4846 |
| [contributing](modules/contributing.md) | 贡献指南、路线图、更新日志 | 3443-3485 |
| [overview](modules/overview.md) | **AG-UI 协议总体介绍** | 4894-5261 |

## 源文件

- `llms-full.txt` - AG-UI 协议完整文档（唯一信源，10632 行）
- `scripts/` - 可执行示例代码（见下方"示例脚本"）

## 示例脚本

`scripts/` 目录包含可直接运行的 TypeScript 示例：

| 示例 | 用途 | 参考文档 |
|------|------|---------|
| [minimal_agent.ts](scripts/minimal_agent.ts) | 最小 Agent 实现 | [agents](modules/agents.md) 行 132-197 |
| [tool_call_example.ts](scripts/tool_call_example.ts) | 工具调用流程 | [events](modules/events.md) 行 938-1066 |
| [state_sync_example.ts](scripts/state_sync_example.ts) | Snapshot-Delta 状态同步 | [events](modules/events.md) 行 1067-1155 |

**运行示例**:
```bash
# 安装依赖
npm install @ag-ui/client rxjs

# 运行
npx ts-node scripts/minimal_agent.ts
```

详见 [scripts/README.md](scripts/README.md)

## 常见事件速查

| 场景 | 关键事件 | 详见 |
|------|---------|------|
| 流式响应 | TextMessageStart → Content → End | [events](modules/events.md) 行 835-937 |
| 工具调用 | ToolCallStart → Args → End → Result | [events](modules/events.md) 行 938-1066 |
| 状态同步 | StateSnapshot, StateDelta | [events](modules/events.md) 行 1067-1155 |
| 生命周期 | RunStarted/Finished, StepStarted/Finished | [events](modules/events.md) 行 715-754 |
| 人机中断 | RunFinished(interrupt) | [drafts](modules/drafts.md) 行 3897-3920 |

## 快速路径

**新手入门**：
1. [overview](modules/overview.md) - **理解 AG-UI 协议全貌与定位**
2. [protocol](modules/protocol.md) - AG-UI 在 AI 协议栈的位置（与 MCP/A2A 关系）
3. [architecture](modules/architecture.md) - 核心概念与设计原则
4. [agents](modules/agents.md) - Agent 基础实现
5. 运行 [minimal_agent.ts](scripts/minimal_agent.ts) 体验基础事件流

**实现功能**：
- 流式响应 → [events](modules/events.md) (TextMessage 事件) + [minimal_agent.ts](scripts/minimal_agent.ts)
- 工具调用 → [tools](modules/tools.md) + [events](modules/events.md) (ToolCall 事件) + [tool_call_example.ts](scripts/tool_call_example.ts)
- 状态同步 → [state](modules/state.md) + [events](modules/events.md) (StateDelta) + [state_sync_example.ts](scripts/state_sync_example.ts)
- 中间件 → [middleware](modules/middleware.md)

**高级特性**：
- 人机协作 → [drafts](modules/drafts.md) (Interrupts)
- 多模态 → [drafts](modules/drafts.md) (Multimodal Messages)
- 生成式 UI → [generative-ui](modules/generative-ui.md) + [drafts](modules/drafts.md) (Generative UI)
- 推理加密 → [reasoning](modules/reasoning.md)

## 建议使用方式

1. 先阅读 [architecture](modules/architecture.md) 了解核心概念
2. 根据需要查看具体模块
3. 事件类型参考 [events](modules/events.md)
4. 实现细节参考对应功能模块