admin/aiagent
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add AI学习助手 agent (KG+RAG ideal) and renshenguo feishu bot

Browse Source 
- Add AI学习助手 agent creation script with all 39 tools, 3-layer KG+RAG memory
- Add renshenguo (人参果) feishu bot integration (app_service + ws_handler)
- Register renshenguo WS client in main.py startup
- Add RENSHENGUO_APP_ID / RENSHENGUO_APP_SECRET / RENSHENGUO_AGENT_ID config
- Reorganize docs from root into docs/ subdirectories
- Move startup scripts to scripts/startup/
- Various backend optimizations and tool improvements

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renjianbo
2026-05-06 01:37:13 +08:00
parent f33bc461ff
commit eabf90c496
171 changed files with 4906 additions and 445 deletions
Download Patch File Download Diff File Expand all files Collapse all files

751
docs/agent-guides/(红头)Agent搭建通用方法指南.md Normal file
View File

@@ -0,0 +1,751 @@
# Agent搭建通用方法指南
## 📖 概述
本文档提供了一套通用的Agent搭建方法，适用于在平台上创建各种类型的智能Agent。无论是要创建聊天助手、数据分析Agent、工具调用Agent还是其他类型的智能体，都可以参考本指南。
---
## 🎯 Agent搭建的核心原则
### 1. 明确Agent的目标和职责
- ✅ **单一职责原则**: 每个Agent应该专注于解决一个特定问题
- ✅ **清晰的功能边界**: 明确定义Agent能做什么、不能做什么
- ✅ **用户价值导向**: 确保Agent能够为用户提供实际价值
### 2. 设计合理的工作流
- ✅ **流程清晰**: 工作流应该逻辑清晰，易于理解和维护
- ✅ **节点职责明确**: 每个节点应该有明确的输入和输出
- ✅ **错误处理**: 考虑异常情况的处理流程
### 3. 充分利用平台能力
- ✅ **工具调用**: 合理使用内置工具和自定义工具
- ✅ **记忆管理**: 对于需要上下文记忆的场景，使用缓存节点
- ✅ **条件分支**: 使用Switch节点处理不同的业务逻辑
---
## 📋 Agent搭建标准流程
### 阶段1: 需求分析和设计
#### 1.1 明确需求
- **用户场景**: 谁将使用这个Agent？在什么场景下使用？
- **核心功能**: Agent需要完成什么任务？
- **输入输出**: 用户输入什么？Agent输出什么？
- **性能要求**: 响应时间、准确性等要求
**示例**:
```
需求: 创建一个Android日志获取Agent
- 用户场景: 开发人员需要快速获取Android设备日志
- 核心功能: 通过ADB命令获取和分析日志
- 输入: 自然语言请求（如"获取错误日志"）
- 输出: 格式化的日志内容和分析结果
- 性能要求: 响应时间<30秒，支持100行日志
```
#### 1.2 设计工作流架构
- **节点规划**: 需要哪些类型的节点？
- **数据流**: 数据如何在节点间传递？
- **分支逻辑**: 是否需要条件分支？
- **工具需求**: 需要哪些工具支持？
**常见工作流模式**:
**模式1: 简单线性流程**
```
开始 → 处理 → 输出 → 结束
```
适用于: 简单的单步处理任务
**模式2: 意图识别+分支处理**
```
开始 → 意图识别 → Switch → [分支1/分支2/分支3] → 合并 → 结束
```
适用于: 需要根据用户意图执行不同操作
**模式3: 工具调用流程**
```
开始 → 参数提取 → 工具调用 → 结果分析 → 结束
```
适用于: 需要调用外部工具或API
**模式4: 记忆管理流程**
```
开始 → 查询记忆 → 合并上下文 → 处理 → 更新记忆 → 结束
```
适用于: 需要上下文记忆的多轮对话
**模式5: 复杂组合流程**
```
开始 → 意图识别 → Switch → [工具调用/记忆查询/数据处理] → 结果合并 → 格式化 → 结束
```
适用于: 复杂的多步骤任务
---
### 阶段2: 工具准备（如需要）
#### 2.1 评估工具需求
- **是否需要自定义工具?**
- 如果平台内置工具可以满足需求，直接使用
- 如果需要特殊功能，考虑创建自定义工具
#### 2.2 创建自定义工具（如需要）
**步骤1: 实现工具函数**
```python
# backend/app/services/builtin_tools.py
async def my_custom_tool(
param1: str,
param2: Optional[int] = None,
timeout: int = 10
) -> str:
"""
自定义工具函数
Args:
param1: 参数1说明
param2: 参数2说明（可选）
timeout: 超时时间（秒）
Returns:
JSON格式的执行结果
"""
try:
# 实现工具逻辑
result = {
"success": True,
"data": "...",
"timestamp": datetime.now().isoformat()
}
return json.dumps(result, ensure_ascii=False)
except Exception as e:
logger.error(f"工具执行失败: {str(e)}")
return json.dumps({"error": str(e)}, ensure_ascii=False)
```
**步骤2: 定义工具Schema**
```python
MY_CUSTOM_TOOL_SCHEMA = {
"type": "function",
"function": {
"name": "my_custom_tool",
"description": "工具功能描述",
"parameters": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "参数1说明"
},
"param2": {
"type": "integer",
"description": "参数2说明（可选）"
},
"timeout": {
"type": "integer",
"description": "超时时间（秒）",
"default": 10
}
},
"required": ["param1"]
}
}
}
```
**步骤3: 注册工具**
```python
# backend/app/main.py
from app.services.builtin_tools import (
my_custom_tool,
MY_CUSTOM_TOOL_SCHEMA
)
tool_registry.register_builtin_tool("my_custom_tool", my_custom_tool, MY_CUSTOM_TOOL_SCHEMA)
```
**工具开发最佳实践**:
- ✅ 参数验证: 验证输入参数的合法性
- ✅ 超时控制: 设置合理的超时时间
- ✅ 错误处理: 完善的异常处理和错误信息
- ✅ 日志记录: 记录工具执行情况
- ✅ 安全考虑: 防止命令注入、SQL注入等安全问题
- ✅ 返回格式: 统一使用JSON格式返回
---
### 阶段3: 工作流节点设计
#### 3.1 开始节点
- **作用**: 接收用户输入
- **配置**: 通常不需要特殊配置
- **输出**: 用户输入数据
```json
{
"id": "start",
"type": "start",
"position": {"x": 100, "y": 200},
"data": {
"label": "开始"
}
}
```
#### 3.2 LLM节点（意图识别/处理）
- **作用**: 理解用户意图、生成回复、调用工具
- **配置要点**:
- **Provider和Model**: 选择合适的LLM提供商和模型
- **Temperature**:
- 意图识别: 0.3（更确定）
- 生成回复: 0.7（更有创造性）
- **Max Tokens**: 根据输出长度需求设置
- **Prompt设计**: 清晰、具体、包含示例
**Prompt设计原则**:
- ✅ **明确任务**: 清楚说明需要做什么
- ✅ **提供上下文**: 包含必要的上下文信息
- ✅ **输出格式**: 明确指定输出格式（JSON/文本）
- ✅ **示例引导**: 提供示例帮助理解
- ✅ **变量引用**: 使用 `{{变量名}}` 引用上游节点数据
**示例Prompt**:
```
你是一个专业的意图分析助手。请分析用户的输入，识别用户的意图。
用户输入：{{input.query}}
对话历史：{{memory.conversation_history}}
请以JSON格式输出分析结果：
{
"intent": "意图类型",
"parameters": {
"key1": "value1",
"key2": "value2"
}
}
请确保输出是有效的JSON格式，不要包含其他文字。
```
#### 3.3 JSON节点
- **作用**: 解析、提取、格式化JSON数据
- **常用操作**:
- `parse`: 解析JSON字符串
- `stringify`: 将对象转换为JSON字符串
- `extract`: 使用JSONPath提取数据
**示例配置**:
```json
{
"id": "json-parse",
"type": "json",
"position": {"x": 400, "y": 200},
"data": {
"label": "解析参数",
"operation": "parse",
"json_path": "$"
}
}
```
#### 3.4 缓存节点（记忆管理）
- **作用**: 存储和检索对话历史、用户信息等
- **操作类型**:
- `get`: 获取缓存数据
- `set`: 设置缓存数据
- `update`: 更新缓存数据
**示例配置**:
```json
{
"id": "cache-query",
"type": "cache",
"position": {"x": 300, "y": 200},
"data": {
"label": "查询记忆",
"operation": "get",
"key": "user_memory_{user_id}",
"default_value": "{\"conversation_history\": [], \"user_profile\": {}}"
}
}
```
#### 3.5 Transform节点（数据转换）
- **作用**: 合并、转换、映射数据
- **常用模式**:
- `merge`: 合并多个输入
- `map`: 数据映射
- `filter`: 数据过滤
**示例配置**:
```json
{
"id": "transform-merge",
"type": "transform",
"position": {"x": 500, "y": 200},
"data": {
"label": "合并上下文",
"mode": "merge",
"mapping": {
"user_input": "{{input.query}}",
"memory": "{{cache-query.output}}",
"timestamp": "{{timestamp}}"
}
}
}
```
#### 3.6 Switch节点（条件分支）
- **作用**: 根据条件路由到不同分支
- **配置要点**:
- 条件表达式要清晰
- 覆盖所有可能的情况
- 提供默认分支
**示例配置**:
```json
{
"id": "switch-intent",
"type": "switch",
"position": {"x": 600, "y": 200},
"data": {
"label": "意图分支",
"conditions": [
{
"condition": "{{intent-recognize.output.intent}} == 'question'",
"target": "llm-answer"
},
{
"condition": "{{intent-recognize.output.intent}} == 'request'",
"target": "tool-call"
},
{
"condition": "default",
"target": "llm-general"
}
]
}
}
```
#### 3.7 工具调用节点（LLM + 工具）
- **作用**: 让LLM智能调用工具完成任务
- **配置要点**:
- 启用工具调用: `enable_tools: true`
- 选择工具: `selected_tools: ["tool1", "tool2"]`
- Prompt中说明如何使用工具
**示例配置**:
```json
{
"id": "llm-with-tools",
"type": "llm",
"position": {"x": 800, "y": 200},
"data": {
"label": "工具调用",
"provider": "deepseek",
"model": "deepseek-chat",
"temperature": 0.7,
"max_tokens": 2000,
"enable_tools": true,
"selected_tools": ["http_request", "file_read", "adb_log"],
"prompt": "根据用户需求，选择合适的工具执行任务。可以使用以下工具：\n- http_request: 发送HTTP请求\n- file_read: 读取文件\n- adb_log: 获取Android日志\n\n用户需求：{{input.query}}\n\n请分析需求，调用合适的工具，然后分析结果并回复用户。"
}
}
```
#### 3.8 结束节点
- **作用**: 输出最终结果
- **配置**: 通常不需要特殊配置
```json
{
"id": "end",
"type": "end",
"position": {"x": 1000, "y": 200},
"data": {
"label": "结束"
}
}
```
---
### 阶段4: 节点连接和边配置
#### 4.1 边的配置
- **source**: 源节点ID
- **target**: 目标节点ID
- **sourceHandle**: 源节点输出端口（通常为"right"）
- **targetHandle**: 目标节点输入端口（通常为"left"）
**示例**:
```json
{
"id": "e1",
"source": "start",
"target": "intent-recognize",
"sourceHandle": "right",
"targetHandle": "left"
}
```
#### 4.2 数据传递规则
- **变量引用**: 使用 `{{节点ID.输出字段}}` 引用上游节点数据
- **特殊变量**:
- `{{input}}`: 开始节点的输入
- `{{timestamp}}`: 当前时间戳
- `{{user_id}}`: 用户ID（如果可用）
**示例**:
```
用户输入：{{input.query}}
记忆数据：{{cache-query.output.memory}}
意图分析：{{intent-recognize.output.intent}}
```
---
### 阶段5: Agent创建脚本
#### 5.1 脚本结构
```python
#!/usr/bin/env python3
"""
生成[Agent名称]Agent
"""
import sys
import os
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from app.core.database import SessionLocal
from app.models.agent import Agent
from app.models.workflow import Workflow
import uuid
from datetime import datetime
def generate_my_agent():
"""生成[Agent名称]Agent"""
db = SessionLocal()
try:
# 1. 检查是否已存在
existing = db.query(Agent).filter(Agent.name == "Agent名称").first()
if existing:
print(f"Agent 'Agent名称' 已存在，ID: {existing.id}")
return existing.id
# 2. 定义节点
nodes = [
# 开始节点
{
"id": "start",
"type": "start",
"position": {"x": 100, "y": 200},
"data": {"label": "开始"}
},
# ... 其他节点
# 结束节点
{
"id": "end",
"type": "end",
"position": {"x": 1000, "y": 200},
"data": {"label": "结束"}
}
]
# 3. 定义边
edges = [
{
"id": "e1",
"source": "start",
"target": "node1",
"sourceHandle": "right",
"targetHandle": "left"
},
# ... 其他边
]
# 4. 创建工作流
workflow_id = str(uuid.uuid4())
workflow = Workflow(
id=workflow_id,
name="工作流名称",
description="工作流描述",
nodes=nodes,
edges=edges,
created_at=datetime.now(),
updated_at=datetime.now()
)
db.add(workflow)
db.commit()
db.refresh(workflow)
# 5. 创建Agent
agent_id = str(uuid.uuid4())
agent = Agent(
id=agent_id,
name="Agent名称",
description="Agent描述",
workflow_config={
"workflow_id": workflow_id,
"nodes": nodes,
"edges": edges
},
created_at=datetime.now(),
updated_at=datetime.now()
)
db.add(agent)
db.commit()
db.refresh(agent)
print(f"✅ Agent创建成功！")
print(f" Agent ID: {agent_id}")
print(f" Agent名称: {agent.name}")
print(f" 工作流ID: {workflow_id}")
return agent_id
except Exception as e:
db.rollback()
print(f"❌ 创建Agent失败: {e}")
import traceback
traceback.print_exc()
return None
finally:
db.close()
if __name__ == "__main__":
generate_my_agent()
```
#### 5.2 脚本最佳实践
- ✅ **幂等性**: 检查Agent是否已存在，避免重复创建
- ✅ **错误处理**: 完善的异常处理和回滚机制
- ✅ **日志输出**: 清晰的日志信息
- ✅ **代码注释**: 详细的注释说明
---
### 阶段6: 测试和优化
#### 6.1 单元测试
- **测试各个节点**: 确保每个节点正常工作
- **测试数据流**: 验证数据在节点间正确传递
- **测试边界情况**: 测试异常输入、空值等
#### 6.2 集成测试
```bash
# 使用测试工具
python3 test_workflow_tool.py -a "Agent名称" -i '{"query": "测试输入"}'
```
#### 6.3 性能优化
- **减少LLM调用**: 合理使用缓存，避免重复调用
- **优化Prompt**: 精简Prompt，提高响应速度
- **并行处理**: 对于独立的任务，考虑并行处理
- **超时控制**: 设置合理的超时时间
#### 6.4 用户体验优化
- **响应时间**: 确保响应时间在可接受范围内
- **错误提示**: 提供友好的错误信息
- **结果格式**: 确保输出格式清晰易读
---
## 🎨 常见Agent模式模板
### 模板1: 简单问答Agent
```
开始 → LLM处理 → 结束
```
**适用场景**: 简单的问答、文本生成
### 模板2: 工具调用Agent
```
开始 → 意图识别 → JSON解析 → LLM工具调用 → 结果分析 → 结束
```
**适用场景**: 需要调用外部工具或API
### 模板3: 多轮对话Agent
```
开始 → 查询记忆 → 合并上下文 → LLM处理 → 更新记忆 → 结束
```
**适用场景**: 需要上下文记忆的对话
### 模板4: 条件分支Agent
```
开始 → 意图识别 → Switch → [分支1/分支2/分支3] → 合并 → 结束
```
**适用场景**: 需要根据条件执行不同操作
### 模板5: 复杂组合Agent
```
开始 → 意图识别 → Switch →
[工具调用分支] → 结果分析 →
[记忆查询分支] → 上下文合并 →
[数据处理分支] → 格式化 →
合并 → 结束
```
**适用场景**: 复杂的多步骤任务
---
## ⚠️ 常见问题和解决方案
### 问题1: 节点数据传递失败
**症状**: 下游节点无法获取上游节点数据
**原因**: 变量引用错误、节点ID不匹配
**解决**:
- 检查变量引用格式: `{{节点ID.字段}}`
- 确认节点ID正确
- 检查节点输出格式
### 问题2: LLM输出格式不正确
**症状**: LLM返回的JSON格式错误
**原因**: Prompt不够明确、没有示例
**解决**:
- 在Prompt中明确要求JSON格式
- 提供JSON示例
- 使用JSON节点验证和修复
### 问题3: 工具调用失败
**症状**: 工具执行失败或返回错误
**原因**: 参数错误、工具未注册、权限问题
**解决**:
- 检查工具参数是否正确
- 确认工具已注册
- 检查工具执行日志
### 问题4: 工作流执行超时
**症状**: 工作流执行时间过长
**原因**: LLM调用过多、工具执行慢、没有超时控制
**解决**:
- 优化工作流，减少不必要的节点
- 设置合理的超时时间
- 使用缓存避免重复计算
### 问题5: 记忆管理问题
**症状**: 对话历史丢失、记忆不准确
**原因**: 缓存key不正确、更新逻辑错误
**解决**:
- 使用唯一的缓存key
- 正确更新缓存数据
- 检查缓存节点的配置
---
## 📊 质量检查清单
### 功能完整性
- [ ] Agent能够完成预期任务
- [ ] 所有功能分支都经过测试
- [ ] 错误情况得到妥善处理
- [ ] 输出格式符合要求
### 性能指标
- [ ] 响应时间在可接受范围内
- [ ] 资源使用合理
- [ ] 没有内存泄漏
- [ ] 超时控制有效
### 代码质量
- [ ] 代码结构清晰
- [ ] 注释充分
- [ ] 错误处理完善
- [ ] 符合编码规范
### 用户体验
- [ ] 交互流程顺畅
- [ ] 错误提示友好
- [ ] 输出结果清晰
- [ ] 响应及时
### 安全性
- [ ] 输入验证充分
- [ ] 没有安全漏洞
- [ ] 权限控制合理
- [ ] 敏感信息保护
---
## 🚀 进阶技巧
### 1. Prompt工程
- **Few-shot Learning**: 在Prompt中提供示例
- **Chain of Thought**: 引导LLM逐步思考
- **角色设定**: 为LLM设定明确的角色
- **输出约束**: 明确指定输出格式和约束
### 2. 工作流优化
- **节点复用**: 将通用逻辑提取为可复用节点
- **并行处理**: 对于独立任务，考虑并行执行
- **缓存策略**: 合理使用缓存减少重复计算
- **错误恢复**: 设计错误恢复机制
### 3. 工具设计
- **工具组合**: 将复杂工具拆分为简单工具
- **工具链**: 设计工具调用链完成复杂任务
- **工具验证**: 在工具中验证输入参数
- **工具文档**: 为工具提供清晰的文档
### 4. 监控和调试
- **执行日志**: 记录详细的执行日志
- **性能监控**: 监控Agent执行性能
- **错误追踪**: 追踪和记录错误信息
- **用户反馈**: 收集用户反馈持续改进
---
## 📚 参考资源
### 内置工具列表
- `http_request`: HTTP请求工具
- `file_read`: 文件读取工具
- `file_write`: 文件写入工具
- `text_analyze`: 文本分析工具
- `datetime`: 日期时间工具
- `math_calculate`: 数学计算工具
- `system_info`: 系统信息工具
- `json_process`: JSON处理工具
- `database_query`: 数据库查询工具
- `adb_log`: ADB日志工具
### 示例Agent
- **智能聊天助手**: `backend/scripts/generate_chat_agent.py`
- **知识库问答助手**: `backend/scripts/generate_knowledge_base_qa_agent.py`
- **Android日志获取助手**: `backend/scripts/generate_android_log_agent.py`
### 相关文档
- 工具调用实现方案
- 节点配置页面增强方案
- ADB工具和Android日志Agent搭建总结
---
## 🎯 总结
搭建一个成功的Agent需要：
1. **明确需求**: 清楚定义Agent的目标和功能
2. **合理设计**: 设计清晰的工作流架构
3. **工具准备**: 准备必要的工具支持
4. **节点配置**: 正确配置各个节点
5. **测试优化**: 充分测试和持续优化
6. **文档完善**: 提供清晰的使用文档
遵循本指南的方法和最佳实践，可以高效地创建各种类型的Agent，满足不同的业务需求。
---
**最后更新**: 2026-01-23
**文档版本**: v1.0
**状态**: 持续更新中 📝

