aiagent/docs/api-reference.md

# API 参考文档

天工智能体平台后端 RESTful API 接口规范。所有 API 前缀为 `/api/v1`。

启动后端后访问 Swagger UI 可查看完整接口列表并在线调试。

---

## 通用规范

### 基础 URL

| 环境 | 地址 |
|------|------|
| 本地开发 | `http://localhost:8038/api/v1` |
| Docker 部署 | `http://localhost:8037/api/v1` |
| 生产环境 | `https://your-domain.com/api/v1` |

### 认证方式

受保护的接口需在请求头携带 JWT Token：

```http
Authorization: Bearer <access_token>
```

Token 通过登录接口获取。

### 响应格式

成功响应直接返回 Pydantic 模型序列化 JSON，无外层包装：

```json
{"access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer"}
```

错误响应：

```json
{"error": "ERROR_CODE", "message": "human readable message"}
```

### ID 格式

所有主键（Agent / Workflow / Execution / Goal / Task 等）均为 UUID 字符串（36 字符），不是整数。

---

## 认证模块 `/api/v1/auth`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/register` | 用户注册（email + password + nickname） |
| POST | `/auth/login` | 登录，返回 access_token |
| GET | `/auth/me` | 获取当前用户信息（需 Bearer Token） |

### 登录

```http
POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

响应：

```json
{
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer"
}
```

---

## 智能体模块 `/api/v1/agents`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/agents` | 智能体列表（分页、搜索、状态筛选） |
| POST | `/agents` | 创建智能体（含 workflow_config） |
| GET | `/agents/{agent_id}` | 智能体详情 |
| PUT | `/agents/{agent_id}` | 更新智能体（自动递增版本号） |
| DELETE | `/agents/{agent_id}` | 删除智能体（所有者或管理员） |
| POST | `/agents/{agent_id}/deploy` | 发布智能体 |
| POST | `/agents/{agent_id}/stop` | 停止智能体 |
| POST | `/agents/{agent_id}/duplicate` | 深拷贝智能体 |
| GET | `/agents/{agent_id}/export` | 导出为 JSON |
| POST | `/agents/import` | 从 JSON 导入 |
| POST | `/agents/{agent_id}/execute` | 执行智能体（agent/sequential/pipeline/debate/graph） |
| POST | `/agents/{agent_id}/create-main-agent` | 升级为主 Agent |
| GET | `/agents/{agent_id}/preview-chat-history` | 设计预览对话历史 |

### 创建智能体

```http
POST /api/v1/agents
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
    "name": "智能体名称",
    "description": "描述",
    "system_prompt": "系统提示词...",
    "model_config": {
        "provider": "openai",
        "model_name": "deepseek-v4-pro",
        "temperature": 0.8
    },
    "iteration_limit": 15,
    "include_tools": [],
    "workflow_config": {
        "nodes": [
            {"id": "start", "type": "start", "label": "开始"},
            {"id": "agent", "type": "agent", "label": "智能体"},
            {"id": "end", "type": "end", "label": "结束"}
        ],
        "edges": [
            {"source": "start", "target": "agent"},
            {"source": "agent", "target": "end"}
        ]
    }
}
```

---

## 智能体对话 `/api/v1/agent-chat`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/agent-chat/{agent_id}` | 与指定智能体对话 |
| POST | `/agent-chat/{agent_id}/stream` | 流式对话（SSE） |
| POST | `/agent-chat/bare` | 默认对话（无需 Agent 配置） |
| POST | `/agent-chat/bare/stream` | 默认流式对话（SSE） |
| POST | `/agent-chat/orchestrate` | 多 Agent 编排（route/sequential/debate） |
| POST | `/agent-chat/orchestrate/graph` | 图模式多 Agent 编排 |

### 对话请求

```http
POST /api/v1/agent-chat/{agent_id}
Authorization: Bearer <token>
Content-Type: application/json
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| message | string | 是 | 用户消息 |
| session_id | string | 否 | 会话 ID，用于恢复上下文 |
| streamlined | boolean | 否 | 是否精简输出 |

### 流式对话 SSE 事件

| 事件 | 说明 |
|------|------|
| token | 输出 token 增量 |
| tool_call | 工具调用开始 |
| tool_result | 工具返回结果 |
| done | 对话完成（含 token_usage） |
| error | 错误信息 |

### 对话分支

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/agent-chat/branches` | 创建分支 |
| GET | `/agent-chat/branches` | 列出分支 |
| GET | `/agent-chat/branches/{branch_id}` | 分支详情 |
| DELETE | `/agent-chat/branches/{branch_id}` | 删除分支 |
| POST | `/agent-chat/branches/{branch_id}/resume` | 从分支恢复 |

