qzlAG-UI 示例脚本
本目录包含 AG-UI 协议的实现示例，帮助开发者快速上手。
前置要求
# 安装依赖
npm install @ag-ui/client rxjs
# 或
pnpm add @ag-ui/client rxjs
示例列表
1. minimal_agent.ts - 最小 Agent 实现
展示如何创建一个最基本的 AG-UI Agent，实现事件流。
核心概念:
- 继承
AbstractAgent类 - 实现
run()方法返回 Observable 事件流 - 发送生命周期事件 (RUN_STARTED/RUN_FINISHED)
- 发送文本消息事件 (TEXT_MESSAGE_START/CONTENT/END)
运行:
# 使用 ts-node
npx ts-node scripts/minimal_agent.ts
# 或编译后运行
npx tsc scripts/minimal_agent.ts --esModuleInterop
node scripts/minimal_agent.js
参考文档: modules/agents.md 行 132-197
2. tool_call_example.ts - 工具调用流程
展示 Agent 如何调用工具并流式传输参数和结果。
核心概念:
- 定义工具 (Tool)
- 工具调用事件流: ToolCallStart → ToolCallArgs → ToolCallEnd → ToolCallResult
- 流式传输工具参数（分块发送）
- 基于工具结果生成响应
事件流:
ToolCallStart (工具名称)
↓
ToolCallArgs (参数片段 1)
ToolCallArgs (参数片段 2)
ToolCallArgs (参数片段 3)
↓
ToolCallEnd (参数传输完成)
↓
ToolCallResult (工具执行结果)
运行:
npx ts-node scripts/tool_call_example.ts
参考文档: modules/events.md 行 938-1066
3. state_sync_example.ts - 状态同步
展示 Agent 与前端的 Snapshot-Delta 状态同步模式。
核心概念:
- StateSnapshot - 完整状态快照
- StateDelta - 增量更新 (JSON Patch RFC 6902)
- MessagesSnapshot - 消息历史快照
- 前端状态管理器实现
状态同步模式:
初始同步:
StateSnapshot (完整状态)
MessagesSnapshot (消息历史)
↓
增量更新:
StateDelta (JSON Patch 操作)
StateDelta (另一个更新)
↓
周期性刷新:
StateSnapshot (确保一致性)
JSON Patch 操作类型:
replace- 替换值add- 添加字段remove- 删除字段
运行:
npx ts-node scripts/state_sync_example.ts
参考文档: modules/events.md 行 1067-1155
常见问题
Q: 这些示例可以直接用于生产环境吗？
A: 这些示例仅用于教学目的。生产环境应考虑：
- 错误处理和重试机制
- 认证和授权
- 日志和监控
- 性能优化（如事件节流）
Q: 如何处理工具调用的并发？
A: 每个工具调用有唯一的 toolCallId，可以并发执行多个工具：
// 工具调用 1
ToolCallStart(toolCallId: "tool_1")
ToolCallArgs(toolCallId: "tool_1", delta: "...")
ToolCallEnd(toolCallId: "tool_1")
// 工具调用 2（并发）
ToolCallStart(toolCallId: "tool_2")
ToolCallArgs(toolCallId: "tool_2", delta: "...")
ToolCallEnd(toolCallId: "tool_2")
Q: StateDelta 的 JSON Patch 格式如何工作？
A: JSON Patch (RFC 6902) 是标准的增量更新格式：
[
{ "op": "replace", "path": "/session/currentPage", "value": 2 },
{ "op": "add", "path": "/formData", "value": {...} },
{ "op": "remove", "path": "/tempField" }
]
推荐使用 fast-json-patch 库处理。
进阶示例
需要更复杂的示例？查看官方仓库：
相关资源
- AG-UI 协议文档 - 完整协议规范
- 模块索引 - 按功能查找文档
- 常见事件速查 - 高频事件流程