283
docs/agent-guides/Agent使用说明.md Normal file
View File

@@ -0,0 +1,283 @@
# Agent使用说明
## 📋 概述
Agent部署后，状态变为"已发布"（published）或"运行中"（running），就可以被使用了。本文档介绍如何使用已发布的Agent。
## 🎯 使用方式
### 方式1：通过前端界面使用（推荐）
#### 步骤1：进入Agent设计器
1. 在Agent管理页面，找到已发布的Agent
2. 点击 **"使用"** 按钮（只有已发布或运行中的Agent才显示此按钮）
3. 系统会跳转到Agent设计器页面
#### 步骤2：在聊天界面使用
- Agent设计器页面右侧有一个聊天预览面板（AgentChatPreview）
- 在输入框中输入您的问题或需求
- 点击发送按钮或按 Enter 键发送
- Agent会执行工作流并返回结果
#### 功能特性：
- ✅ 实时对话：支持多轮对话
- ✅ 执行动画：左侧工作流会显示节点执行动画
- ✅ 自动滚动：新消息自动滚动到底部
- ✅ 清空对话：可以随时清空对话历史
### 方式2：通过API调用
#### API端点
```
POST /api/v1/executions
```
#### 请求格式
```json
{
"agent_id": "agent-id",
"input_data": {
"query": "用户输入的问题",
"USER_INPUT": "用户输入的问题"
}
}
```
#### 响应格式
```json
{
"id": "execution-id",
"agent_id": "agent-id",
"status": "pending",
"input_data": {...},
"created_at": "2024-01-19T12:00:00"
}
```
#### 获取执行结果
```
GET /api/v1/executions/{execution_id}
```
#### 轮询执行状态
```
GET /api/v1/executions/{execution_id}/status
```
### 方式3：使用测试工具
使用我们提供的测试工具 `test_workflow_tool.py`：
```bash
# 通过Agent名称和用户输入测试
python3 test_workflow_tool.py -a "Agent名称" -i "用户输入内容"
# 交互式输入
python3 test_workflow_tool.py
```
## 📝 使用示例
### 示例1：前端界面使用
1. **打开Agent管理页面**
- 访问 `/agents` 路径
- 找到状态为"已发布"的Agent
2. **点击"使用"按钮**
- 系统跳转到Agent设计器页面
- 右侧显示聊天界面
3. **发送消息**
- 在输入框输入："生成一个导出androidlog的脚本"
- 点击发送或按Enter键
4. **查看结果**
- 左侧工作流显示执行动画
- 右侧聊天界面显示Agent的回复
### 示例2：API调用
```bash
# 1. 登录获取token
curl -X POST http://localhost:8037/api/v1/auth/login \
-d "username=admin&password=123456"
# 2. 执行Agent
curl -X POST http://localhost:8037/api/v1/executions \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent-id",
"input_data": {
"query": "生成一个导出androidlog的脚本",
"USER_INPUT": "生成一个导出androidlog的脚本"
}
}'
# 3. 获取执行结果（使用返回的execution_id）
curl -X GET http://localhost:8037/api/v1/executions/{execution_id} \
-H "Authorization: Bearer <your_token>"
```
### 示例3：Python脚本调用
```python
import requests
# 登录
response = requests.post(
"http://localhost:8037/api/v1/auth/login",
data={"username": "admin", "password": "123456"}
)
token = response.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}
# 执行Agent
response = requests.post(
"http://localhost:8037/api/v1/executions",
headers=headers,
json={
"agent_id": "agent-id",
"input_data": {
"query": "用户问题",
"USER_INPUT": "用户问题"
}
}
)
execution_id = response.json()["id"]
# 轮询获取结果
import time
while True:
response = requests.get(
f"http://localhost:8037/api/v1/executions/{execution_id}",
headers=headers
)
execution = response.json()
if execution["status"] == "completed":
print("结果:", execution["output_data"])
break
elif execution["status"] == "failed":
print("执行失败:", execution.get("error_message"))
break
time.sleep(2)
```
## 🔑 权限说明
### 已发布Agent的使用权限
1. **所有者**：可以随时使用自己的Agent
2. **其他用户**：只有已发布（published）或运行中（running）状态的Agent才能被其他用户使用
3. **草稿状态**：只有所有者可以测试，其他用户无法使用
### API权限检查
从代码中可以看到：
```python
# 只有已发布的Agent可以执行，或者所有者可以测试
if agent.status not in ["published", "running"] and agent.user_id != current_user.id:
raise HTTPException(status_code=403, detail="Agent未发布或无权执行")
```
## 🎨 前端界面说明
### Agent设计器页面布局
```
┌─────────────────────────────────────────────────┐
│ Agent编排设计器 [测试运行] [发布] [返回] │
├──────────────────────┬──────────────────────────┤
│ │ │
│ 工作流编辑器 │ Agent聊天预览 │
│ (左侧) │ (右侧) │
│ │ │
│ - 节点可视化 │ - 对话界面 │
│ - 执行动画 │ - 消息历史 │
│ - 节点配置 │ - 输入框 │
│ │ - 实时响应 │
│ │ │
└──────────────────────┴──────────────────────────┘
```
### 聊天界面功能
1. **消息显示**
- 用户消息：右侧显示，蓝色背景
- Agent回复：左侧显示，白色背景
- 时间戳：每条消息显示发送时间
2. **输入功能**
- 文本输入：支持多行文本
- Enter发送：按Enter键发送消息
- Shift+Enter：换行
- 发送按钮：点击发送
3. **其他功能**
- 清空对话：清除所有消息历史
- 加载状态：显示"正在思考..."
- 执行动画：左侧工作流实时显示节点执行状态
## 🔧 常见问题
### Q1: 为什么看不到"使用"按钮？
**A:** "使用"按钮只对状态为"已发布"（published）或"运行中"（running）的Agent显示。如果Agent是"草稿"（draft）状态，需要先点击"部署"按钮发布。
### Q2: 如何知道Agent是否可用？
**A:** 查看Agent列表中的"状态"列：
- ✅ **已发布**（published）：可以使用
- ✅ **运行中**（running）：可以使用
- ⚠️ **草稿**（draft）：只有所有者可以测试
- ⚠️ **已停止**（stopped）：需要重新部署
### Q3: Agent执行失败怎么办？
**A:**
1. 检查Agent的工作流配置是否正确
2. 查看执行记录中的错误信息
3. 检查LLM节点的API密钥是否配置
4. 查看后端日志获取详细错误信息
### Q4: 如何查看Agent的执行历史？
**A:**
1. 访问"执行管理"页面（`/executions`）
2. 筛选Agent相关的执行记录
3. 点击执行记录查看详细信息
### Q5: 可以同时使用多个Agent吗？
**A:** 可以。每个Agent都是独立的，可以同时打开多个Agent设计器页面使用不同的Agent。
## 📚 相关文档
- [Agent管理功能使用说明](./Agent管理功能使用说明.md)
- [工作流调用测试总结](./工作流调用测试总结.txt)
- [API文档](./backend/API_DOCUMENTATION.md)
## 🎯 快速开始
1. **确保Agent已发布**
- 在Agent列表中，找到要使用的Agent
- 确认状态为"已发布"或"运行中"
2. **点击"使用"按钮**
- 跳转到Agent设计器页面
3. **开始对话**
- 在右侧聊天界面输入问题
- 点击发送或按Enter键
- 等待Agent执行并返回结果
4. **查看结果**
- 在聊天界面查看Agent的回复
- 在左侧工作流查看执行过程
---
**最后更新**：2026-01-19
**适用版本**：v1.0+

