# WeKnora Agent Mode 文档 ## 概述 WeKnora Agent Mode 是基于 ReAct (Reasoning + Acting) 框架实现的智能代理系统,能够通过工具调用和迭代推理来回答复杂问题。 ### 核心特性 - **ReAct 框架**: Thought → Action → Observation 循环 - **工具系统**: 7个知识库相关工具 - **可选规划**: 可在执行前生成任务计划 - **事件追踪**: 完整的执行过程可视化 - **灵活配置**: 支持多种参数调整 ## 架构设计 ### Agent 工作流程 ``` 用户查询 ↓ [可选] 生成执行计划 ↓ ┌─────────────────┐ │ ReAct 循环开始 │ ├─────────────────┤ │ 1. Think (思考) │ → LLM 分析当前状态 │ 2. Act (行动) │ → 调用工具获取信息 │ 3. Observe (观察)│ → 处理工具返回结果 │ [可选] Reflect │ → 反思当前步骤 │ 4. Decide (决策)│ → 继续或结束? └─────────────────┘ ↓ 生成最终答案 ``` ### 组件结构 ``` internal/agent/ ├── engine.go # Agent 执行引擎 ├── prompts.go # System prompts └── tools/ # 工具系统 ├── tool.go ├── registry.go ├── knowledge_search.go ├── multi_kb_search.go ├── list_knowledge_bases.go ├── get_chunk_detail.go ├── get_related_chunks.go ├── query_knowledge_graph.go └── get_document_info.go ``` ## 配置说明 ### Agent 配置结构 ```go type AgentConfig struct { Enabled bool // 是否启用 Agent 模式 EnablePlanning bool // 是否先规划 MaxIterations int // 最大迭代次数 (1-20) ReflectionEnabled bool // 是否启用反思 AllowedTools []string // 允许的工具列表 Temperature float64 // LLM 温度 (0-2) ThinkingModelID string // 推理模型 ID KnowledgeBases []string // 可访问的知识库 ID } ``` ### 全局配置 (config.yaml) ```yaml agent: enabled: true default_max_iterations: 5 default_temperature: 0.7 reflection_enabled: false default_tools: - knowledge_search - multi_kb_search - list_knowledge_bases - get_chunk_detail - get_related_chunks - query_knowledge_graph - get_document_info ``` ## 可用工具 ### 1. knowledge_search 搜索指定知识库中的相关内容。 **参数:** - `knowledge_base_id` (必需): 知识库ID - `query` (必需): 搜索查询内容 - `top_k` (可选): 返回结果数量,默认5 **示例:** ``` knowledge_search(knowledge_base_id="kb123", query="什么是RAG", top_k=5) ``` ### 2. multi_kb_search 在多个知识库中智能搜索,自动选择最相关的知识库。 **参数:** - `query` (必需): 搜索查询内容 - `top_k` (可选): 每个知识库返回的结果数量,默认3 **适用场景:** 跨知识库查询,不确定信息在哪个知识库中 ### 3. list_knowledge_bases 列出当前可访问的所有知识库。 **参数:** 无 **用途:** 了解有哪些知识库可以搜索 ### 4. get_chunk_detail 获取指定chunk的详细信息,包括完整内容、来源文档。 **参数:** - `chunk_id` (必需): Chunk ID **用途:** 当搜索结果不够详细时获取完整内容 ### 5. get_related_chunks 获取与指定chunk相关的其他chunks。 **参数:** - `chunk_id` (必需): Chunk ID - `relation_type` (可选): "sequential" (顺序) 或 "semantic" (语义) - `limit` (可选): 返回数量,默认5 **用途:** 发现相关信息,扩展上下文 ### 6. query_knowledge_graph 查询知识图谱中的实体和关系。 **参数:** - `knowledge_base_id` (必需): 知识库ID - `query` (必需): 查询内容(实体名称或查询文本) **前提:** 知识库已配置知识图谱抽取 ### 7. get_document_info 获取文档的元数据信息。 **参数:** - `knowledge_id` (必需): 文档/知识ID **用途:** 了解文档的整体情况 ## 使用指南 ### 创建 Agent Session ```bash POST /api/v1/sessions { "knowledge_base_id": "kb123", "session_strategy": { "summary_model_id": "model123", ... }, "agent_config": { "enabled": true, "enable_planning": false, "max_iterations": 5, "reflection_enabled": false, "allowed_tools": [ "knowledge_search", "multi_kb_search", "list_knowledge_bases" ], "temperature": 0.7, "knowledge_bases": ["kb123", "kb456"] } } ``` ### 发起 Agent 查询 ```bash POST /api/v1/sessions/{session_id}/agent-qa { "query": "请解释RAG技术的工作原理" } ``` ### 响应格式 Agent 会返回 SSE (Server-Sent Events) 流式响应: 1. **知识引用** (可选) ```json { "response_type": "references", "knowledge_references": [...] } ``` 2. **Agent 思考过程** (可选,用于调试) ```json { "response_type": "agent_thought", "content": "我需要先搜索相关知识..." } ``` 3. **工具调用** (可选) ```json { "response_type": "agent_action", "content": "调用工具: knowledge_search" } ``` 4. **最终答案** ```json { "response_type": "answer", "content": "RAG技术的工作原理是...", "done": true } ``` ## 最佳实践 ### 1. 工具选择策略 - **已知知识库**: 使用 `knowledge_search` - **不确定位置**: 使用 `multi_kb_search` - **需要上下文**: 使用 `get_related_chunks` - **探索阶段**: 先用 `list_knowledge_bases` ### 2. 迭代次数设置 - **简单查询**: 3-5 次 - **复杂问题**: 5-10 次 - **探索性任务**: 10-15 次 - **最大限制**: 20 次 (防止无限循环) ### 3. 温度参数 - **精确查询**: 0.3-0.5 (更确定性) - **创造性任务**: 0.7-1.0 (更多样性) - **默认推荐**: 0.7 ### 4. Planning 启用时机 - **复杂多步骤任务**: 启用 - **简单直接查询**: 禁用 - **探索性问题**: 启用 ### 5. Reflection 启用时机 - **关键任务**: 启用 (提高准确性) - **快速响应**: 禁用 (减少延迟) - **默认**: 禁用 ## 工作原理详解 ### ReAct Prompt Template ``` 你是一个智能知识库助手。你的任务是通过使用提供的工具来回答用户问题。 工作流程: 1. 分析用户问题,确定需要什么信息 2. 使用合适的工具获取信息(可以多次调用不同工具) 3. 基于获取的信息,提供准确、完整的答案 注意事项: - 优先使用 multi_kb_search 进行跨知识库搜索 - 如果需要特定知识库,先用 list_knowledge_bases 查看可用知识库 - 如果搜索结果不够详细,使用 get_chunk_detail 获取完整内容 - 使用 get_related_chunks 发现相关信息 - 如果涉及实体关系,使用 query_knowledge_graph - 引用信息时,说明来源(chunk_id 或 knowledge_base) - 如果找不到相关信息,诚实告知用户 当前可访问的知识库: {knowledge_bases} {plan_context} ``` ### 工具调用解析 Agent 会尝试从 LLM 输出中解析工具调用,支持的格式: ``` tool_name(arg1="value1", arg2="value2") ``` 例如: ``` knowledge_search(knowledge_base_id="kb123", query="RAG技术") ``` ### 循环控制 Agent 会在以下情况停止: 1. LLM 输出包含 "最终答案" 或 "Final Answer" 2. 达到最大迭代次数 3. 工具调用失败且无法恢复 4. 检测到重复循环模式 ## 事件追踪 Agent 执行过程中会发送以下事件 (通过 Event Bus): ### agent.plan ```go type AgentPlanData struct { Query string Plan []string Duration int64 } ``` ### agent.step ```go type AgentStepData struct { Iteration int Thought string ToolCalls []ToolCall Duration int64 } ``` ### agent.tool ```go type AgentActionData struct { Iteration int ToolName string ToolInput map[string]interface{} ToolOutput string Success bool Error string Duration int64 } ``` ## 示例场景 ### 场景 1: 简单知识查询 **用户问题**: "什么是 RAG?" **Agent 执行流程**: 1. **Think**: 需要搜索 RAG 相关知识 2. **Act**: `multi_kb_search(query="RAG")` 3. **Observe**: 获得3条相关结果 4. **Think**: 信息足够,可以回答 5. **Final Answer**: 基于搜索结果生成答案 **迭代次数**: 2 ### 场景 2: 跨文档关联查询 **用户问题**: "比较 RAG 和微调的优缺点" **Agent 执行流程**: 1. **Think**: 需要分别查找 RAG 和微调的信息 2. **Act**: `multi_kb_search(query="RAG优缺点")` 3. **Observe**: 获得 RAG 相关信息 4. **Think**: 还需要微调的信息 5. **Act**: `multi_kb_search(query="模型微调优缺点")` 6. **Observe**: 获得微调相关信息 7. **Think**: 信息完整,进行对比 8. **Final Answer**: 综合两者信息生成对比答案 **迭代次数**: 4 ### 场景 3: 深入探索 **用户问题**: "详细解释向量数据库的工作原理" **Agent 执行流程**: 1. **Think**: 先查看有哪些知识库 2. **Act**: `list_knowledge_bases()` 3. **Observe**: 发现有"数据库技术"知识库 4. **Think**: 在该知识库中搜索 5. **Act**: `knowledge_search(knowledge_base_id="db_kb", query="向量数据库")` 6. **Observe**: 找到相关 chunk 7. **Think**: 需要更多细节 8. **Act**: `get_chunk_detail(chunk_id="chunk123")` 9. **Observe**: 获得完整内容 10. **Think**: 查看相关内容 11. **Act**: `get_related_chunks(chunk_id="chunk123", relation_type="sequential")` 12. **Observe**: 获得上下文 13. **Final Answer**: 基于详细信息生成深入解释 **迭代次数**: 7 ## 常见问题 ### Q: Agent 和普通 RAG 有什么区别? **A**: - **普通 RAG**: 一次性检索 → 生成答案 - **Agent**: 可以多次迭代,根据中间结果调整策略,调用不同工具 ### Q: 什么时候使用 Agent 模式? **A**: - 需要多步推理的复杂问题 - 需要在多个知识库中查找信息 - 需要深入探索和关联分析 - 问题模糊,需要澄清和逐步细化 ### Q: Agent 模式的成本如何? **A**: - **Token 消耗**: 比普通 RAG 高 (多次 LLM 调用) - **响应时间**: 较长 (迭代执行) - **准确性**: 通常更高 (多步验证) ### Q: 如何优化 Agent 性能? **A**: 1. 合理设置 `max_iterations` (避免过多) 2. 选择必要的工具 (`allowed_tools`) 3. 禁用不需要的功能 (planning, reflection) 4. 使用更快的模型作为 thinking_model ### Q: 工具调用失败怎么办? **A**: Agent 会: 1. 在 Observation 中记录错误 2. 尝试使用其他工具 3. 如果多次失败,会在最终答案中说明 ## 技术限制与注意事项 ### 当前限制 1. **工具调用解析**: 使用简单的模式匹配,可能无法处理复杂格式 2. **Function Calling**: 当前使用 prompt-based 方式,未来可升级为原生 function calling 3. **并行工具调用**: 当前不支持,工具按顺序执行 4. **图谱查询**: 当前使用 hybrid search,完整图谱功能开发中 ### 未来改进 - [ ] 支持 LLM 原生 function calling (GPT-4, Claude 等) - [ ] 并行工具执行 - [ ] 更智能的循环检测 - [ ] 工具结果缓存 - [ ] 自定义工具注册 - [ ] Agent 执行可视化 UI ## 开发指南 ### 创建自定义工具 ```go package tools import ( "context" "github.com/Tencent/WeKnora/internal/types" ) type CustomTool struct { BaseTool // 添加依赖 } func NewCustomTool() *CustomTool { return &CustomTool{ BaseTool: NewBaseTool( "custom_tool", "工具描述", ), } } func (t *CustomTool) Parameters() map[string]interface{} { return map[string]interface{}{ "type": "object", "properties": map[string]interface{}{ "param1": map[string]interface{}{ "type": "string", "description": "参数描述", }, }, "required": []string{"param1"}, } } func (t *CustomTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { // 实现工具逻辑 param1 := args["param1"].(string) // 执行操作 result := doSomething(param1) return &types.ToolResult{ Success: true, Output: result, Data: map[string]interface{}{}, }, nil } ``` ### 注册自定义工具 在 `agent_service.go` 的 `registerTools` 方法中添加: ```go case "custom_tool": registry.RegisterTool(tools.NewCustomTool()) ``` ## 总结 WeKnora Agent Mode 提供了强大的迭代推理能力,适用于复杂的知识查询场景。通过合理配置和工具选择,可以在准确性和效率之间找到最佳平衡点。 如有问题或建议,请提交 Issue 或 Pull Request。