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

name, description

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

源文件

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

示例脚本

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

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

运行示例:

# 安装依赖
npm install @ag-ui/client rxjs

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

详见 scripts/README.md

常见事件速查

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

快速路径

新手入门：

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

实现功能：

• 流式响应 → events (TextMessage 事件) + minimal_agent.ts
• 工具调用 → tools + events (ToolCall 事件) + tool_call_example.ts
• 状态同步 → state + events (StateDelta) + state_sync_example.ts
• 中间件 → middleware

高级特性：

• 人机协作 → drafts (Interrupts)
• 多模态 → drafts (Multimodal Messages)
• 生成式 UI → generative-ui + drafts (Generative UI)
• 推理加密 → reasoning

建议使用方式

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