268
docs/agent-guides/Agent管理功能使用说明.md Normal file
View File

@@ -0,0 +1,268 @@
# Agent管理功能使用说明
## 📍 入口位置
### 方式一：通过URL直接访问
在浏览器地址栏输入：
```
http://localhost:8038/agents
```
或
```
http://101.43.95.130:8038/agents
```
### 方式二：通过代码导航
在应用中的任何位置，可以通过以下方式导航到Agent管理页面：
```typescript
// 使用 Vue Router
router.push('/agents')
// 或使用路由名称
router.push({ name: 'agents' })
```
## 🎯 功能概览
Agent管理页面提供了完整的Agent生命周期管理功能：
### 1. Agent列表展示
- 显示所有Agent的基本信息（名称、描述、状态、版本、创建时间）
- 支持分页显示
- 支持搜索和筛选
### 2. 搜索和筛选
- **搜索功能**：按Agent名称或描述搜索
- **状态筛选**：按状态筛选（草稿、已发布、运行中、已停止）
### 3. Agent操作
- **创建Agent**：创建新的Agent
- **编辑Agent**：修改Agent的基本信息和配置
- **设计Agent**：打开工作流设计器，设计Agent的工作流
- **部署Agent**：将Agent状态改为"已发布"
- **停止Agent**：停止运行中的Agent
- **删除Agent**：删除Agent（需确认）
## 📋 详细使用步骤
### 创建Agent
1. 点击页面右上角的 **"创建Agent"** 按钮
2. 在弹出的对话框中填写：
- **名称**：Agent的名称（必填）
- **描述**：Agent的描述（可选）
3. 点击 **"确定"** 创建Agent
4. 创建成功后，Agent会出现在列表中，状态为"草稿"
### 设计Agent工作流
1. 在Agent列表中，找到要设计的Agent
2. 点击 **"设计"** 按钮
3. 系统会跳转到工作流设计器页面（`/agents/{agent_id}/design`）
4. 在设计器中：
- 拖拽节点到画布
- 连接节点
- 配置节点参数
- 保存工作流配置
### 编辑Agent
1. 在Agent列表中，找到要编辑的Agent
2. 点击 **"编辑"** 按钮
3. 在弹出的对话框中修改：
- Agent名称
- Agent描述
- 工作流配置（JSON格式）
4. 点击 **"确定"** 保存修改
### 部署Agent
1. 在Agent列表中，找到状态为"草稿"或"已停止"的Agent
2. 点击 **"部署"** 按钮
3. 确认部署操作
4. Agent状态会变为"已发布"
### 停止Agent
1. 在Agent列表中，找到状态为"已发布"或"运行中"的Agent
2. 点击 **"停止"** 按钮
3. 确认停止操作
4. Agent状态会变为"已停止"
### 删除Agent
1. 在Agent列表中，找到要删除的Agent
2. 点击 **"删除"** 按钮
3. 确认删除操作
4. Agent会被永久删除
## 🔌 API接口说明
### 后端API端点
所有API都需要JWT认证，在请求头中添加：
```
Authorization: Bearer <your_token>
```
#### 1. 获取Agent列表
```
GET /api/v1/agents
```
**查询参数：**
- `skip`: 跳过记录数（分页，默认0）
- `limit`: 每页记录数（默认100，最大100）
- `search`: 搜索关键词（按名称或描述）
- `status`: 状态筛选（draft/published/running/stopped）
**响应示例：**
```json
[
{
"id": "agent-uuid",
"name": "客服Agent",
"description": "处理客户咨询的智能Agent",
"workflow_config": {
"nodes": [...],
"edges": [...]
},
"version": 1,
"status": "published",
"user_id": "user-uuid",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
]
```
#### 2. 创建Agent
```
POST /api/v1/agents
```
**请求体：**
```json
{
"name": "Agent名称",
"description": "Agent描述",
"workflow_config": {
"nodes": [...],
"edges": [...]
}
}
```
#### 3. 获取Agent详情
```
GET /api/v1/agents/{agent_id}
```
#### 4. 更新Agent
```
PUT /api/v1/agents/{agent_id}
```
**请求体：**
```json
{
"name": "新名称",
"description": "新描述",
"workflow_config": {...},
"status": "published"
}
```
#### 5. 删除Agent
```
DELETE /api/v1/agents/{agent_id}
```
#### 6. 部署Agent
```
POST /api/v1/agents/{agent_id}/deploy
```
#### 7. 停止Agent
```
POST /api/v1/agents/{agent_id}/stop
```
## 💡 使用示例
### 示例1：创建一个简单的客服Agent
1. 点击"创建Agent"
2. 填写：
- 名称：客服Agent
- 描述：处理客户咨询
3. 点击"确定"创建
4. 点击"设计"按钮，进入设计器
5. 在设计器中：
- 添加"开始"节点
- 添加"LLM"节点，配置提示词
- 添加"输出"节点
- 连接节点
- 保存
6. 返回Agent列表，点击"部署"
### 示例2：通过API创建Agent
```bash
curl -X POST http://localhost:8037/api/v1/agents \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "API创建的Agent",
"description": "通过API创建的Agent",
"workflow_config": {
"nodes": [
{
"id": "start-1",
"type": "start",
"position": {"x": 0, "y": 0},
"data": {"label": "开始"}
},
{
"id": "end-1",
"type": "end",
"position": {"x": 200, "y": 0},
"data": {"label": "结束"}
}
],
"edges": []
}
}'
```
## 🔍 前端代码位置
- **页面组件**：`frontend/src/views/Agents.vue`
- **状态管理**：`frontend/src/stores/agent.ts`
- **路由配置**：`frontend/src/router/index.ts`（路径：`/agents`）
## 🔧 后端代码位置
- **API路由**：`backend/app/api/agents.py`
- **数据模型**：`backend/app/models/agent.py`
- **API前缀**：`/api/v1/agents`
## 📝 注意事项
1. **权限**：所有Agent操作都需要用户登录，且只能操作自己创建的Agent
2. **状态管理**：
- `draft`：草稿状态，可以编辑和设计
- `published`：已发布，可以执行
- `running`：运行中
- `stopped`：已停止
3. **工作流配置**：Agent的工作流配置格式与普通工作流相同，包含`nodes`和`edges`
4. **版本管理**：每次更新Agent，版本号会自动递增
## 🎨 界面截图说明
Agent管理页面包含：
- 顶部：标题和"创建Agent"按钮
- 搜索栏：搜索框和状态筛选下拉框
- 表格：显示Agent列表
- 操作列：编辑、设计、部署/停止、删除按钮

