跳转至

接口契约（已实现）

范围说明

本页仅描述当前代码中已实现、可对接的接口契约与交互约定。

快速入口

MCP 出站能力约定

  • 本版本仅支持 出站 MCP Client 能力（Agent 消费外部 MCP Server），不包含入站 MCP Server。
  • MCP 能力按 agent_id 解析挂载：未配置 MCP 挂载时，对话行为与现有流程保持一致。
  • Phase 1 支持 stdio 传输；http_sse 作为配置位保留用于后续阶段。
  • 凭据仅以加密形式存储在数据库，接口不返回明文 secret。
  • 工具调用审计可通过会话维度与 Agent 维度查询。

一、通用约定

1) 编码与时间格式

  • 所有 JSON 请求/响应均为 UTF-8 编码。
  • 时间字段统一使用 ISO 8601 字符串（由后端 Pydantic 输出）。

2) 标识符字段

  • id、session_id、thread_id、agent_id、source_id 等均为字符串。

3) 会话与消息概念

  • session：一次多轮对话的会话容器，包含状态与模型配置。
  • message：会话中的单条消息，包含角色与内容。

4) 角色（role）

当前对外接口中 role 以字符串表达（未强制枚举类型）：

  • user：终端用户
  • assistant：AI 回复
  • agent：人工坐席
  • system：系统提示或错误提示

二、AI Service（FastAPI）对接契约

1) GET /healthz

  • 用途：健康检查
  • 响应：{ "status": "ok" }

2) POST /stream（SSE 流式对话）

模型以 ChatRequest 为准（见 API 服务（mkdocstrings））。

请求语义

  • thread_id 用于标识会话；若不存在将创建新会话。
  • 可通过 model_* 覆盖当前会话的模型配置（会触发校验并写库）。
  • agent_id 可选，用于：
  • RAG 检索过滤：自动过滤为该 Agent 挂载的知识源
  • 模型默认参数：当请求未显式提供 model_* 时，使用 Agent 的默认模型配置
  • 系统提示：当 Agent 配置了 system_prompt 时，会作为系统消息影响对话
  • MCP 工具能力：当 Agent 配置了有效 MCP 挂载时，编排器可进行受控工具调用

模型默认值与覆盖优先级

当请求中包含 agent_id 时，模型参数优先级如下：

  1. 请求显式提供的 model_name、model_provider、model_temperature
  2. Agent 的默认配置（仅在请求未覆盖时生效）
  3. 系统全局默认配置

SSE 响应事件格式

服务端以 text/event-stream 输出事件，单条事件格式：data: {json}\n\n。

  • {"type":"token","content":"..."}：流式输出片段
  • {"type":"error","content":"..."}：校验或运行错误
  • {"type":"done"}：本次输出结束

说明：当前实现中会将完整回复按空格拆分为片段并模拟流式输出；无论成功或失败，都会在最后发送 done。

3) WS /ws/{session_id}（WebSocket 会话）

入站/出站模型以 IncomingWebSocketMessage / OutgoingWebSocketMessage 为准（见 API 服务（mkdocstrings））。

连接建立后的行为

  • 连接建立后，服务端立即发送 type=history，包含最近消息（当前上限为 200 条）。

消息类型（出站）

  • type=history：历史消息回放
  • type=message：单条消息（入站消息写库回传、或 AI 生成回复写库回传）
  • type=system：状态类系统事件（例如接管/释放导致的状态变更）
  • type=error：校验或运行错误

事件（入站 event）

  • 若 event 为空但 content 非空，服务端会将其视为用户消息事件（等价于 user_message）。
  • 当 event 为 agent_takeover / agent_release 时：
  • 编排器会更新会话状态（AI_ACTIVE / HUMAN_ACTIVE）
  • 服务端会额外发送一次 type=system，携带当前状态：{"status": "..."}

4) Agent / 知识源 / 文档与摄取

本组接口用于 Agent 管理、知识源管理、文档上传与摄取等能力：

5) MCP 管理接口（REST）

  • MCP Server：/mcp-servers（CRUD + health-check）
  • MCP Credential：/mcp-credentials（CRUD + rotate）
  • Agent MCP Mount：/agents/{agent_id}/mcp-mounts（CRUD）
  • MCP 审计：/sessions/{session_id}/mcp-calls、/agents/{agent_id}/mcp-calls

凭据安全约定

  • 创建/轮换凭据时，客户端提交 secret_payload。
  • 服务端在落库前加密并持久化到 encrypted_secret_json。
  • 响应仅返回凭据元数据，不回传密文或明文 secret。

审计约定

  • 每次 MCP 工具调用都会产生审计记录（success / timeout / error / blocked）。
  • 审计中的请求与响应 payload 会按敏感键进行脱敏后存储。

三、Demo Gateway（仅 demo 使用）

项目内 demo-backend 使用 Socket.IO 作为网关，将前端事件转发到 AI Service：

  • 前端 → demo-backend：事件 user_message
  • demo-backend → 前端：事件 ai_response（token|done|error）

说明：该网关属于 Demo 形态的中转层，契约可能随 Demo 演进调整；对外对接建议优先直接使用 AI Service 的 FastAPI 接口。