# 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#常见事件速查) - 高频事件流程