AG-UI 是一份面向协议级集成的技能指南，用于在智能体后端与 UI 客户端之间实现符合 AG-UI 规范的集成，重点保证事件顺序、工具生命周期行为与状态同步语义正确。
用途：当任务属于智能体后端与 UI 客户端之间的协议级集成时使用。若主要问题是图编排或检查点逻辑，应改用 $langgraph；若主要是链或工具编排内部逻辑，应改用 $langchain；若主要是 CopilotKit 的 hooks/provider 行为，应改用 $copilotkit。
工作流程：先定义集成模式，选择客户端 HttpAgent、自定义 AbstractAgent 或中间件桥接；锁定所需事件子集与顺序，在实现前映射生命周期、文本、工具与状态事件；优先实现生命周期，保证所有运行都被 RUN_STARTED 与 RUN_FINISHED/RUN_ERROR 包裹；实现消息与工具流，确保工具调用的 start/args/end/result 序列有效且完整；实现状态同步，明确选择仅快照、仅增量或混合策略；按显式顺序添加中间件，在不改变协议不变量的前提下实现鉴权、过滤与日志；最后用事件轨迹校验，通过确定性重放确认顺序与载荷结构。
默认模式：输出最小有效事件流而非自定义临时载荷；保持工具结果载荷可解析且有界；优先使用显式事件模式而非客户端推断解析；保持协议载荷与传输方式无关。
常见失败模式：生命周期或工具事件乱序；工具调用流不完整、缺少终止结果事件；客户端状态增量应用不匹配；中间件修改载荷导致不符合规范。
参考资料按需加载：事件契约见 references/event-contracts.md，状态同步策略见 references/state-sync.md，中间件用法见 references/middleware-patterns.md，集成清单见 references/integration-checklist.md。具体安装命令与收费信息暂未提供。