admin/aiagent
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a7512a54234ba0eb74218dbb097a1dfb28baa570
aiagent/docs/api-reference.md
renjianbo a7512a5423 docs: update 3 reference docs + add Android design, Feishu bot config, productization plan 
- Rewrite api-reference.md: 245 endpoints across 38 modules, correct auth paths and response format
- Rewrite 内置工具列表.md: all 56 real tools in 11 categories
- Fix quickstart.md: local dev ports (3001/8038) vs Docker (8037/8038), --port 8038
- Add android-app-design.md: Kotlin/Compose/MVVM design with SSE, FCM, voice
- Add 飞书智能体配置手册.md: all 6 bots config, capabilities, memory architecture
- Add 产品化落地方案.md: PWA/voice/push/Flutter productization roadmap

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-13 21:58:10 +08:00

12 KiB
Raw Blame History

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 场景模板/快捷创建
节点模板 /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 执行状态实时推送

健康检查

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 个端点的详细参数和在线调试功能。

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

Reference in New Issue View Git Blame Copy Permalink