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

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