---

## 工作流模块 `/api/v1/workflows`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/workflows` | 工作流列表 |
| POST | `/workflows` | 创建工作流 |
| GET | `/workflows/{workflow_id}` | 工作流详情 |
| PUT | `/workflows/{workflow_id}` | 更新工作流 |
| DELETE | `/workflows/{workflow_id}` | 删除工作流 |
| POST | `/workflows/{workflow_id}/execute` | 执行工作流 |
| POST | `/workflows/validate` | 验证工作流配置 |
| GET | `/workflows/{workflow_id}/export` | 导出 JSON |
| POST | `/workflows/import` | 导入 JSON |
| GET | `/workflows/{workflow_id}/versions` | 版本历史 |
| GET | `/workflows/{workflow_id}/versions/{v}` | 特定版本详情 |
| POST | `/workflows/{workflow_id}/versions/{v}/rollback` | 回滚到指定版本 |

### 工作流模板

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/workflows/templates` | 模板列表 |
| GET | `/workflows/templates/{id}` | 模板详情 |
| POST | `/workflows/templates/{id}/create` | 从模板创建 |

---

## 知识库模块 `/api/v1/knowledge-bases`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/knowledge-bases` | 知识库列表 |
| POST | `/knowledge-bases` | 创建知识库 |
| GET | `/knowledge-bases/{kb_id}` | 知识库详情 |
| DELETE | `/knowledge-bases/{kb_id}` | 删除知识库 |
| GET | `/knowledge-bases/{kb_id}/documents` | 文档列表 |
| POST | `/knowledge-bases/{kb_id}/documents` | 添加文档 |
| DELETE | `/knowledge-bases/{kb_id}/documents/{doc_id}` | 删除文档 |
| POST | `/knowledge-bases/{kb_id}/search` | 语义搜索 |
| POST | `/knowledge-bases/{kb_id}/rag` | RAG 检索增强生成 |

---

## 工具模块 `/api/v1/tools`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/tools` | 工具列表 |
| GET | `/tools/categories` | 工具分类 |
| GET | `/tools/builtin` | 内置工具列表（56个） |
| GET | `/tools/{tool_id}` | 工具详情 |
| POST | `/tools` | 创建自定义工具 |
| PUT | `/tools/{tool_id}` | 更新自定义工具 |
| DELETE | `/tools/{tool_id}` | 删除自定义工具 |
| POST | `/tools/test/http` | 测试 HTTP 工具 |
| POST | `/tools/test/code` | 测试代码工具 |
| POST | `/tools/{tool_id}/use` | 调用工具 |

---

## 目标与任务

### 目标 `/api/v1/goals`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/goals` | 目标列表 |
| POST | `/goals` | 创建目标 |
| GET | `/goals/{goal_id}` | 目标详情 |
| PUT | `/goals/{goal_id}` | 更新目标 |
| DELETE | `/goals/{goal_id}` | 删除目标 |
| POST | `/goals/{goal_id}/start` | 启动 |
| POST | `/goals/{goal_id}/pause` | 暂停 |
| POST | `/goals/{goal_id}/resume` | 恢复 |
| POST | `/goals/{goal_id}/decompose` | 分解为任务 |
| POST | `/goals/{goal_id}/replan` | 重新规划 |
| POST | `/goals/{goal_id}/execute-async` | 异步执行 |
| POST | `/goals/{goal_id}/interact` | 对话交互 |
| GET | `/goals/{goal_id}/tasks` | 任务树 |

### 任务 `/api/v1/tasks`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/tasks` | 任务列表 |
| POST | `/tasks` | 创建任务 |
| GET | `/tasks/{task_id}` | 任务详情 |
| PUT | `/tasks/{task_id}` | 更新任务 |
| DELETE | `/tasks/{task_id}` | 删除任务 |
| POST | `/tasks/{task_id}/execute` | 执行 |
| POST | `/tasks/{task_id}/retry` | 重试 |
| POST | `/tasks/{task_id}/claim` | 认领 |
| POST | `/tasks/{task_id}/release` | 释放 |
| POST | `/tasks/{task_id}/complete` | 完成 |
| POST | `/tasks/{task_id}/fail` | 标记失败 |
| POST | `/tasks/{task_id}/approve` | 审批通过 |
| POST | `/tasks/{task_id}/reject` | 审批拒绝 |
| GET | `/tasks/{task_id}/blockers` | 阻塞项 |
| GET | `/tasks/available/{goal_id}` | 可接任务 |