127
docs/agent-guides/使用指南.md Normal file
View File

@@ -0,0 +1,127 @@
# 低代码智能体平台 - 使用指南
## 🎉 恭喜！系统已成功运行
你现在已经登录到系统，可以开始使用所有功能了！
## 📋 功能概览
### 1. 工作流管理
从主页面可以看到：
- **工作流列表**：显示所有已创建的工作流
- **创建工作流**：点击按钮进入可视化编辑器
### 2. 创建工作流
点击"创建工作流"按钮后，你将进入工作流设计器：
#### 左侧工具箱
可以拖拽以下节点类型：
- **开始**：工作流起始节点
- **输入**：数据输入节点
- **LLM**：AI模型处理节点
- **条件**：条件判断节点
- **转换**：数据转换节点
- **输出**：数据输出节点
- **结束**：工作流结束节点
#### 中间画布
- 拖拽节点到画布
- 连接节点（点击节点的连接点并拖拽到目标节点）
- 点击节点进行配置
#### 右侧配置面板
- 配置节点名称
- 配置节点参数（如LLM节点的提示词、模型选择等）
### 3. 保存和执行工作流
- **保存**：点击工具栏的"保存"按钮
- **运行**：点击工具栏的"运行"按钮（功能开发中）
## 🚀 快速开始
### 创建一个简单的工作流
1. **点击"创建工作流"**
2. **拖拽节点**：
- 从左侧拖拽"开始"节点到画布
- 拖拽"LLM"节点到画布
- 拖拽"结束"节点到画布
3. **连接节点**：
- 点击"开始"节点的输出点，拖拽到"LLM"节点
- 点击"LLM"节点的输出点，拖拽到"结束"节点
4. **配置LLM节点**：
- 点击"LLM"节点
- 在右侧配置面板输入提示词，例如：`处理输入: {input}`
- 选择模型（GPT-3.5 或 GPT-4）
5. **保存工作流**：
- 点击工具栏的"保存"按钮
- 输入工作流名称和描述
## 📝 当前功能状态
### ✅ 已完成功能
- [x] 用户注册和登录
- [x] 工作流CRUD（创建、读取、更新、删除）
- [x] 可视化编辑器（拖拽节点、连线）
- [x] 节点配置面板
- [x] 工作流执行引擎（基础版本）
- [x] 执行记录管理
### 🚧 开发中功能
- [ ] LLM节点真实调用（OpenAI集成）
- [ ] 工作流执行实时状态推送
- [ ] 执行结果可视化
## 🔧 技术说明
### API文档
访问：http://101.43.95.130:8037/docs
可以查看所有可用的API接口。
### 数据库
- 类型：MySQL（腾讯云）
- 数据库名：agent_db
### 服务端口
- 前端：8038
- 后端：8037
- Redis：6379
## 💡 提示
1. **工作流设计**：
- 每个工作流必须有一个"开始"节点和一个"结束"节点
- 节点之间通过连线连接，数据会沿着连线传递
2. **节点配置**：
- LLM节点可以使用 `{input}` 引用输入数据
- 条件节点需要配置条件表达式
3. **保存工作流**：
- 工作流会自动保存到数据库
- 可以随时编辑和更新
## 🐛 遇到问题？
1. **查看浏览器控制台**（F12）：查看错误信息
2. **查看后端日志**：
```bash
docker-compose -f docker-compose.dev.yml logs backend
```
3. **检查服务状态**：
```bash
docker-compose -f docker-compose.dev.yml ps
```
---
**祝你使用愉快！** 🎉

