renjianbo
beff3fac8d
- Fix delete agent 500: clean up FK records (agent_llm_logs, permissions, schedules, executions, team_members) and unbind goals/tasks before delete - Remove hardcoded personality templates in Android, replace with dynamic system prompt generation from name + description - Set promptSectionsEnabled=false to bypass PromptComposer for personality - Add Tencent Cloud Linux deployment guide (Docker Compose) - Accumulated backend service updates, frontend UI fixes, Android app changes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
445 lines
14 KiB
Markdown
445 lines
14 KiB
Markdown
# 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 | 场景模板/快捷创建 |
|
||
| 场景契约 | `/scene-contracts` | 8 | 统一 DSL 契约 CRUD/预设/prompt 生成 |
|
||
| 节点模板 | `/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 | 执行状态实时推送 |
|
||
|
||
---
|
||
|
||
## 场景契约模块 `/api/v1/scene-contracts`
|
||
|
||
统一 DSL 输入契约 API，定义标准输入格式（目标/约束/产物/验收），供模板复用。
|
||
|
||
### 预置契约
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/scene-contracts/presets` | 列出 11 个预置契约元数据 |
|
||
| GET | `/scene-contracts/presets/{contract_id}` | 预置契约完整内容 |
|
||
|
||
预置契约 ID：`contract_customer_service` / `contract_dev_codegen` / `contract_ops_log_analysis` / `contract_learning_assistant` / `contract_pr_review` / `contract_daily_report` / `contract_interview_scheduler` / `contract_competitor_monitor` / `contract_test_report` / `contract_onboarding_guide` / `contract_risk_alert`
|
||
|
||
### 用户契约 CRUD
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/scene-contracts` | 用户契约列表 |
|
||
| POST | `/scene-contracts` | 创建自定义契约 |
|
||
| GET | `/scene-contracts/{id}` | 契约详情（含预置） |
|
||
| PUT | `/scene-contracts/{id}` | 更新契约 |
|
||
| DELETE | `/scene-contracts/{id}` | 删除契约 |
|
||
|
||
### DSL 操作
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/scene-contracts/generate-prompt` | 从契约生成 system prompt |
|
||
| POST | `/scene-contracts/evaluate` | 生成验收评估 prompt |
|
||
| POST | `/scene-contracts/validate-input` | 根据契约验证用户输入 |
|
||
|
||
### 契约数据结构
|
||
|
||
```json
|
||
{
|
||
"name": "契约名称",
|
||
"goal": "场景目标描述",
|
||
"role": "Agent 扮演的角色",
|
||
"constraints": ["约束1", "约束2"],
|
||
"forbidden_actions": ["禁止事项"],
|
||
"deliverables": [{"name": "产出物", "format": "markdown", "description": "描述"}],
|
||
"acceptance_criteria": ["验收条件1"],
|
||
"examples": [{"input": "输入示例", "output": "输出示例"}],
|
||
"category": "分类",
|
||
"tags": ["标签"],
|
||
"input_schema": {},
|
||
"output_schema": {}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 健康检查
|
||
|
||
```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)
|