---

## 智能体蜂群 `/api/v1/swarm`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/swarm/run` | 运行 Agent 蜂群 |
| POST | `/swarm/run/stream` | 流式运行（SSE） |

---

## 通知模块 `/api/v1/notifications`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/notifications` | 通知列表 |
| GET | `/notifications/unread-count` | 未读数量 |
| PUT | `/notifications/{id}/read` | 标记已读 |
| PUT | `/notifications/read-all` | 全部已读 |
| DELETE | `/notifications/{id}` | 删除通知 |

---

## 飞书集成 `/api/v1/feishu`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/feishu/event` | 飞书事件回调 |
| POST | `/feishu/bind` | 绑定飞书用户 |
| POST | `/feishu/unbind` | 解绑 |
| POST | `/feishu/lookup` | 按 open_id 查找 |
| GET | `/feishu/status` | 集成状态 |
| GET | `/feishu/pending` | 待审批绑定 |
| POST | `/feishu/bind-pending` | 审批绑定 |
| GET | `/feishu/default-agent` | 默认 Agent |
| POST | `/feishu/default-agent` | 设置默认 Agent |

---

## 监控模块

### 系统监控 `/api/v1/monitoring`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/monitoring/overview` | 系统概览 |
| GET | `/monitoring/executions` | 执行统计 |
| GET | `/monitoring/node-types` | 节点类型用量 |
| GET | `/monitoring/activities` | 最近动态 |

### Agent 监控 `/api/v1/agent-monitoring`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/agent-monitoring/overview` | Agent 监控概览 |
| GET | `/agent-monitoring/llm-calls` | LLM 调用统计 |
| GET | `/agent-monitoring/agents-stats` | Agent 统计 |
| GET | `/agent-monitoring/tool-usage` | 工具用量 |
| GET | `/agent-monitoring/daily-trend` | 每日趋势 |

---

## 其他模块速查

| 模块 | 前缀 | 端点数 | 说明 |
|------|------|--------|------|
| 执行管理 | `/executions` | 5 | 执行创建/状态/暂停恢复 |
| 执行日志 | `/execution-logs` | 8 | 日志查看/性能分析/调用链 |
| 数据源 | `/data-sources` | 7 | MySQL/PG/Mongo/Redis/CSV/JSON/API/S3 |
| 模型配置 | `/model-configs` | 6 | LLM 模型配置/测试 |
| 协作 | `/collaboration` | 2 | WebSocket 协作 + 用户列表 |
| 权限管理 | `/permissions` | 14 | 角色/权限/用户-资源分配 |
| 告警规则 | `/alert-rules` | 8 | 告警 CRUD/日志/确认 |
| Agent 市场 | `/agent-market` | 14 | 发布/安装/评分/收藏/升级 |
| 模板市场 | `/template-market` | 11 | 模板发布/安装/评分/收藏 |
| 插件 | `/plugins` | 10 | 插件 CRUD/市场/安装/开关 |
| 编排模板 | `/orchestration-templates` | 5 | 多 Agent 编排模板 CRUD |
| 平台模板 | `/platform` | 4 | 场景模板/快捷创建 |
| 节点模板 | `/node-templates` | 6 | 节点配置模板 CRUD |
| 节点测试 | `/nodes` | 1 | 单节点调试 |
| 审批 | `/approval` | 2 | 审批查询/决议 |
| 定时任务 | `/agent-schedules` | 5 | Cron 定时任务/手动触发 |
| Webhook | `/webhooks` | 2 | 按 ID/名称触发工作流 |
| 批量操作 | `/batch` | 3 | 批量执行/导出/删除 |
| 文件上传 | `/uploads` | 2 | 工作区文件上传/预览 |
| 系统日志 | `/system-logs` | 3 | 统一日志/统计/应用日志 |
| 审计日志 | `/audit-logs` | 2 | 操作审计日志/统计 |
| 反馈 | `/feedback` | 3 | 用户反馈分析/记录/负样本 |
| WebSocket | `/ws/executions/{id}` | 1 | 执行状态实时推送 |

---

## 健康检查

```http
GET /health
```

```json
{
    "status": "ok",
    "version": "1.0.0",
    "builtin_tools": {"count": 56, "ready": true}
}
```

---

> 完整接口文档：启动后端后访问 Swagger UI（本地 `http://localhost:8038/docs`，Docker `http://localhost:8037/docs`），包含全部 245 个端点的详细参数和在线调试功能。

> 快速验证命令参考 [平台资料](../平台资料.md)