567
docs/agent-guides/使用文档.md Normal file
View File

@@ -0,0 +1,567 @@
# Agent 工具使用文档
## 概述
所有 Agent 默认拥有 **34 个内置工具**（`tools: []` = 全部可用）。工具涵盖文件操作、网络访问、代码执行、项目管理、部署、自主能力扩展等能力，Agent 可在 ReAct 循环中自主选择和调用。
---
## 工具清单（34个）
### 文件与数据
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 1 | `file_read` | `file_path` | 读取文本/PDF/docx/xlsx/图片OCR |
| 2 | `file_write` | `file_path`, `content`, `mode` | 写入文本文件（覆盖/追加） |
| 3 | `json_process` | `json_data`, `operation`, `key` | JSON 结构化数据处理 |
| 4 | `excel_process` | `file_path`, `action`, `sheet_name`, `data_json`, `chart_config_json` | Excel 读写 + 图表生成 |
### 网络
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 5 | `http_request` | `url`, `method`, `headers`, `body` | HTTP 请求（GET/POST/PUT/DELETE） |
| 6 | `url_parse` | `url` | URL 解析 |
| 7 | `web_search` | `query`, `max_results` | DuckDuckGo 网页搜索 |
### 代码与文本
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 8 | `code_execute` | `code`, `language`, `timeout` | Python/JS 沙箱执行 |
| 9 | `text_analyze` | `text`, `operation` | 文本分析 |
| 10 | `regex_test` | `pattern`, `text` | 正则表达式测试 |
| 11 | `code_tool_create` | `name`, `description`, `code`, `language`, `parameter_schema`, `test_input` | 持久化验证过的代码为可复用工具 |
### 项目管理
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 11 | `git_operation` | `operation`, `file_path`, `revision` | Git 只读操作（log/diff/blame/status） |
| 12 | `project_scaffold` | `template`, `project_name`, `target_dir` | 项目模板生成（fastapi/vue/react等） |
| 13 | `task_plan` | `action`, `plan_id`, `title`, `steps_json`, `step_index`, `status` | 任务分解与进度跟踪 |
| 14 | `deploy_push` | `source_path`, `target`, `method`, `exclude` | 文件部署（本地复制/rsync） |
### 文档与报告
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 15 | `pdf_generate` | `markdown`, `output_path`, `title` | Markdown→PDF/HTML 报告生成 |
### 计算与系统
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 16 | `math_calculate` | `expression` | 数学计算 |
| 17 | `system_info` | | 系统环境信息 |
| 18 | `datetime` | `operation`, `datetime_str`, `timezone` | 日期时间计算 |
| 19 | `crypto_util` | `operation`, `text`, `key` | 加密/解密/哈希 |
| 20 | `random_generate` | `type`, `count`, `min`, `max` | 随机数据生成 |
### 自动化
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 21 | `schedule_create` | `agent_id`, `name`, `cron_expression`, `input_message` | 创建定时任务 |
| 22 | `schedule_list` | `agent_id` | 查看定时任务 |
| 23 | `schedule_delete` | `schedule_id` | 删除定时任务 |
### 通信与协作
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 25 | `send_email` | `to`, `subject`, `body` | 发送邮件 |
| 26 | `agent_call` | `agent_name`, `query`, `max_iterations` | 调用其他 Agent 委派任务 |
| 27 | `agent_create` | `name`, `system_prompt`, `description` | 动态创建专业子 Agent |
| 28 | `tool_register` | `name`, `description`, `method`, `url` | 动态注册 HTTP 工具 |
| 29 | `capability_check` | `task_description`, `required_domains` | 能力自检，分析任务与现有能力的匹配度 |
| 30 | `extension_log` | `action`, `name`, `extension_type`, `reason` | 记录和查询自主扩展历史 |
### DevOps
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 31 | `database_query` | `query`, `params` | 数据库查询 |
| 32 | `docker_manage` | `operation`, `resource`, `options` | Docker 容器管理（只读） |
| 33 | `browser_use` | `url`, `action`, `selector`, `script` | 无头浏览器操控（截图/提取/填表） |
| 34 | `adb_log` | `device`, `lines`, `tag` | Android ADB 日志 |
---
## 核心工具详解
### 1. code_execute — 代码执行
```
code_execute(code="print(sum(range(1,101)))", language="python")
→ {"stdout": "5050\n", "stderr": "", "returncode": 0}
```
**场景：**
- 写脚本验证逻辑 → 看输出 → 修正 → 完成闭环
- 数据处理：pandas 读取 → 清洗 → 统计
- 批量文件重命名、格式转换
**安全限制：** 超时 30s，Python/JS 沙箱，任意代码可执行
---
### 2. git_operation — Git 操作
```
git_operation(operation="log", file_path="src/main.py")
→ 最近 50 条该文件的提交历史
git_operation(operation="diff", file_path="src/utils.py")
→ 当前未暂存的差异
git_operation(operation="blame", file_path="src/app.py")
→ 每行代码的作者和提交时间
```
**支持的 operation：** `log`, `diff`, `diff_staged`, `status`, `branch`, `blame`, `show`, `tag`, `remote`, `rev_parse`
**场景：**
- 理解项目演进历史
- 定位 bug 引入的提交
- 审查代码变更范围
---
### 3. web_search — 网页搜索
```
web_search(query="FastAPI middleware CORS setup 2025", max_results=5)
→ {"results": [
{"index": 1, "title": "...", "url": "https://...", "snippet": "..."},
...
], "count": 5}
```
**场景：**
- 查最新技术文档、API 用法
- 搜索错误信息找到解决方案
- 了解行业最佳实践
---
### 4. task_plan — 任务规划
```
# 创建计划
task_plan(
action="create",
title="开发用户认证系统",
steps_json='["设计数据库模型","实现注册API","实现登录API","添加JWT中间件","编写测试","部署配置"]'
)
→ {"plan": {"id": "plan_20260503_120000", "steps": [...], ...}}
# 标记步骤完成
task_plan(
action="update_step",
plan_id="plan_20260503_120000",
step_index=0,
status="done"
)
# 查看进度
task_plan(action="view", plan_id="plan_20260503_120000")
→ 完整计划及每个步骤的状态
# 列出所有计划
task_plan(action="list")
→ 所有活跃计划的摘要
```
**步骤状态：** `pending` → `in_progress` → `done` / `blocked`
**场景：**
- 复杂多步骤任务："帮我搭建一个完整的博客系统"
- Agent 自主拆解 → 逐步执行 → 汇报每步结果
- 长期项目跟踪
---
### 5. project_scaffold — 项目脚手架
```
project_scaffold(template="fastapi", project_name="my-api")
→ 在工作区创建标准 FastAPI 项目目录结构
project_scaffold(template="vue", project_name="my-dashboard")
→ Vue 3 + Vite 前端项目
```
**支持的模板：**
| 模板 | 说明 |
|------|------|
| `fastapi` | FastAPI 后端 + Dockerfile |
| `vue` | Vue 3 + Vite 前端 |
| `react` | React 18 + Vite |
| `python_cli` | Python CLI 工具 |
| `shell` | Shell 脚本项目 |
---
### 6. pdf_generate — 报告生成
```
pdf_generate(
markdown="# 项目周报\n\n## 进展\n- 完成用户模块\n- 修复3个bug\n\n## 下周计划\n- 集成支付",
title="项目周报 2026-05-03"
)
→ {"file": "/path/to/report_20260503_120000.pdf", "format": "pdf"}
```
**依赖：** `pip install weasyprint` 生成 PDF；否则降级为 HTML
---
### 7. excel_process — 高级 Excel
```
# 读取
excel_process(file_path="data.xlsx", action="read")
→ 返回所有工作表的数据
# 写入
excel_process(
file_path="output.xlsx",
action="write",
data_json='{"Sheet1": [["姓名","分数"],["张三",95],["李四",87]]}'
)
# 添加图表
excel_process(
file_path="output.xlsx",
action="chart",
chart_config_json='{"type":"bar","title":"成绩分布","data_min_col":2,"data_min_row":1,"data_max_col":2,"data_max_row":3}'
)
```
**支持的图表：** `bar`（柱状图）、`line`（折线图）、`pie`（饼图）
---
### 8. browser_use — 浏览器操控
```
# 截图
browser_use(url="https://example.com", action="screenshot")
→ {"screenshot": "/tmp/screenshot_20260503_120000.png"}
# 提取文本
browser_use(url="https://docs.example.com", action="content")
→ {"text": "...页面全部可读文本...", "text_length": 5432}
# 执行 JS
browser_use(url="https://example.com", action="evaluate", script="document.title")
→ {"evaluate_result": "Example Domain"}
```
**依赖：** `pip install playwright && playwright install chromium`
---
### 9. docker_manage — Docker 管理
```
docker_manage(operation="ps")
→ 正在运行的容器列表
docker_manage(operation="logs", resource="my-container")
→ 容器日志
docker_manage(operation="compose", resource="ps")
→ docker compose 服务状态
```
**只读操作：** `ps`, `images`, `logs`, `stats`, `inspect`, `version`, `info`, `compose ps/logs/config/top`
---
### 10. deploy_push — 部署推送
```
# 本地复制（自动排除 .git/node_modules 等）
deploy_push(source_path="/app/dist", target="/var/www/html", method="copy")
# rsync 到远程服务器
deploy_push(
source_path="/app/dist",
target="user@server.com:/var/www/html",
method="rsync",
exclude=".git,node_modules,.venv"
)
```
---
### 11. agent_call — Agent 间协作
```
agent_call(agent_name="家庭医生助手", query="用户头痛3天，伴随失眠，该注意什么？")
→ {
"agent": "家庭医生助手",
"status": "success",
"iterations": 3,
"tool_calls": 1,
"reply": "根据您描述的症状..."
}
```
详见下一节。
---
### 12. agent_create — 动态创建子 Agent
```
agent_create(
name="SQL优化专家",
system_prompt="你是MySQL性能优化专家，擅长分析慢查询日志...",
description="专门分析MySQL慢查询并提供优化方案"
)
→ {"status": "created", "agent": {"id": "uuid", "name": "SQL优化专家", ...}}
```
**场景：**
- Agent 发现任务需要专业知识但当前没有对应子 Agent → 创建一个 → 委派
- 新 Agent 写入 DB，拥有全部 31 工具 + RAG 记忆，持久化复用
- 创建后立即通过 `agent_call` 调用来完成任务
---
### 13. tool_register — 动态注册工具
```
tool_register(
name="currency_exchange",
description="查询实时汇率",
method="GET",
url="https://api.exchangerate-api.com/v4/latest/{base_currency}"
)
→ {"status": "registered", "tool": {"id": "uuid", "name": "currency_exchange", ...}}
```
**场景：**
- Agent 发现某个外部 API 很实用 → 注册为工具 → 立即调用
- URL 中用 `{param}` 占位 → 自动解析为工具参数
- 工具写入 DB → 加载到 tool_registry → 后续所有 Agent 均可复用
---
### 14. capability_check — 能力自检
```
capability_check(task_description="分析MySQL慢查询日志并优化", required_domains="数据库,性能优化,SQL")
→ {
"available_tools_count": 34,
"available_agents": ["数据分析师", "日志分析师", "代码助手"],
"gap_analysis": {
"missing_domain_knowledge": ["MySQL性能优化"],
"missing_tools": ["database_query"],
"severity": "medium"
},
"recommendations": [
"使用 agent_create 创建「数据库专家」Agent",
"使用 web_search 搜索相关的外部 API 或开源工具"
]
}
```
**场景：**
- Agent 接到陌生/复杂任务时，先自检能力是否足够
- 基于关键词和领域规则做差距分析（不消耗 LLM token）
- 返回结构化建议：创建子Agent / 注册工具 / 搜索方案
---
### 15. code_tool_create — 代码工具持久化
```
code_tool_create(
name="parse_slow_query",
description="解析MySQL慢查询日志，提取最慢的N条SQL",
code="def parse_slow_query(log_path, top_n=10):\n import re\n ...",
language="python",
parameter_schema='{"log_path": {"type": "string", "description": "日志路径"}, "top_n": {"type": "integer", "description": "返回前N条"}}',
test_input='{"log_path": "/tmp/slow.log", "top_n": 5}'
)
→ {"status": "created", "tool": {"id": "uuid", "name": "parse_slow_query"}, "sandbox_test": {"passed": true}}
```
**场景：**
- 先用 `code_execute` 编写并验证代码逻辑
- 确认无误后调用此工具持久化 → 写入 tools 表 → 加载到 tool_registry
- 后续所有 Agent 均可直接调用该工具
**安全限制：** 创建前自动在沙箱中测试（15s 超时），测试失败则拒绝注册
---
### 16. extension_log — 扩展记录
```
# 记录扩展
extension_log(action="log", extension_type="agent_created", name="SQL优化专家", reason="缺少MySQL优化知识")
→ {"status": "logged", "extension": {"id": "uuid", "type": "agent_created", "name": "SQL优化专家"}}
# 查询历史
extension_log(action="list", limit=5)
→ {"extensions": [{"type": "agent_created", "name": "SQL优化专家", ...}, ...], "count": 5}
# 评价效果
extension_log(action="evaluate", name="SQL优化专家", success_rating="success", note="成功定位3条慢SQL")
→ {"status": "evaluated", "extension": {"name": "SQL优化专家", "success_rating": "success"}}
```
**场景：**
- Agent 每次扩展能力后记录原因和结果
- 后续任务前查询历史 → 评估哪些扩展有效 → 优化决策
- 形成自主进化反馈闭环
---
## Agent 自主能力扩展流程
```
全能助手收到: "监控线上MySQL慢查询并优化"
│
├─ capability_check(task_description="分析MySQL慢查询日志并优化")
│ └─ 差距分析：缺少 MySQL优化知识、慢查询解析工具
│
├─ web_search("MySQL慢查询分析方案 percona-toolkit")
│ └─ 发现 pt-query-digest 工具
│
├─ agent_create(name="SQL优化专家", system_prompt="你是MySQL性能优化专家...")
│ └─ 新 Agent 写入 DB，拥有全部 34 工具
│
├─ agent_call("SQL优化专家", "分析这份慢查询日志并给出优化建议")
│ └─ 子 Agent 独立 ReAct 循环执行
│
├─ extension_log(action="log", extension_type="agent_created", name="SQL优化专家", reason="缺少MySQL优化知识")
│
├─ 发现 percona-toolkit 有 REST API
├─ tool_register(name="pt_query_digest", url="http://internal-api/analyze?log={path}")
│ └─ 工具立即可用
│
├─ extension_log(action="log", extension_type="tool_registered", name="pt_query_digest")
│
└─ 整合结果: "慢查询优化方案如下..."
└─ extension_log(action="evaluate", success_rating="success")
```
---
## Agent 间协作模式
### 路由模式（全能助手）
```
用户 → 全能助手 → 分析意图
├─ 健康问题 → agent_call("家庭医生助手")
├─ 代码问题 → agent_call("代码助手")
└─ 学习问题 → agent_call("学习助手")
```
### 串行协作
```
全能助手收到"分析服务器日志并给出健康建议"
→ agent_call("日志分析师", "分析这段错误日志")
→ agent_call("家庭医生助手", "这个错误模式是不是意味着系统压力太大，对运维人员的健康有什么建议")
→ 整合两个结果回复用户
```
### 并行协作
```
全能助手收到"对比 React 和 Vue 的优缺点"
→ 并行调用多个搜索/代码分析
→ 综合汇总
```
---
## 复杂项目示例
### 示例 1：从零搭建 Web 应用
```
用户: "帮我搭一个用户管理后台"
Agent 自主规划:
1. task_plan(action="create", title="用户管理后台", steps_json=[...])
2. project_scaffold(template="fastapi", project_name="user-admin")
3. code_execute 写模型代码 → 验证 → 修正
4. project_scaffold(template="vue", project_name="user-admin-ui")
5. web_search("Vue 3 Element Plus table CRUD example")
6. code_execute 写前端组件 → 验证
7. docker_manage(operation="compose") 检查环境
8. deploy_push(source_path="user-admin", target="/opt/app", method="copy")
9. pdf_generate(markdown="# 部署文档...") 生成交付文档
```
### 示例 2：数据分析报告
```
用户: "分析 sales.xlsx 的销售趋势并生成报告"
Agent 自主规划:
1. excel_process(action="read", file_path="sales.xlsx")
2. code_execute("用 Python 计算月度增长率/同比/环比")
3. excel_process(action="chart", chart_config_json='{"type":"line",...}')
4. web_search("2025 电商行业销售趋势对比") 补充行业背景
5. pdf_generate(markdown="# 销售分析报告\n...")
```
### 示例 3：Bug 排查
```
用户: "线上 /api/orders 接口报 500，帮我排查"
Agent 自主规划:
1. docker_manage(operation="logs", resource="api-container")
2. git_operation(operation="log", file_path="src/api/orders.py")
3. git_operation(operation="diff") 查看最近改动
4. database_query("SELECT * FROM orders WHERE created_at > '...'")
5. web_search("FastAPI order API 500 error common causes")
6. code_execute 复现 bug → 定位根因 → 输出修复方案
```
---
## 依赖安装（可选工具）
部分工具需要额外依赖才能使用。Agent 首次调用时会返回明确的安装指引。
| 工具 | 依赖 | 安装命令 |
|------|------|----------|
| `pdf_generate`（PDF模式） | weasyprint | `pip install weasyprint` |
| `browser_use` | playwright | `pip install playwright && playwright install chromium` |
| `excel_process` | openpyxl | `pip install openpyxl` |
| `docker_manage` | docker CLI | 安装 Docker Desktop |
| `deploy_push`（rsync模式） | rsync | `apt install rsync` / `brew install rsync` |
| `git_operation` | git CLI | 安装 Git |
| `code_execute`（JS模式） | node | 安装 Node.js |
---
## 扩展工具
如需添加新工具：
1. 在 `backend/app/services/builtin_tools.py` 添加工具函数 + Schema
2. 在 `backend/app/core/tools_bootstrap.py` 注册
3. 在 `frontend/src/utils/agentSkills.ts` 添加条目
4. 重启后端
工具函数签名为：
```python
async def my_tool(param1: str, param2: int = 0) -> str:
# ... 实现 ...
return json.dumps({"result": "..."}, ensure_ascii=False)
```

