qzl
164 lines
3.7 KiB
Markdown
164 lines
3.7 KiB
Markdown
# AG-UI 示例脚本
|
|
|
|
本目录包含 AG-UI 协议的实现示例，帮助开发者快速上手。
|
|
|
|
## 前置要求
|
|
|
|
```bash
|
|
# 安装依赖
|
|
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)
|
|
|
|
**运行**:
|
|
```bash
|
|
# 使用 ts-node
|
|
npx ts-node scripts/minimal_agent.ts
|
|
|
|
# 或编译后运行
|
|
npx tsc scripts/minimal_agent.ts --esModuleInterop
|
|
node scripts/minimal_agent.js
|
|
```
|
|
|
|
**参考文档**: [modules/agents.md](../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 (工具执行结果)
|
|
```
|
|
|
|
**运行**:
|
|
```bash
|
|
npx ts-node scripts/tool_call_example.ts
|
|
```
|
|
|
|
**参考文档**: [modules/events.md](../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` - 删除字段
|
|
|
|
**运行**:
|
|
```bash
|
|
npx ts-node scripts/state_sync_example.ts
|
|
```
|
|
|
|
**参考文档**: [modules/events.md](../modules/events.md) 行 1067-1155
|
|
|
|
---
|
|
|
|
## 常见问题
|
|
|
|
### Q: 这些示例可以直接用于生产环境吗？
|
|
|
|
A: 这些示例仅用于教学目的。生产环境应考虑：
|
|
- 错误处理和重试机制
|
|
- 认证和授权
|
|
- 日志和监控
|
|
- 性能优化（如事件节流）
|
|
|
|
### Q: 如何处理工具调用的并发？
|
|
|
|
A: 每个工具调用有唯一的 `toolCallId`，可以并发执行多个工具：
|
|
```typescript
|
|
// 工具调用 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) 是标准的增量更新格式：
|
|
```json
|
|
[
|
|
{ "op": "replace", "path": "/session/currentPage", "value": 2 },
|
|
{ "op": "add", "path": "/formData", "value": {...} },
|
|
{ "op": "remove", "path": "/tempField" }
|
|
]
|
|
```
|
|
|
|
推荐使用 [fast-json-patch](https://github.com/Starcounter-Jack/Fast-JSON-Patch) 库处理。
|
|
|
|
---
|
|
|
|
## 进阶示例
|
|
|
|
需要更复杂的示例？查看官方仓库：
|
|
- [AG-UI GitHub](https://github.com/ag-ui/ag-ui)
|
|
- [CopilotKit Examples](https://github.com/CopilotKit/CopilotKit/tree/main/examples)
|
|
|
|
---
|
|
|
|
## 相关资源
|
|
|
|
- [AG-UI 协议文档](../llms-full.txt) - 完整协议规范
|
|
- [模块索引](../SKILL.md#模块索引) - 按功能查找文档
|
|
- [常见事件速查](../SKILL.md#常见事件速查) - 高频事件流程
|