chore: 清理opencode技能文件、旧设计文档并更新配置文档
This commit is contained in:
qzl
@@ -1,111 +0,0 @@
|
||||
---
|
||||
name: ag-ui
|
||||
description: 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](modules/protocol.md) | 协议概述，与 MCP、A2A 关系 | 1-33 |
|
||||
| [agents](modules/agents.md) | Agent 概念、架构、类型、实现 | 35-451 |
|
||||
| [architecture](modules/architecture.md) | 核心架构、设计原则、运行机制 | 453-679 |
|
||||
| [events](modules/events.md) | 所有事件类型详解 | 680-1475 |
|
||||
| [generative-ui](modules/generative-ui.md) | 生成式 UI 规范（A2UI/MCP-UI） | 1476-1496 |
|
||||
| [messages](modules/messages.md) | 消息结构、类型、同步机制 | 1498-1952 |
|
||||
| [middleware](modules/middleware.md) | 中间件：转换、过滤、增强事件流 | 1954-2158 |
|
||||
| [reasoning](modules/reasoning.md) | LLM 推理支持，加密推理内容 | 2160-2638 |
|
||||
| [serialization](modules/serialization.md) | 事件流序列化、压缩、分支 | 2640-2827 |
|
||||
| [state](modules/state.md) | Agent 与前端状态同步 | 2829-3080 |
|
||||
| [tools](modules/tools.md) | 工具定义、调用生命周期 | 3082-3441 |
|
||||
| [drafts](modules/drafts.md) | 提案功能：Generative UI, Interrupts, Meta Events, Multimodal | 3492-4846 |
|
||||
| [contributing](modules/contributing.md) | 贡献指南、路线图、更新日志 | 3443-3485 |
|
||||
| [overview](modules/overview.md) | **AG-UI 协议总体介绍** | 4894-5261 |
|
||||
|
||||
## 源文件
|
||||
|
||||
- `llms-full.txt` - AG-UI 协议完整文档（唯一信源，10632 行）
|
||||
- `scripts/` - 可执行示例代码（见下方"示例脚本"）
|
||||
|
||||
## 示例脚本
|
||||
|
||||
`scripts/` 目录包含可直接运行的 TypeScript 示例：
|
||||
|
||||
| 示例 | 用途 | 参考文档 |
|
||||
|------|------|---------|
|
||||
| [minimal_agent.ts](scripts/minimal_agent.ts) | 最小 Agent 实现 | [agents](modules/agents.md) 行 132-197 |
|
||||
| [tool_call_example.ts](scripts/tool_call_example.ts) | 工具调用流程 | [events](modules/events.md) 行 938-1066 |
|
||||
| [state_sync_example.ts](scripts/state_sync_example.ts) | Snapshot-Delta 状态同步 | [events](modules/events.md) 行 1067-1155 |
|
||||
|
||||
**运行示例**:
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm install @ag-ui/client rxjs
|
||||
|
||||
# 运行
|
||||
npx ts-node scripts/minimal_agent.ts
|
||||
```
|
||||
|
||||
详见 [scripts/README.md](scripts/README.md)
|
||||
|
||||
## 常见事件速查
|
||||
|
||||
| 场景 | 关键事件 | 详见 |
|
||||
|------|---------|------|
|
||||
| 流式响应 | TextMessageStart → Content → End | [events](modules/events.md) 行 835-937 |
|
||||
| 工具调用 | ToolCallStart → Args → End → Result | [events](modules/events.md) 行 938-1066 |
|
||||
| 状态同步 | StateSnapshot, StateDelta | [events](modules/events.md) 行 1067-1155 |
|
||||
| 生命周期 | RunStarted/Finished, StepStarted/Finished | [events](modules/events.md) 行 715-754 |
|
||||
| 人机中断 | RunFinished(interrupt) | [drafts](modules/drafts.md) 行 3897-3920 |
|
||||
|
||||
## 快速路径
|
||||
|
||||
**新手入门**：
|
||||
1. [overview](modules/overview.md) - **理解 AG-UI 协议全貌与定位**
|
||||
2. [protocol](modules/protocol.md) - AG-UI 在 AI 协议栈的位置（与 MCP/A2A 关系）
|
||||
3. [architecture](modules/architecture.md) - 核心概念与设计原则
|
||||
4. [agents](modules/agents.md) - Agent 基础实现
|
||||
5. 运行 [minimal_agent.ts](scripts/minimal_agent.ts) 体验基础事件流
|
||||
|
||||
**实现功能**：
|
||||
- 流式响应 → [events](modules/events.md) (TextMessage 事件) + [minimal_agent.ts](scripts/minimal_agent.ts)
|
||||
- 工具调用 → [tools](modules/tools.md) + [events](modules/events.md) (ToolCall 事件) + [tool_call_example.ts](scripts/tool_call_example.ts)
|
||||
- 状态同步 → [state](modules/state.md) + [events](modules/events.md) (StateDelta) + [state_sync_example.ts](scripts/state_sync_example.ts)
|
||||
- 中间件 → [middleware](modules/middleware.md)
|
||||
|
||||
**高级特性**：
|
||||
- 人机协作 → [drafts](modules/drafts.md) (Interrupts)
|
||||
- 多模态 → [drafts](modules/drafts.md) (Multimodal Messages)
|
||||
- 生成式 UI → [generative-ui](modules/generative-ui.md) + [drafts](modules/drafts.md) (Generative UI)
|
||||
- 推理加密 → [reasoning](modules/reasoning.md)
|
||||
|
||||
## 建议使用方式
|
||||
|
||||
1. 先阅读 [architecture](modules/architecture.md) 了解核心概念
|
||||
2. 根据需要查看具体模块
|
||||
3. 事件类型参考 [events](modules/events.md)
|
||||
4. 实现细节参考对应功能模块
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,16 +0,0 @@
|
||||
# Agents
|
||||
|
||||
**作用**: 介绍 AG-UI 中 Agent 的概念、架构、类型和实现方式。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 35-451
|
||||
|
||||
**内容索引**:
|
||||
- 什么是 Agent (行 47-62)
|
||||
- Agent Architecture - AbstractAgent, 核心组件 (行 63-91)
|
||||
- Agent Types - HttpAgent, Custom Agents (行 93-130)
|
||||
- Implementing Agents - 基本实现示例 (行 132-197)
|
||||
- Agent Capabilities - 交互通信、工具使用、状态管理、多 Agent 协作、人机协作、对话记忆 (行 199-358)
|
||||
- 使用 Agent (行 360-399)
|
||||
- Agent Configuration (行 401-424)
|
||||
- Agent State Management (行 426-439)
|
||||
@@ -1,17 +0,0 @@
|
||||
# Core Architecture
|
||||
|
||||
**作用**: 介绍 AG-UI 的核心架构、设计原则和运行机制。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 453-679
|
||||
|
||||
**内容索引**:
|
||||
- Design Principles - 事件驱动、双向交互、灵活中间件 (行 463-489)
|
||||
- Architectural Overview - 客户端-服务器架构 (行 491-534)
|
||||
- Protocol layer - run(input) -> Observable<BaseEvent> (行 537-567)
|
||||
- Standard HTTP client - HttpAgent, SSE/HTTP binary (行 569-585)
|
||||
- Message types - Lifecycle, Text, Tool, State, Special 事件 (行 587-609)
|
||||
- Running Agents (行 611-640)
|
||||
- State Management - STATE_SNAPSHOT, STATE_DELTA (行 642-652)
|
||||
- Tools and Handoff (行 653-662)
|
||||
- Base Event 属性 (行 664-677)
|
||||
@@ -1,15 +0,0 @@
|
||||
# Contributing & Roadmap
|
||||
|
||||
**作用**: 贡献指南、路线图和更新日志。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 3443-3485
|
||||
|
||||
**内容索引**:
|
||||
- Contributing (行 3443-3460):
|
||||
- Naming conventions - integrations/, wip-, community- 前缀 (行 3448-3459)
|
||||
- Roadmap (行 3462-3481):
|
||||
- 公开路线图链接 (行 3467-3468)
|
||||
- Get Involved - 贡献方式 (行 3470-3474)
|
||||
- What's New (行 3477-3485):
|
||||
- 2025-04-09: AG-UI 仓库公开发布 (行 3482-3484)
|
||||
@@ -1,53 +0,0 @@
|
||||
# Drafts
|
||||
|
||||
**作用**: 介绍 AG-UI 协议中正在考虑或开发中的提案功能。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 3492-3854 (Generative UI), 3860-4105 (Interrupts), 4111-4349 (Meta Events), 4355-4846 (Multimodal)
|
||||
|
||||
**Drafts 概述** (行 4847-4887):
|
||||
- Drafts 状态定义 - Draft/Under Review/Accepted/Implemented/Withdrawn (行 4880-4886)
|
||||
|
||||
**Generative User Interfaces** (行 3492-3854):
|
||||
- Summary - 问题陈述与动机 (行 3494-3508)
|
||||
- Challenges and Limitations - 工具描述长度、JSON Schema 约束 (行 3515-3531)
|
||||
- Detailed Specification:
|
||||
- Two-Step Generation Process - 两步生成流程图 (行 3535-3543)
|
||||
- Step 1: What to Generate? - generateUserInterface 工具 (行 3545-3596)
|
||||
- Step 2: How to Generate? - 次级 LLM 生成实际 UI (行 3598-3612)
|
||||
- Implementation Examples:
|
||||
- UISchemaGenerator - JSON Schema 输出 (行 3615-3673)
|
||||
- ReactFormHookGenerator - React Hook Form 代码生成 (行 3675-3795)
|
||||
- Implementation Considerations - SDK 变更 (行 3797-3819)
|
||||
- Use Cases - 动态表单、数据可视化、交互式工作流 (行 3821-3838)
|
||||
|
||||
**Interrupt-Aware Run Lifecycle** (行 3860-4105):
|
||||
- Summary - 人机协作暂停机制 (行 3862-3875)
|
||||
- Updates to RUN_FINISHED Event - outcome, interrupt 字段 (行 3897-3920)
|
||||
- Updates to RunAgentInput - resume 字段 (行 3922-3937)
|
||||
- Contract Rules (行 3939-3945)
|
||||
- Implementation Examples (行 3947-4026)
|
||||
- Use Cases - 人类批准、信息收集、策略强制 (行 4028-4051)
|
||||
- Implementation Considerations (行 4052-4091)
|
||||
|
||||
**Meta Events** (行 4111-4349):
|
||||
- Summary - 独立于 Agent 运行的事件注解 (行 4115-4127)
|
||||
- MetaEvent Type - metaType, payload (行 4145-4170)
|
||||
- Implementation Examples:
|
||||
- User Feedback - thumbs_up, thumbs_down (行 4174-4206)
|
||||
- Annotations - note, tag (行 4208-4239)
|
||||
- External System Events - analytics, moderation (行 4241-4276)
|
||||
- Common Meta Event Types 表 (行 4278-4292)
|
||||
- Use Cases (行 4294-4318)
|
||||
|
||||
**Multimodal Messages** (行 4355-4846):
|
||||
- Summary - 支持多模态输入消息 (行 4357-4371)
|
||||
- Status: Implemented (行 4373-4376)
|
||||
- Detailed Specification:
|
||||
- Modality Types 表 - text, image, audio, video, document (行 4473-4483)
|
||||
- Source Types - InputContentDataSource, InputContentUrlSource (行 4485-4509)
|
||||
- Content Part Types - TextInputPart, ImageInputPart, AudioInputPart, VideoInputPart, DocumentInputPart (行 4511-4561)
|
||||
- Provider Metadata (行 4562-4571)
|
||||
- Implementation Examples (行 4573-4764)
|
||||
- Implementation Considerations (行 4766-4798)
|
||||
- Use Cases (行 4800-4827)
|
||||
@@ -1,20 +0,0 @@
|
||||
# Events
|
||||
|
||||
**作用**: 详细介绍 AG-UI 协议中的所有事件类型，包括生命周期、文本、工具调用、状态管理、推理等事件。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 680-1475
|
||||
|
||||
**内容索引**:
|
||||
- Event Types Overview - 事件分类表 (行 692-703)
|
||||
- Base Event Properties (行 705-713)
|
||||
- Lifecycle Events - RunStarted, RunFinished, RunError, StepStarted, StepFinished (行 715-754)
|
||||
- Text Message Events - TextMessageStart, TextMessageContent, TextMessageEnd, TextMessageChunk (行 835-937)
|
||||
- Tool Call Events - ToolCallStart, ToolCallArgs, ToolCallEnd, ToolCallResult, ToolCallChunk (行 938-1066)
|
||||
- State Management Events - StateSnapshot, StateDelta, MessagesSnapshot (行 1067-1155)
|
||||
- Activity Events - ActivitySnapshot, ActivityDelta (行 1156-1189)
|
||||
- Special Events - Raw, Custom (行 1191-1233)
|
||||
- Reasoning Events - ReasoningStart, ReasoningMessageStart/Content/End/Chunk, ReasoningEnd, ReasoningEncryptedValue (行 1234-1368)
|
||||
- Deprecated Events - THINKING_* 事件迁移 (行 1369-1389)
|
||||
- Draft Events - Meta Events, Modified Lifecycle Events (行 1391-1446)
|
||||
- Event Flow Patterns - Start-Content-End, Snapshot-Delta, Lifecycle (行 1447-1474)
|
||||
@@ -1,11 +0,0 @@
|
||||
# Generative UI Specs
|
||||
|
||||
**作用**: 介绍 AG-UI 与生成式 UI 规范的关系（A2UI、MCP-UI、Open-JSON-UI）。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 1476-1496
|
||||
|
||||
**内容索引**:
|
||||
- AG-UI and Generative UI Specs - AG-UI 不是生成式 UI 规范，而是用户交互协议 (行 1476-1496)
|
||||
- AG-UI 与 A2UI、MCP-UI、Open-JSON-UI 的关系说明
|
||||
- Generative UI 实现详情见 [drafts](drafts.md) 的 Generative User Interfaces 章节 (行 3492-3854)
|
||||
@@ -1,21 +0,0 @@
|
||||
# Messages
|
||||
|
||||
**作用**: 介绍 AG-UI 中消息的结构、类型和同步机制。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 1498-1952
|
||||
|
||||
**内容索引**:
|
||||
- Message Structure - BaseMessage 接口, role, encryptedContent (行 1510-1537)
|
||||
- Message Types:
|
||||
- UserMessage - 用户消息, 支持多模态 InputContent (行 1543-1576)
|
||||
- AssistantMessage - 助手消息, 含 toolCalls (行 1578-1591)
|
||||
- SystemMessage - 系统消息 (行 1593-1604)
|
||||
- ToolMessage - 工具结果消息 (行 1606-1627)
|
||||
- ActivityMessage - 前端专用活动消息 (行 1628-1653)
|
||||
- DeveloperMessage - 开发/调试消息 (行 1654-1665)
|
||||
- ReasoningMessage - 推理消息 (行 1667-1704)
|
||||
- Vendor Neutrality - 供应商中立性, 格式转换示例 (行 1705-1735)
|
||||
- Message Synchronization - MESSAGES_SNAPSHOT, 流式消息 (行 1736-1794)
|
||||
- Tool Integration - ToolCall, ToolResult 结构 (行 1795-1889)
|
||||
- Practical Example - 完整对话示例 (行 1891-1939)
|
||||
@@ -1,18 +0,0 @@
|
||||
# Middleware
|
||||
|
||||
**作用**: 介绍 AG-UI 中间件，用于转换、过滤和增强事件流。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 1954-2158
|
||||
|
||||
**内容索引**:
|
||||
- What is Middleware? - 中间件的作用 (行 1965-1973)
|
||||
- How Middleware Works - 中间件链式调用 (行 1975-1991)
|
||||
- Function-Based Middleware - 函数式中间件示例 (行 1993-2019)
|
||||
- Class-Based Middleware - 类中间件示例 (行 2021-2055)
|
||||
- Built-in Middleware - FilterToolCallsMiddleware (行 2062-2086)
|
||||
- Middleware Patterns - 日志、认证、限流 (行 2088-2090)
|
||||
- Combining Middleware (行 2092-2103)
|
||||
- Execution Order - 中间件执行顺序 (行 2104-2124)
|
||||
- Best Practices (行 2126-2134)
|
||||
- Conditional Middleware (行 2136-2153)
|
||||
@@ -1,28 +0,0 @@
|
||||
# AG-UI Overview
|
||||
|
||||
**作用**: AG-UI 协议总体介绍，包括协议定位、核心特性、与其他协议的关系、以及构建块概览。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 4894-5261
|
||||
|
||||
**内容索引**:
|
||||
- 协议定义 - 开放、轻量、事件驱动的 Agent-User 交互协议 (行 4894-4901)
|
||||
- Agentic Protocols - MCP/A2A/AG-UI 三层协议栈 (行 4910-4923)
|
||||
- Building Blocks (行 4926-5088):
|
||||
- Streaming chat - 流式对话 (行 4930-4941)
|
||||
- Tool calling - 工具调用 (行 4943-4953)
|
||||
- Structured state - 结构化状态 (行 4955-4965)
|
||||
- Generative UI - 生成式 UI (行 4967-4977)
|
||||
- Contextual context - 上下文管理 (行 4979-4989)
|
||||
- Client-side tools - 客户端工具 (行 4991-5001)
|
||||
- Auth & multi-tenancy - 认证与多租户 (行 5003-5013)
|
||||
- Debugging & evals - 调试与评估 (行 5015-5025)
|
||||
- Upcoming: Reasoning continuity - 推理连续性 (行 5027-5037)
|
||||
- Upcoming: Multi-modal - 多模态 (行 5039-5049)
|
||||
- Upcoming: Generative UI - 生成式 UI (行 5051-5061)
|
||||
- Upcoming: Interrupts & approval flows - 中断与审批流程 (行 5063-5073)
|
||||
- Upcoming: Meta events - 元事件 (行 5075-5085)
|
||||
- Protocol Basics (行 5090-5261):
|
||||
- Agent Definition - Agent 定义 (行 5095-5109)
|
||||
- Event Stream - 事件流 (行 5111-5129)
|
||||
- Common Patterns - 常见模式 (行 5131-5151)
|
||||
@@ -1,11 +0,0 @@
|
||||
# Protocol
|
||||
|
||||
**作用**: 介绍 AG-UI 与 MCP、A2A 协议的关系，以及 AG-UI 作为连接 Agent 与用户应用的协议定位。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 1-33
|
||||
|
||||
**内容索引**:
|
||||
- Agentic Protocols 概述 (MCP, A2A, AG-UI)
|
||||
- AG-UI 与 MCP、A2A 的握手
|
||||
- Generative UI Specs 介绍
|
||||
@@ -1,26 +0,0 @@
|
||||
# Reasoning
|
||||
|
||||
**作用**: 介绍 AG-UI 对 LLM 推理的支持，包括链式思维可视化和加密推理内容。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 2160-2638
|
||||
|
||||
**内容索引**:
|
||||
- Overview - 推理可见性、状态连续性、隐私合规 (行 2171-2188)
|
||||
- ReasoningMessage - 推理消息结构 (行 2190-2217)
|
||||
- Reasoning Events:
|
||||
- Event Flow - 推理事件流程图 (行 2223-2246)
|
||||
- Event Types 表 (行 2248-2258)
|
||||
- Privacy and Compliance:
|
||||
- Zero Data Retention (ZDR) - 零数据保留 (行 2264-2273)
|
||||
- Visibility Control - 可见性控制 (行 2274-2284)
|
||||
- Compliance Considerations 表 - GDPR, SOC 2, HIPAA (行 2285-2293)
|
||||
- Example Implementations:
|
||||
- Basic Reasoning Flow (行 2296-2348)
|
||||
- Encrypted Content for State Continuity (行 2350-2396)
|
||||
- Attaching Encrypted Reasoning to Tool Calls (行 2398-2430)
|
||||
- ZDR-Compliant Implementation (行 2432-2475)
|
||||
- Using Convenience Chunk Event (行 2477-2503)
|
||||
- Client Integration - 处理推理事件, 传递加密推理 (行 2505-2563)
|
||||
- Migration from Thinking Events - THINKING_* 迁移到 REASONING_* (行 2565-2617)
|
||||
- Best Practices (行 2619-2632)
|
||||
@@ -1,21 +0,0 @@
|
||||
# Serialization
|
||||
|
||||
**作用**: 介绍 AG-UI 事件流的序列化，用于历史恢复、分支和时间旅行。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 2640-2827
|
||||
|
||||
**内容索引**:
|
||||
- Core Concepts:
|
||||
- Stream serialization - 事件流转为 JSON (行 2660-2662)
|
||||
- Event compaction - 压缩事件流 (行 2662-2663)
|
||||
- Run lineage - parentRunId 实现 git 类日志 (行 2664-2665)
|
||||
- Updated Event Fields - RunStarted 新增 parentRunId, input (行 2667-2685)
|
||||
- Event Compaction - compactEvents 函数, 压缩规则 (行 2686-2704)
|
||||
- Branching and Time Travel - parentRunId 创建分支, git 类日志 (行 2705-2729)
|
||||
- Examples:
|
||||
- Basic Serialization (行 2732-2744)
|
||||
- Event Compaction - 压缩前后示例 (行 2746-2774)
|
||||
- Branching With parentRunId (行 2776-2795)
|
||||
- Normalized Input (行 2797-2814)
|
||||
- Implementation Notes (行 2816-2822)
|
||||
@@ -1,18 +0,0 @@
|
||||
# State Management
|
||||
|
||||
**作用**: 介绍 AG-UI 中 Agent 与前端之间的状态同步机制。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 2829-3080
|
||||
|
||||
**内容索引**:
|
||||
- Shared State Architecture - 共享状态架构, 双向通信 (行 2842-2857)
|
||||
- State Synchronization Methods:
|
||||
- State Snapshots - STATE_SNAPSHOT 事件 (行 2862-2882)
|
||||
- State Deltas - STATE_DELTA 事件, JSON Patch (行 2884-2902)
|
||||
- JSON Patch Format:
|
||||
- RFC 6902 操作: add, replace, remove, move, copy, test (行 2903-2944)
|
||||
- State Processing in AG-ui - fast-json-patch 使用示例 (行 2946-2977)
|
||||
- Human-in-the-Loop Collaboration - 人机协作示例 (行 2978-3005)
|
||||
- CopilotKit Implementation - useCoAgent, copilotkit_emit_state (行 3007-3050)
|
||||
- Best Practices (行 3052-3068)
|
||||
@@ -1,24 +0,0 @@
|
||||
# Tools
|
||||
|
||||
**作用**: 介绍 AG-UI 中工具的定义、使用和人在环工作流。
|
||||
|
||||
**源文件**: `llms-full.txt`
|
||||
**行号范围**: 3082-3441
|
||||
|
||||
**内容索引**:
|
||||
- What Are Tools? - 工具的作用 (行 3095-3105)
|
||||
- Tool Structure - Tool 接口定义 (行 3107-3130)
|
||||
- Frontend-Defined Tools - 工具由前端定义并传递给 Agent (行 3132-3175)
|
||||
- Tool Call Lifecycle:
|
||||
- ToolCallStart (行 3179-3191)
|
||||
- ToolCallArgs - 流式参数 (行 3193-3217)
|
||||
- ToolCallEnd (行 3219-3229)
|
||||
- Tool Results - ToolMessage 结构 (行 3231-3246)
|
||||
- Human-in-the-Loop Workflows - 人机协作工作流 (行 3248-3270)
|
||||
- CopilotKit Integration - useCopilotAction hook (行 3272-3304)
|
||||
- Tool Examples:
|
||||
- User Confirmation (行 3310-3332)
|
||||
- Data Retrieval (行 3334-3358)
|
||||
- User Interface Control (行 3360-3381)
|
||||
- Content Generation (行 3383-3412)
|
||||
- Best Practices (行 3414-3428)
|
||||
@@ -1,163 +0,0 @@
|
||||
# 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#常见事件速查) - 高频事件流程
|
||||
@@ -1,99 +0,0 @@
|
||||
/**
|
||||
* 最小 AG-UI Agent 实现示例
|
||||
*
|
||||
* 展示如何创建一个自定义 Agent，实现基本的事件流
|
||||
*
|
||||
* 参考文档: modules/agents.md (行 132-197)
|
||||
*/
|
||||
|
||||
import {
|
||||
AbstractAgent,
|
||||
RunAgent,
|
||||
RunAgentInput,
|
||||
EventType,
|
||||
BaseEvent,
|
||||
} from "@ag-ui/client"
|
||||
import { Observable } from "rxjs"
|
||||
|
||||
class MinimalAgent extends AbstractAgent {
|
||||
/**
|
||||
* 实现 run 方法，返回事件流
|
||||
*/
|
||||
run(input: RunAgentInput): RunAgent {
|
||||
const { threadId, runId } = input
|
||||
|
||||
return () =>
|
||||
new Observable<BaseEvent>((observer) => {
|
||||
// 1. 发送 RUN_STARTED 事件
|
||||
observer.next({
|
||||
type: EventType.RUN_STARTED,
|
||||
threadId,
|
||||
runId,
|
||||
})
|
||||
|
||||
// 2. 发送文本消息
|
||||
const messageId = Date.now().toString()
|
||||
|
||||
// 消息开始
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_START,
|
||||
messageId,
|
||||
role: "assistant",
|
||||
})
|
||||
|
||||
// 消息内容（流式）
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_CONTENT,
|
||||
messageId,
|
||||
delta: "Hello! ",
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_CONTENT,
|
||||
messageId,
|
||||
delta: "I'm a minimal AG-UI agent.",
|
||||
})
|
||||
|
||||
// 消息结束
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_END,
|
||||
messageId,
|
||||
})
|
||||
|
||||
// 3. 发送 RUN_FINISHED 事件
|
||||
observer.next({
|
||||
type: EventType.RUN_FINISHED,
|
||||
threadId,
|
||||
runId,
|
||||
})
|
||||
|
||||
// 完成流
|
||||
observer.complete()
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// 使用示例
|
||||
const agent = new MinimalAgent({
|
||||
agentId: "minimal-agent",
|
||||
description: "A minimal AG-UI agent example",
|
||||
})
|
||||
|
||||
// 运行 Agent 并订阅事件流
|
||||
agent
|
||||
.runAgent({
|
||||
runId: "run_123",
|
||||
threadId: "thread_456",
|
||||
messages: [],
|
||||
tools: [],
|
||||
context: [],
|
||||
})
|
||||
.subscribe({
|
||||
next: (event) => {
|
||||
console.log(`[${event.type}]`, event)
|
||||
},
|
||||
error: (error) => console.error("Error:", error),
|
||||
complete: () => console.log("Agent run completed"),
|
||||
})
|
||||
|
||||
export { MinimalAgent }
|
||||
@@ -1,255 +0,0 @@
|
||||
/**
|
||||
* AG-UI 状态同步示例
|
||||
*
|
||||
* 展示 Agent 与前端的 Snapshot-Delta 状态同步模式
|
||||
*
|
||||
* 参考文档: modules/events.md (行 1067-1155)
|
||||
*
|
||||
* 状态管理模式:
|
||||
* 1. StateSnapshot - 完整状态快照（初始同步/周期性刷新）
|
||||
* 2. StateDelta - 增量更新（JSON Patch RFC 6902）
|
||||
* 3. MessagesSnapshot - 消息历史快照
|
||||
*/
|
||||
|
||||
import {
|
||||
AbstractAgent,
|
||||
RunAgent,
|
||||
RunAgentInput,
|
||||
EventType,
|
||||
BaseEvent,
|
||||
} from "@ag-ui/client"
|
||||
import { Observable } from "rxjs"
|
||||
|
||||
/**
|
||||
* Agent 状态定义示例
|
||||
*/
|
||||
interface AgentState {
|
||||
user: {
|
||||
name: string
|
||||
preferences: {
|
||||
theme: "light" | "dark"
|
||||
language: string
|
||||
}
|
||||
}
|
||||
session: {
|
||||
currentPage: number
|
||||
itemsPerPage: number
|
||||
totalItems: number
|
||||
}
|
||||
formData?: {
|
||||
[key: string]: any
|
||||
}
|
||||
}
|
||||
|
||||
class StateSyncAgent extends AbstractAgent {
|
||||
private state: AgentState = {
|
||||
user: {
|
||||
name: "Alice",
|
||||
preferences: {
|
||||
theme: "light",
|
||||
language: "en",
|
||||
},
|
||||
},
|
||||
session: {
|
||||
currentPage: 1,
|
||||
itemsPerPage: 10,
|
||||
totalItems: 100,
|
||||
},
|
||||
}
|
||||
|
||||
run(input: RunAgentInput): RunAgent {
|
||||
const { threadId, runId } = input
|
||||
|
||||
return () =>
|
||||
new Observable<BaseEvent>((observer) => {
|
||||
observer.next({
|
||||
type: EventType.RUN_STARTED,
|
||||
threadId,
|
||||
runId,
|
||||
})
|
||||
|
||||
// 1. 发送初始状态快照
|
||||
observer.next({
|
||||
type: EventType.STATE_SNAPSHOT,
|
||||
snapshot: this.state,
|
||||
})
|
||||
|
||||
// 2. 发送消息历史快照
|
||||
observer.next({
|
||||
type: EventType.MESSAGES_SNAPSHOT,
|
||||
messages: [
|
||||
{
|
||||
id: "msg_1",
|
||||
role: "user",
|
||||
content: "Show me page 2",
|
||||
},
|
||||
{
|
||||
id: "msg_2",
|
||||
role: "assistant",
|
||||
content: "Loading page 2...",
|
||||
},
|
||||
],
|
||||
})
|
||||
|
||||
// 3. 模拟状态变化 - 分页更新
|
||||
setTimeout(() => {
|
||||
// 发送 Delta 更新（JSON Patch 格式）
|
||||
observer.next({
|
||||
type: EventType.STATE_DELTA,
|
||||
delta: [
|
||||
{ op: "replace", path: "/session/currentPage", value: 2 },
|
||||
],
|
||||
})
|
||||
}, 500)
|
||||
|
||||
// 4. 模拟用户偏好更新
|
||||
setTimeout(() => {
|
||||
observer.next({
|
||||
type: EventType.STATE_DELTA,
|
||||
delta: [
|
||||
{ op: "replace", path: "/user/preferences/theme", value: "dark" },
|
||||
],
|
||||
})
|
||||
}, 1000)
|
||||
|
||||
// 5. 添加新字段（表单数据）
|
||||
setTimeout(() => {
|
||||
observer.next({
|
||||
type: EventType.STATE_DELTA,
|
||||
delta: [
|
||||
{
|
||||
op: "add",
|
||||
path: "/formData",
|
||||
value: {
|
||||
searchQuery: "AG-UI tutorial",
|
||||
filters: ["beginner", "typescript"],
|
||||
},
|
||||
},
|
||||
],
|
||||
})
|
||||
}, 1500)
|
||||
|
||||
// 6. 周期性完整快照（确保状态一致性）
|
||||
setTimeout(() => {
|
||||
const updatedState: AgentState = {
|
||||
...this.state,
|
||||
session: {
|
||||
...this.state.session,
|
||||
currentPage: 2,
|
||||
},
|
||||
user: {
|
||||
...this.state.user,
|
||||
preferences: {
|
||||
...this.state.user.preferences,
|
||||
theme: "dark",
|
||||
},
|
||||
},
|
||||
formData: {
|
||||
searchQuery: "AG-UI tutorial",
|
||||
filters: ["beginner", "typescript"],
|
||||
},
|
||||
}
|
||||
|
||||
observer.next({
|
||||
type: EventType.STATE_SNAPSHOT,
|
||||
snapshot: updatedState,
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.RUN_FINISHED,
|
||||
threadId,
|
||||
runId,
|
||||
})
|
||||
|
||||
observer.complete()
|
||||
}, 2000)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 前端状态管理示例（接收端）
|
||||
*/
|
||||
class StateManager {
|
||||
private state: AgentState | null = null
|
||||
|
||||
handleEvent(event: BaseEvent) {
|
||||
switch (event.type) {
|
||||
case EventType.STATE_SNAPSHOT:
|
||||
// 完整替换状态
|
||||
this.state = (event as any).snapshot as AgentState
|
||||
console.log("[State] Snapshot received:", this.state)
|
||||
break
|
||||
|
||||
case EventType.STATE_DELTA:
|
||||
// 应用 JSON Patch 增量更新
|
||||
if (this.state) {
|
||||
const patches = (event as any).delta
|
||||
this.state = this.applyPatches(this.state, patches)
|
||||
console.log("[State] Delta applied:", patches)
|
||||
console.log("[State] Current state:", this.state)
|
||||
}
|
||||
break
|
||||
|
||||
case EventType.MESSAGES_SNAPSHOT:
|
||||
console.log("[Messages] Snapshot:", (event as any).messages)
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 应用 JSON Patch 操作（简化实现）
|
||||
* 生产环境应使用 json-patch 库
|
||||
*/
|
||||
private applyPatches(state: AgentState, patches: any[]): AgentState {
|
||||
const newState = JSON.parse(JSON.stringify(state))
|
||||
|
||||
for (const patch of patches) {
|
||||
const { op, path, value } = patch
|
||||
const pathParts = path.split("/").filter(Boolean)
|
||||
let target: any = newState
|
||||
|
||||
// 导航到目标对象的父级
|
||||
for (let i = 0; i < pathParts.length - 1; i++) {
|
||||
target = target[pathParts[i]]
|
||||
}
|
||||
|
||||
const lastKey = pathParts[pathParts.length - 1]
|
||||
|
||||
switch (op) {
|
||||
case "replace":
|
||||
target[lastKey] = value
|
||||
break
|
||||
case "add":
|
||||
target[lastKey] = value
|
||||
break
|
||||
case "remove":
|
||||
delete target[lastKey]
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
return newState
|
||||
}
|
||||
}
|
||||
|
||||
// 使用示例
|
||||
const agent = new StateSyncAgent()
|
||||
const stateManager = new StateManager()
|
||||
|
||||
agent
|
||||
.runAgent({
|
||||
runId: "run_state_sync",
|
||||
threadId: "thread_123",
|
||||
messages: [],
|
||||
tools: [],
|
||||
context: [],
|
||||
})
|
||||
.subscribe({
|
||||
next: (event) => {
|
||||
stateManager.handleEvent(event)
|
||||
},
|
||||
complete: () => console.log("\n[Complete] State sync demo finished"),
|
||||
})
|
||||
|
||||
export { StateSyncAgent, StateManager, AgentState }
|
||||
@@ -1,201 +0,0 @@
|
||||
/**
|
||||
* AG-UI 工具调用示例
|
||||
*
|
||||
* 展示 Agent 如何调用工具并流式传输参数和结果
|
||||
*
|
||||
* 参考文档: modules/events.md (行 938-1066)
|
||||
*
|
||||
* 事件流:
|
||||
* 1. ToolCallStart - 工具调用开始
|
||||
* 2. ToolCallArgs (多次) - 流式传输参数
|
||||
* 3. ToolCallEnd - 参数传输完成
|
||||
* 4. ToolCallResult - 工具执行结果
|
||||
*/
|
||||
|
||||
import {
|
||||
AbstractAgent,
|
||||
RunAgent,
|
||||
RunAgentInput,
|
||||
EventType,
|
||||
BaseEvent,
|
||||
} from "@ag-ui/client"
|
||||
import { Observable } from "rxjs"
|
||||
|
||||
/**
|
||||
* 工具定义示例
|
||||
*/
|
||||
interface Tool {
|
||||
name: string
|
||||
description: string
|
||||
parameters: Record<string, unknown>
|
||||
}
|
||||
|
||||
const weatherTool: Tool = {
|
||||
name: "get_weather",
|
||||
description: "Get current weather for a location",
|
||||
parameters: {
|
||||
type: "object",
|
||||
properties: {
|
||||
location: {
|
||||
type: "string",
|
||||
description: "City name",
|
||||
},
|
||||
unit: {
|
||||
type: "string",
|
||||
enum: ["celsius", "fahrenheit"],
|
||||
},
|
||||
},
|
||||
required: ["location"],
|
||||
},
|
||||
}
|
||||
|
||||
class ToolCallingAgent extends AbstractAgent {
|
||||
run(input: RunAgentInput): RunAgent {
|
||||
const { threadId, runId } = input
|
||||
|
||||
return () =>
|
||||
new Observable<BaseEvent>((observer) => {
|
||||
observer.next({
|
||||
type: EventType.RUN_STARTED,
|
||||
threadId,
|
||||
runId,
|
||||
})
|
||||
|
||||
// 模拟 Agent 分析用户请求后决定调用工具
|
||||
const toolCallId = `tool_${Date.now()}`
|
||||
const messageId = `msg_${Date.now()}`
|
||||
|
||||
// 1. 发送文本消息说明
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_START,
|
||||
messageId,
|
||||
role: "assistant",
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_CONTENT,
|
||||
messageId,
|
||||
delta: "Let me check the weather for you.",
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_END,
|
||||
messageId,
|
||||
})
|
||||
|
||||
// 2. 开始工具调用
|
||||
observer.next({
|
||||
type: EventType.TOOL_CALL_START,
|
||||
toolCallId,
|
||||
toolCallName: "get_weather",
|
||||
parentMessageId: messageId,
|
||||
})
|
||||
|
||||
// 3. 流式传输参数（分块发送）
|
||||
observer.next({
|
||||
type: EventType.TOOL_CALL_ARGS,
|
||||
toolCallId,
|
||||
delta: '{"loc', // 参数片段 1
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.TOOL_CALL_ARGS,
|
||||
toolCallId,
|
||||
delta: 'ation":', // 参数片段 2
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.TOOL_CALL_ARGS,
|
||||
toolCallId,
|
||||
delta: ' "San Francisco"}', // 参数片段 3
|
||||
})
|
||||
|
||||
// 4. 参数传输完成
|
||||
observer.next({
|
||||
type: EventType.TOOL_CALL_END,
|
||||
toolCallId,
|
||||
})
|
||||
|
||||
// 5. 工具执行结果（模拟）
|
||||
setTimeout(() => {
|
||||
observer.next({
|
||||
type: EventType.TOOL_CALL_RESULT,
|
||||
toolCallId,
|
||||
content: JSON.stringify({
|
||||
location: "San Francisco",
|
||||
temperature: "18°C",
|
||||
condition: "Partly cloudy",
|
||||
}),
|
||||
})
|
||||
|
||||
// 6. 基于工具结果的响应
|
||||
const responseMsgId = `msg_${Date.now()}_response`
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_START,
|
||||
messageId: responseMsgId,
|
||||
role: "assistant",
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_CONTENT,
|
||||
messageId: responseMsgId,
|
||||
delta: "The current weather in San Francisco is 18°C and partly cloudy.",
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.TEXT_MESSAGE_END,
|
||||
messageId: responseMsgId,
|
||||
})
|
||||
|
||||
observer.next({
|
||||
type: EventType.RUN_FINISHED,
|
||||
threadId,
|
||||
runId,
|
||||
})
|
||||
|
||||
observer.complete()
|
||||
}, 1000)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// 使用示例
|
||||
const agent = new ToolCallingAgent()
|
||||
|
||||
agent
|
||||
.runAgent({
|
||||
runId: "run_tool_example",
|
||||
threadId: "thread_123",
|
||||
messages: [
|
||||
{
|
||||
id: "user_1",
|
||||
role: "user",
|
||||
content: "What's the weather in San Francisco?",
|
||||
},
|
||||
],
|
||||
tools: [weatherTool as any],
|
||||
context: [],
|
||||
})
|
||||
.subscribe({
|
||||
next: (event) => {
|
||||
switch (event.type) {
|
||||
case EventType.TOOL_CALL_START:
|
||||
console.log(`[Tool Call] Starting: ${(event as any).toolCallName}`)
|
||||
break
|
||||
case EventType.TOOL_CALL_ARGS:
|
||||
process.stdout.write((event as any).delta)
|
||||
break
|
||||
case EventType.TOOL_CALL_END:
|
||||
console.log("\n[Tool Call] Arguments complete")
|
||||
break
|
||||
case EventType.TOOL_CALL_RESULT:
|
||||
console.log("[Tool Result]", (event as any).content)
|
||||
break
|
||||
default:
|
||||
console.log(`[${event.type}]`)
|
||||
}
|
||||
},
|
||||
complete: () => console.log("Tool call flow completed"),
|
||||
})
|
||||
|
||||
export { ToolCallingAgent, weatherTool }
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
name: crewai
|
||||
description: CrewAI framework for multi-agent orchestration. Use when building multi-agent systems, agent collaboration, task automation, crew orchestration, agent teams, delegation, or any CrewAI-related development.
|
||||
---
|
||||
|
||||
# CrewAI Skills
|
||||
|
||||
CrewAI 框架开发权威指南。**必须使用**场景：构建多 Agent 协作系统、编排 Agent 团队、任务自动化、工具集成、知识管理、LLM 应用开发。提供完整模块索引与源文件行号映射。
|
||||
|
||||
## 何时使用
|
||||
|
||||
**必须使用**的场景：
|
||||
- 创建和管理 AI Agent 团队
|
||||
- 实现 Agent 间的协作和任务委托
|
||||
- 编排多步骤工作流和任务流程
|
||||
- 集成 RAG、向量存储和知识管理
|
||||
- 配置和管理 LLM 提供商
|
||||
- 构建自动化任务和工具
|
||||
- 实现 Agent 记忆和推理能力
|
||||
- 训练和微调 Agent 性能
|
||||
|
||||
**查询模式**：
|
||||
- "如何创建 crewai agent"
|
||||
- "agent collaboration 委托任务"
|
||||
- "crew kickoff 执行流程"
|
||||
- "crewai tools 集成"
|
||||
- "knowledge RAG 配置"
|
||||
- "llm 多模型切换"
|
||||
|
||||
## 模块索引
|
||||
|
||||
按功能模块查看源文件对应章节：
|
||||
|
||||
| 模块 | 作用 | 源文件行号 |
|
||||
|------|------|------------|
|
||||
| [agents](modules/agents.md) | Agent 概念、属性、创建、高级特性 | 1-1276 |
|
||||
| [collaboration](modules/collaboration.md) | Agent 协作、委托、层级管理 | 1277-1655 |
|
||||
| [crews](modules/crews.md) | Crew 概念、创建、执行流程 | 1656-2658 |
|
||||
| [flows](modules/flows.md) | Flow 流程控制、状态管理 | 2659-3712 |
|
||||
| [knowledge](modules/knowledge.md) | 知识管理、向量存储、RAG | 3713-4838 |
|
||||
| [llms](modules/llms.md) | LLM 配置、多模型支持 | 4839-6469 |
|
||||
| [memory](modules/memory.md) | Memory 记忆系统 | 6470-7341 |
|
||||
| [planning](modules/planning.md) | Planning 任务规划 | 7342-7729 |
|
||||
| [reasoning](modules/reasoning.md) | Reasoning 推理和反思 | 7730-7877 |
|
||||
| [tasks](modules/tasks.md) | Task 概念、属性、执行流程 | 7878-9005 |
|
||||
| [tools](modules/tools.md) | Tool 概念、创建、内置工具 | 9006-9292 |
|
||||
| [training](modules/training.md) | Training 训练和微调 | 9293-12843 |
|
||||
| [installation](modules/installation.md) | 安装、配置、项目创建 | 12844-14875 |
|
||||
| [quickstart-tools](modules/quickstart-tools.md) | **快速开始 + 50+ 工具参考** | 14876-53221 |
|
||||
|
||||
## 源文件
|
||||
|
||||
- `llms-full.md` - CrewAI 完整文档（唯一信源，53221 行）
|
||||
|
||||
## 核心概念速查
|
||||
|
||||
| 概念 | 说明 | 详见 |
|
||||
|------|------|------|
|
||||
| **Agent** | 自主单元，执行任务、使用工具、协作 | [agents](modules/agents.md) |
|
||||
| **Task** | Agent 完成的具体任务 | [tasks](modules/tasks.md) |
|
||||
| **Crew** | Agent 团队，协作完成任务 | [crews](modules/crews.md) |
|
||||
| **Tool** | Agent 可用的能力或功能 | [tools](modules/tools.md) |
|
||||
| **Flow** | 工作流编排和状态管理 | [flows](modules/flows.md) |
|
||||
| **Knowledge** | 知识存储和 RAG 检索 | [knowledge](modules/knowledge.md) |
|
||||
|
||||
## 快速路径
|
||||
|
||||
**新手入门**：
|
||||
1. [installation](modules/installation.md) - 安装和项目创建
|
||||
2. [agents](modules/agents.md) - 理解 Agent 核心概念
|
||||
3. [tasks](modules/tasks.md) - 创建第一个 Task
|
||||
4. [crews](modules/crews.md) - 组建 Crew 并执行
|
||||
5. [quickstart-tools](modules/quickstart-tools.md) - 完整快速开始示例
|
||||
|
||||
**实现功能**：
|
||||
- Agent 协作 → [collaboration](modules/collaboration.md) (委托、层级)
|
||||
- 任务编排 → [crews](modules/crews.md) + [flows](modules/flows.md)
|
||||
- 知识管理 → [knowledge](modules/knowledge.md) (RAG、向量存储)
|
||||
- 工具集成 → [tools](modules/tools.md) + [quickstart-tools](modules/quickstart-tools.md)
|
||||
- LLM 配置 → [llms](modules/llms.md)
|
||||
|
||||
**高级特性**：
|
||||
- Agent 记忆 → [memory](modules/memory.md)
|
||||
- 任务规划 → [planning](modules/planning.md)
|
||||
- 推理能力 → [reasoning](modules/reasoning.md)
|
||||
- 性能优化 → [training](modules/training.md)
|
||||
|
||||
## 建议使用方式
|
||||
|
||||
1. 先阅读 [installation](modules/installation.md) 了解安装和项目结构
|
||||
2. 根据需求查看核心概念模块（agents/tasks/crews/tools）
|
||||
3. 高级功能参考对应模块（collaboration/knowledge/flows）
|
||||
4. 工具集成参考 [quickstart-tools](modules/quickstart-tools.md)
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,18 +0,0 @@
|
||||
# Agents
|
||||
|
||||
**作用**: 介绍 CrewAI 中 Agent 的概念、属性、创建方式和高级特性。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 1-1276
|
||||
|
||||
**内容索引**:
|
||||
- Overview of an Agent - Agent 定义和核心能力 (行 6-22)
|
||||
- Agent Attributes - 完整属性表 (行 37-68)
|
||||
- Creating Agents (行 70-741):
|
||||
- YAML Configuration (推荐) (行 74-115)
|
||||
- Direct Code Definition (行 117-155)
|
||||
- 完整参数示例 (行 156-357)
|
||||
- Tools 配置 (行 358-365)
|
||||
- Context Management (行 366-543)
|
||||
- Structured Output (行 578-741)
|
||||
- CLI - 命令行工具 (行 742-1276)
|
||||
@@ -1,20 +0,0 @@
|
||||
# Collaboration
|
||||
|
||||
**作用**: 介绍 Agent 间的协作机制，包括任务委托、层级管理和最佳实践。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 1277-1655
|
||||
|
||||
**内容索引**:
|
||||
- Enable collaboration for agents - 启用协作 (行 1291-1323)
|
||||
- Delegation Tools - 委托工具 (行 1325-1343):
|
||||
- Delegate work to coworker (行 1326)
|
||||
- Ask question to coworker (行 1335)
|
||||
- Implementation Examples (行 1345-1445):
|
||||
- Collaborative agents 示例 (行 1345-1386)
|
||||
- Hierarchical crew 示例 (行 1447-1481)
|
||||
- Best Practices (行 1495-1597):
|
||||
- 角色定义 (行 1495-1514)
|
||||
- 任务依赖 (行 1525-1545)
|
||||
- 常见问题和解决方案 (行 1556-1597)
|
||||
- Collaboration Guidelines (行 1598-1655)
|
||||
@@ -1,20 +0,0 @@
|
||||
# Crews
|
||||
|
||||
**作用**: 介绍 Crew 的概念、创建方式、执行流程和高级特性。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 1656-2658
|
||||
|
||||
**内容索引**:
|
||||
- Crew Overview - Crew 定义 (行 1656-1891)
|
||||
- Example crew execution - 执行示例 (行 1892-1900)
|
||||
- Accessing crew output (行 1901-1918)
|
||||
- Save crew logs (行 1919-1938)
|
||||
- Usage metrics (行 1939-1954)
|
||||
- Execution Methods (行 1955-2024):
|
||||
- kickoff() - 同步执行 (行 1955-1988)
|
||||
- kickoff_for_each() - 批量执行 (行 1989-2010)
|
||||
- kickoff_async() - 异步执行 (行 1995-2024)
|
||||
- Streaming - 流式输出 (行 2025-2073)
|
||||
- Event Listeners - 事件监听器 (行 2074-2245)
|
||||
- Files - 文件处理 (行 2387-2658)
|
||||
@@ -1,13 +0,0 @@
|
||||
# Flows
|
||||
|
||||
**作用**: 介绍 Flow 的概念、状态管理、流程控制和与 Crew 的集成。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 2659-3712
|
||||
|
||||
**内容索引**:
|
||||
- Flow Overview - Flow 定义和用途 (行 2659-3293)
|
||||
- Structured Output - 结构化输出 (行 3294-3371)
|
||||
- Usage example (行 3372-3379)
|
||||
- Run the flow (行 3380-3538)
|
||||
- Streaming - 流式输出 (行 3539-3712)
|
||||
@@ -1,13 +0,0 @@
|
||||
# Installation
|
||||
|
||||
**作用**: 介绍 CrewAI 的安装、配置和项目创建。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 12844-14875
|
||||
|
||||
**内容索引**:
|
||||
- Installation Guide - 安装指南 (行 12844-12944)
|
||||
- Creating a CrewAI Project - 项目创建 (行 12945-13047)
|
||||
- What is CrewAI? - 框架介绍 (行 13053-13179)
|
||||
- MCP Integration - MCP 集成 (行 13763-14450)
|
||||
- Quickstart Guide - 快速开始 (行 14876-15252)
|
||||
@@ -1,17 +0,0 @@
|
||||
# Knowledge
|
||||
|
||||
**作用**: 介绍 Knowledge 的概念、知识源、向量存储和 RAG 集成。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 3713-4838
|
||||
|
||||
**内容索引**:
|
||||
- Knowledge Overview - 知识管理概念 (行 3713-3750)
|
||||
- Vector Stores - 向量存储 (行 3751-3780):
|
||||
- ChromaDB (默认) (行 3751-3755)
|
||||
- Qdrant (行 3756-3760)
|
||||
- Knowledge Sources (行 3781-3952):
|
||||
- 创建知识源 (行 3781-3824)
|
||||
- Web content (行 3825-3835)
|
||||
- Agent-level vs Crew-level (行 3953-4000)
|
||||
- Advanced Usage (行 4001-4838)
|
||||
@@ -1,11 +0,0 @@
|
||||
# LLMs
|
||||
|
||||
**作用**: 介绍 LLM 配置、多模型支持、自定义 LLM 和最佳实践。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 4839-6469
|
||||
|
||||
**内容索引**:
|
||||
- LLM Overview - LLM 配置概念 (行 4839-6281)
|
||||
- Supported Providers - 支持的 LLM 提供商 (行 6282-6469)
|
||||
- Custom LLM Integration (行 6990-7496)
|
||||
@@ -1,11 +0,0 @@
|
||||
# Memory
|
||||
|
||||
**作用**: 介绍 Memory 的概念、类型、配置和使用场景。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 6470-7341
|
||||
|
||||
**内容索引**:
|
||||
- Memory Overview - 记忆系统概念 (行 6470-7341)
|
||||
- Memory Types - 记忆类型 (行 6470-7341)
|
||||
- Configuration and Usage (行 6470-7341)
|
||||
@@ -1,10 +0,0 @@
|
||||
# Planning
|
||||
|
||||
**作用**: 介绍 Planning 功能、任务规划和自动化流程设计。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 7342-7729
|
||||
|
||||
**内容索引**:
|
||||
- Planning Overview - 任务规划概念 (行 7342-7571)
|
||||
- Flow-First Mindset - 流程优先思维 (行 7572-7729)
|
||||
@@ -1,52 +0,0 @@
|
||||
# Quickstart & Tools Reference
|
||||
|
||||
**作用**: 快速开始指南和完整的工具集成参考。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 14876-53221
|
||||
|
||||
**内容索引**:
|
||||
- Quickstart Guide - 快速开始 (行 14876-15252)
|
||||
- Core Tools (行 15253-16645):
|
||||
- AI Mind Tool (行 15253-15338)
|
||||
- Code Interpreter (行 15373-15582)
|
||||
- DALL-E Tool (行 15583-15635)
|
||||
- LangChain Tool (行 15636-15694)
|
||||
- LlamaIndex Tool (行 15695-15841)
|
||||
- RAG Tool (行 15906-16595)
|
||||
- Vision Tool (行 16596-16645)
|
||||
- Cloud & Database Tools (行 16646-18003):
|
||||
- MongoDB Vector Search (行 16698-16864)
|
||||
- MySQL RAG Search (行 16865-16934)
|
||||
- NL2SQL Tool (行 16935-17104)
|
||||
- PG RAG Search (行 17105-17187)
|
||||
- Qdrant Vector Search (行 17188-17542)
|
||||
- SingleStore Search (行 17543-17602)
|
||||
- Snowflake Search (行 17603-17732)
|
||||
- Weaviate Vector Search (行 17806-17973)
|
||||
- File Tools (行 17974-18868):
|
||||
- CSV RAG Search (行 17974-18051)
|
||||
- Directory Read (行 18052-18105)
|
||||
- Directory RAG Search (行 18106-18175)
|
||||
- DOCX RAG Search (行 18176-18255)
|
||||
- File Read (行 18256-18300)
|
||||
- File Write (行 18301-18351)
|
||||
- JSON RAG Search (行 18352-18427)
|
||||
- MDX RAG Search (行 18428-18499)
|
||||
- OCR Tool (行 18500-18684)
|
||||
- PDF Text Writing (行 18685-18759)
|
||||
- PDF RAG Search (行 18760-18868)
|
||||
- TXT RAG Search (行 18869-18966)
|
||||
- XML RAG Search (行 18967-19044)
|
||||
- Search & Research Tools (行 19045-20000+):
|
||||
- Tools Overview (行 19045-19128)
|
||||
- Arxiv Paper Tool (行 19151-19262)
|
||||
- Brave Search (行 19263-19341)
|
||||
- Code Docs RAG Search (行 19360-19445)
|
||||
- Databricks SQL Query (行 19446-19524)
|
||||
- EXA Search Web Loader (行 19525-19579)
|
||||
- Github Search (行 19580-19666)
|
||||
- Linkup Search (行 19667-19737)
|
||||
- SerpApi Tools (行 19738-20000+)
|
||||
|
||||
**注**: 此章节包含 50+ 工具的详细文档，按类别组织
|
||||
@@ -1,10 +0,0 @@
|
||||
# Reasoning
|
||||
|
||||
**作用**: 介绍 Reasoning 功能、反思机制和任务执行前的规划。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 7730-7877
|
||||
|
||||
**内容索引**:
|
||||
- Reasoning Overview - 推理和反思概念 (行 7730-7877)
|
||||
- Configuration (行 7730-7877)
|
||||
@@ -1,20 +0,0 @@
|
||||
# Tasks
|
||||
|
||||
**作用**: 介绍 Task 的概念、属性、创建方式、执行流程和高级特性。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 7878-9005
|
||||
|
||||
**内容索引**:
|
||||
- Task Overview - Task 定义 (行 7883-7902)
|
||||
- Task Execution Flow - 执行流程 (行 7904-7919)
|
||||
- Task Attributes - 完整属性表 (行 7921-7994)
|
||||
- Creating Tasks (行 7995-8277):
|
||||
- YAML Configuration (行 7995-8125)
|
||||
- Direct Code Definition (行 8126-8161)
|
||||
- Markdown formatting (行 8162-8277)
|
||||
- Advanced Features (行 8278-9005):
|
||||
- Guardrails - 任务护栏 (行 8396-8547)
|
||||
- Callbacks (行 8548-8657)
|
||||
- Output files (行 8658-8773)
|
||||
- Execute tasks (行 9112-9227)
|
||||
@@ -1,13 +0,0 @@
|
||||
# Tools
|
||||
|
||||
**作用**: 介绍 Tool 的概念、创建方式、内置工具和自定义工具。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 9006-9292
|
||||
|
||||
**内容索引**:
|
||||
- Tools Overview - 工具概念 (行 9006-9292)
|
||||
- Creating Custom Tools (行 9006-9292)
|
||||
- Built-in Tools List (行 9006-9292)
|
||||
|
||||
**注**: 完整的工具集成文档见 Quickstart 章节 (行 14876-53221)
|
||||
@@ -1,12 +0,0 @@
|
||||
# Training
|
||||
|
||||
**作用**: 介绍 Training 功能、模型训练、微调和性能优化。
|
||||
|
||||
**源文件**: `llms-full.md`
|
||||
**行号范围**: 9293-12843
|
||||
|
||||
**内容索引**:
|
||||
- Training Overview - 训练概念 (行 9293-9494)
|
||||
- Training Methods (行 9495-12843)
|
||||
- Best Practices (行 9616-9725)
|
||||
- Custom Templates (行 9953-10166)
|
||||
Reference in New Issue
Block a user