1385
docs/agent-guides/创建Agent经验.md Normal file
View File

File diff suppressed because it is too large Load Diff

186
docs/agent-guides/创建Agent经验总结.md Normal file
View File

@@ -0,0 +1,186 @@
# 创建Agent经验总结（实战版）
> 基于本仓库实际落地的 **Android应用开发助手**（已发布可用）沉淀：从“想法→工作流→落库→发布→验证→避坑”一套流程。
## 1. 目标与验收标准
- **目标**：在 Agent 管理页面出现一个“可运行/可使用”的 Agent，并且能通过 `/api/v1/executions` 正常触发执行并拿到结果。
- **关键验收**：
- **状态**：Agent 为 `published` 或 `running`（否则普通用户无法执行）
- **工作流**：`workflow_config` 必须包含合法的 `nodes` / `edges`，能从 `start` 走到 `end`
- **数据链路**：LLM prompt 能正确拿到用户输入（一般是 `{{query}}` / `{{user_query}}`）
## 2. 两种创建方式：UI vs 脚本
### 2.1 UI 创建（适合调试）
- 优点：所见即所得、方便调整 prompt/连线/节点参数
- 缺点：重复劳动多，不利于批量/版本化
### 2.2 脚本创建（推荐用于“生成一批可运行Agent/一键复现”）
- 典型做法：写一个 `backend/scripts/generate_xxx_agent.py`，直接用 SQLAlchemy 创建或更新 Agent。
- 本仓库示例：
- `backend/scripts/generate_android_agent.py`（Android应用开发助手）
- `backend/scripts/generate_content_agent.py`（内容生成助手）
## 3. Agent 能不能“运行”，最关键的规则
### 3.1 Agent 状态与执行权限
后端创建执行时会做状态校验：**非 owner 执行必须是 `published/running`**。
对应代码（要点：状态不对会 403）：
```103:104:backend/app/api/executions.py
if agent.status not in ["published", "running"] and agent.user_id != current_user.id:
raise HTTPException(status_code=403, detail="Agent未发布或无权执行")
```
**经验**：
- 如果你希望“创建出来立刻可用”，脚本里就直接写 `status="published"`。
- 如果你希望“先草稿”，脚本里写 `draft`，但要用 owner 测试或再部署发布。
### 3.2 workflow_config 的最低要求
- 必须包含：
- `nodes`: 节点数组
- `edges`: 连线数组
- 且能通过校验（创建接口会校验）：
- 参考：`backend/app/api/agents.py` 中 `create_agent` 会调用 `validate_workflow(...)`
**经验**：
- 最小可运行工作流：`start -> llm -> end`
- 复杂工作流建议：`start -> 分析(llm) -> 分流(condition) -> 子分支(llm/transform) -> 汇总(transform) -> 输出优化(llm) -> end`
## 4. 数据流转与 Prompt 设计（决定“是否答非所问”）
### 4.1 输入字段命名建议
本平台执行 Agent 时，常见输入会放在：
- `query`
- `USER_INPUT`
Android 示例项目也是这样发起的：
- `query = 用户输入`
- `USER_INPUT = 用户输入`
**经验**：
- prompt 里优先用 `{{query}}`（平台链路更稳定）
- 如果你做了 transform 映射，可统一成 `user_query` 再用 `{{user_query}}`
### 4.2 先分析、再生成：降低跑偏
常见稳定结构：
- 第 1 个 LLM：**需求抽取/结构化**（JSON 输出）
- 后续 LLM：拿着“结构化需求 + 原始需求”做生成/诊断/优化
这样可以显著减少“答非所问”，也便于条件分支与 transform 做数据拼接。
## 5. 条件分支的关键坑：`sourceHandle`
条件节点“走哪个分支”，靠 edge 的 `sourceHandle` 来区分（例如 `true` / `false`）。
对应引擎逻辑（要点：**只保留 sourceHandle == branch 的边**）：
```1936:1961:backend/app/services/workflow_engine.py
if node.get('type') == 'condition':
branch = result.get('branch', 'false')
# 只保留：不是从条件节点出发的边，或 从条件节点出发且sourceHandle匹配分支的边
edges_to_remove = []
edges_to_keep = []
for edge in active_edges:
if edge['source'] == next_node_id:
edge_handle = edge.get('sourceHandle')
if edge_handle == branch:
edges_to_keep.append(edge)
else:
edges_to_remove.append(edge)
else:
edges_to_keep.append(edge)
active_edges = edges_to_keep
```
**经验**：
- 条件节点的出边必须带 `sourceHandle`，而且值要与引擎产出的 `branch` 完全一致（常用：`true`/`false`）
- 否则会出现：
- 分支全跑 / 分支全不跑 / 走错分支
## 6. 用脚本创建“可运行Agent”的推荐模板
核心点：
- 查用户（owner）
- 构造 `nodes/edges`
- 若同名存在则更新，否则创建
- 设置 `status="published"`
本仓库可直接复用（已验证创建成功）：
- `backend/scripts/generate_android_agent.py`
运行方式：
```bash
cd /home/renjianbo/aiagent
python3 backend/scripts/generate_android_agent.py
```
运行后会输出 Agent ID、节点数、边数，且状态为 `published`。
## 7. 如何验证 Agent “真的可运行”
### 7.1 前端验证
- 进入 **Agent管理**
- 找到 Agent（例如：Android应用开发助手）
- 状态为 **已发布/运行中**
- 点击 **使用**，输入一句话触发执行
### 7.2 API 验证（推荐可自动化）
1) 登录获取 token（form-urlencoded）
2) 发起执行：
```json
POST /api/v1/executions
{
"agent_id": "你的agent_id",
"input_data": {
"query": "帮我生成一个登录页",
"USER_INPUT": "帮我生成一个登录页"
}
}
```
3) 轮询状态：
- `GET /api/v1/executions/{execution_id}/status`
4) 获取结果：
- `GET /api/v1/executions/{execution_id}`
## 8. 常见问题与排查清单
- **Agent 列表里看到了，但点“使用”无权限/403**
- 检查 `status` 是否为 `published/running`
- 是否为 owner 在测试草稿
- **LLM 输出跑偏/答非所问**
- 是否把用户输入稳定透传到了 `{{query}}`
- 是否先做“需求结构化”再生成
- prompt 是否过泛、缺少输出格式约束
- **条件节点后续分支乱跑**
- 检查条件节点出边是否有 `sourceHandle=true/false`
- 检查引擎分支值是否与 sourceHandle 对齐
- **输出结构混乱**
- 建议末端增加 `llm-format` 做统一 Markdown 格式化
- end 节点尽量只输出最终 `output` 字段（不要拼接用户 query）
## 9. 本次落地成果（可复用资产）
- **可运行 Agent**：Android应用开发助手（脚本创建，状态 `published`）
- **生成脚本**：`backend/scripts/generate_android_agent.py`
- **Prompt 方案文档**：`androidExampleDemo/多功能android应用智能体的提示词.md`
---
最后更新：2026-01-20

