aiagent/docs/agent-guides/创建agent.md

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 创建

# 直接创建
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 脚本创建

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. 重启后端