# 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 ``` 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 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 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)