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：

Authorization: Bearer <access_token>

Token 通过登录接口获取。

响应格式

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

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

错误响应：

{"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）

登录

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

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

响应：

{
    "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	设计预览对话历史

创建智能体

POST /api/v1/agents
Authorization: Bearer <token>
Content-Type: application/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 编排

对话请求

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	根据契约验证用户输入

契约数据结构

{
    "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": {}
}

---

健康检查

GET /health

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

---

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

快速验证命令参考 平台资料