231
docs/agent-guides/创建agent.md Normal file
View File

@@ -0,0 +1,231 @@
# Agent 创建指南
## 概述
本系统支持多种方式创建 Agent。**所有创建方式均默认赋予 Agent 全部 34 个内置工具能力**，除非明确限制。
## 内置工具清单（34个）
| 类别 | 工具 | 用途 |
|------|------|------|
| 文件 | `file_read` | 读文件：文本/PDF/docx/xlsx/图片OCR(作业拍照识别) |
| 文件 | `file_write` | 写文件：笔记、报告、数据导出 |
| 网络 | `http_request` | HTTP 请求：上网查资料、调 API |
| 网络 | `url_parse` | URL 解析 |
| 数据 | `json_process` | JSON 结构化数据处理 |
| 数据 | `database_query` | 数据库查询 |
| 计算 | `math_calculate` | 数学计算 |
| 文本 | `text_analyze` | 文本分析 |
| 时间 | `datetime` | 日期时间计算、倒计时 |
| 系统 | `system_info` | 系统环境信息 |
| 调度 | `schedule_create` | 创建定时任务（cron 表达式） |
| 调度 | `schedule_list` | 查看定时任务列表 |
| 调度 | `schedule_delete` | 删除定时任务 |
| 通信 | `send_email` | 发送邮件 |
| 工具 | `regex_test` | 正则表达式测试 |
| 工具 | `crypto_util` | 加密/解密工具 |
| 工具 | `random_generate` | 随机数据生成 |
| 调试 | `adb_log` | Android 设备日志（ADB） |
| 协作 | `agent_call` | 调用其他 Agent 委派任务（Agent 间协作） |
| 协作 | `agent_create` | 动态创建专业子 Agent（自我扩展能力） |
| 协作 | `tool_register` | 动态注册新 HTTP 工具（自我扩展工具） |
---
## Agent 自主能力扩展
Agent 可以通过 `agent_create` + `tool_register` 在运行时自我扩展能力和工具。
### 能力不足时的自主决策流程
```
Agent 收到复杂任务
│
├─ 评估自身能力是否足够
├─ 能力足够 → 直接处理
│
├─ 领域知识不足 → agent_create 创建专业子 Agent → agent_call 委派
│
├─ 缺少实用工具 → web_search 找到外部 API → tool_register 注册工具 → 直接调用
│
└─ 整合所有结果返回用户
```
### agent_create — 动态创建子 Agent
```
agent_create(
name="SQL优化专家",
system_prompt="你是MySQL性能优化专家，擅长分析慢查询日志并给出优化建议...",
description="专门优化MySQL慢查询"
)
→ {"status": "created", "agent": {"id": "uuid", ...}}
# 创建后立即委派
agent_call(agent_name="SQL优化专家", query="分析这份慢查询日志")
```
### tool_register — 动态注册工具
```
tool_register(
name="currency_exchange",
description="查询实时汇率",
method="GET",
url="https://api.exchangerate-api.com/v4/latest/{base_currency}"
)
→ {"status": "registered", "tool": {"id": "uuid", ...}}
# 注册后立即可用
currency_exchange(base_currency="USD")
```
---
## Agent 间协作（agent_call）
全能助手等通用 Agent 可以通过 `agent_call` 工具调用其他专业 Agent：
```
用户: "帮我分析这段日志，然后看看我该注意什么健康问题"
全能助手 自主决策:
→ agent_call(agent_name="日志分析师", query="分析这段日志...")
→ agent_call(agent_name="家庭医生助手", query="最近压力大该注意什么...")
→ 整合两个 Agent 的结果，统一回复用户
```
**执行流程：**
1. 按 Agent 名称模糊匹配查找目标 Agent
2. 解析目标 Agent 的 workflow_config（system_prompt、model、tools 等）
3. 创建 AgentRuntime 独立执行（有独立 ReAct 循环）
4. 返回结构化的执行结果（reply + 迭代次数 + 工具调用次数）
---
## 创建方式
### 方式一：前端界面创建（http://localhost:3001/agents）
#### 1.1 手动创建
1. 打开 http://localhost:3001/agents
2. 点击「创建 Agent」
3. 填写名称、描述
4. 进入工作流设计器拖拽节点（至少需要一个 LLM 或 Agent 节点）
5. **不设置工具白名单 = 全部工具可用**
6. 保存
#### 1.2 场景模板创建
1. 在 Agents 页面点击「从场景模板创建」
2. 选择模板（客服/研发/运维）
3. 填写名称
4. 系统默认启用全部工具（`enable_tools=true`，`tools` 为空）
#### 1.3 导入 JSON
1. 导出已有 Agent 的 JSON
2. 修改后导入
3. 若 JSON 中未指定 `tools` 字段 = 全部工具
---
### 方式二：后端 API 创建
```bash
# 直接创建
curl -X POST http://localhost:8037/api/v1/agents \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "My Agent",
"description": "Agent description",
"workflow_config": {
"nodes": [
{"id": "start-1", "type": "start", "position": {"x": 80, "y": 120}, "data": {}},
{"id": "llm-1", "type": "llm", "position": {"x": 320, "y": 120},
"data": {
"prompt": "你是一个有用的AI助手",
"enable_tools": true
// 不指定 tools = 全部工具
}}
],
"edges": [...]
}
}'
```
### 方式三：Python 脚本创建
```python
from app.core.database import SessionLocal
from app.models.agent import Agent
import uuid
agent = Agent(
id=str(uuid.uuid4()),
name="My Agent",
description="Description",
workflow_config={
"nodes": [
{"id": "node_1", "type": "llm", "label": "LLM",
"data": {
"system_prompt": "你是一个有用的AI助手",
"model": "deepseek-v4-flash",
"provider": "deepseek",
"temperature": 0.7,
"max_iterations": 10,
# 不指定 tools = 全部工具
}}
],
"edges": []
},
status="active",
)
db = SessionLocal()
db.add(agent)
db.commit()
db.close()
```
---
## 工具配置规则
### Agent 节点（AgentRuntime 执行）
- `tools` 字段不存在 → 全部工具
- `tools: []` → 全部工具
- `tools: ["file_read", "http_request"]` → 仅这两个工具
### LLM 节点（工作流引擎执行）
- `enable_tools: false` → 无工具
- `enable_tools: true` + `tools` 未设置/为空 → 全部工具
- `enable_tools: true` + `tools: ["file_read"]` → 仅 file_read
### 飞书长连接路由（WS Handler）
- 读取 Agent workflow_config 节点 data 中的 `tools` 字段
- 未设置 = `include_tools=[]` = 全部工具
---
## 快速检查 Agent 能力
```
GET /api/v1/health
```
返回 `builtin_tools.count` 和 `builtin_tools.names`，确认工具已注册。
---
## 配置飞书连接
1. 在飞书开放平台创建应用，开启「机器人」能力
2. 在 `.env` 中添加：
```
XXXXX_APP_ID=cli_xxx
XXXXX_APP_SECRET=xxx
XXXXX_AGENT_ID=<agent_uuid>
```
3. 创建 `app/services/xxxxx_app_service.py`（token 管理 + 消息发送）
4. 创建 `app/services/xxxxx_ws_handler.py`（WebSocket 长连接 + 消息路由）
5. 在 `app/core/config.py` 添加配置字段
6. 在 `app/main.py` startup 事件中启动 WS 客户端
7. 重启后端