CMDC Gateway API 参考

所有端点的完整请求/响应规范。Base URL 示例: http://localhost:4000

目录

• 认证
• 通用错误格式
• 健康检查
• Session 管理
  • 创建 Session
  • 查询 Session
  • 删除 Session
• Prompt API
• 事件流
  • SSE 事件流
  • SSE 事件类型详解
  • WebSocket 双向通信
• 控制 API
  • 审批通过
  • 审批拒绝
  • 回答 Agent 提问
• 统计与历史
  • 用量统计
  • 对话历史
• 回调工具注册

认证

所有 /v1/* 端点需要 API Key 认证。支持两种方式（二选一）：

API Key 在服务端配置中绑定 tenant_id，用于多租户隔离：

config :cmdc_gateway, CMDCGateway.Plugs.Auth,
  api_keys: %{
    "sk-abc123" => "tenant-a",
    "sk-xyz789" => "tenant-b"
  }

认证失败响应：

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Missing or invalid API key"
}

/healthz 端点无需认证。

通用错误格式

所有错误响应遵循统一 JSON 结构：

{
  "error": "<error_code>",
  "message": "<人类可读描述>"
}

429 特殊响应头：

HTTP/1.1 429 Too Many Requests
Retry-After: 15
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 15 seconds.",
  "retryAfter": 15
}

404 路由不匹配：

{
  "error": "not_found",
  "message": "No route matches GET /v1/unknown"
}

健康检查

检查 Gateway 服务状态，无需认证。

GET /healthz

请求：

GET /healthz HTTP/1.1
Host: localhost:4000

无请求体、无认证。

响应 200：

{
  "status": "ok",
  "version": "0.1.0",
  "sessions": {
    "active": 5
  },
  "meter": {
    "tracked_keys": 3
  },
  "timestamp": "2026-04-08T12:00:00.000000Z"
}

Session 管理

创建 Session

创建一个 CMDC Agent Session，Agent 进程随即启动并进入 idle 状态。

POST /v1/sessions

请求头：

Content-Type: application/json
X-API-Key: sk-abc123

请求体：

{
  "model": "deepseek:deepseek-chat",
  "sessionId": "my-session-001",
  "systemPrompt": "你是一个专业的编程助手",
  "workingDir": "/home/user/project",
  "tools": ["CMDC.Tool.Shell", "CMDC.Tool.ReadFile", "CMDC.Tool.WriteFile"],
  "plugins": ["CMDC.Plugin.Builtin.ApprovalGuard"],
  "blueprint": "CMDC.Blueprint.Base",
  "maxTurns": 50,
  "maxTokens": 4096,
  "skillsDirs": ["/home/user/skills"],
  "providerOpts": {
    "temperature": 0.7,
    "top_p": 0.95
  }
}

请求体字段：

响应 201 Created：

{
  "sessionId": "my-session-001",
  "status": "created"
}

响应 422 Unprocessable Entity：

{
  "error": "create_failed",
  "message": ":unknown_provider"
}

cURL 示例：

curl -X POST http://localhost:4000/v1/sessions \
  -H "X-API-Key: sk-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek:deepseek-chat",
    "systemPrompt": "你是助手",
    "tools": ["CMDC.Tool.Shell"],
    "maxTurns": 20
  }'

查询 Session

获取 Session 的当前运行状态。

GET /v1/sessions/:id

路径参数：

请求：

GET /v1/sessions/my-session-001 HTTP/1.1
X-API-Key: sk-abc123

响应 200：

{
  "sessionId": "my-session-001",
  "state": "idle",
  "turns": 3,
  "toolCalls": 5,
  "totalTokens": 12800,
  "uptimeMs": 45200
}

响应 404：

{
  "error": "not_found",
  "message": "Session my-session-001 not found"
}

删除 Session

停止 Agent 进程，清理 Session 数据和已注册的回调工具。

DELETE /v1/sessions/:id

路径参数：

请求：

DELETE /v1/sessions/my-session-001 HTTP/1.1
X-API-Key: sk-abc123

响应 200：

{
  "sessionId": "my-session-001",
  "status": "deleted"
}

副作用：

1. Agent 进程被 CMDC.stop/1 终止
2. SessionStore 中的条目被删除
3. 该 Session 注册的所有 CallbackTool 被清理
4. 活跃的 SSE/WebSocket 连接收到最终事件后断开

Prompt API

向 Agent 发送用户消息（异步）。消息被投递到 Agent 状态机后立即返回 202，后续处理结果通过 SSE 或 WebSocket 推送。

POST /v1/sessions/:id/prompt

路径参数：

请求头：

Content-Type: application/json
X-API-Key: sk-abc123

请求体：

{
  "text": "帮我用 Python 写一个快速排序"
}

响应 202 Accepted：

{
  "requestId": "a1b2c3d4e5f67890",
  "sessionId": "my-session-001",
  "queued": false
}

响应 400：

{
  "error": "bad_request",
  "message": "Missing 'text' field"
}

典型调用流程：

1. POST /v1/sessions/:id/prompt  →  202 (消息已投递)
2. GET  /v1/sessions/:id/events  →  SSE 流接收处理事件
   - event: agent_start
   - event: message_delta (多次，逐 token)
   - event: tool_execution_start (如果 Agent 调用了工具)
   - event: tool_execution_end
   - event: agent_end (本轮完成)

cURL 示例：

curl -X POST http://localhost:4000/v1/sessions/my-session-001/prompt \
  -H "X-API-Key: sk-abc123" \
  -H "Content-Type: application/json" \
  -d '{"text": "帮我用 Python 写一个快速排序"}'

事件流

SSE 事件流

建立 Server-Sent Events 长连接，实时接收 Agent 事件推送。

GET /v1/sessions/:id/events

路径参数：

请求：

GET /v1/sessions/my-session-001/events HTTP/1.1
X-API-Key: sk-abc123
Accept: text/event-stream

响应头：

HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache
X-Accel-Buffering: no
Transfer-Encoding: chunked

SSE 数据格式：

每个事件由 event: 行（事件类型）和 data: 行（JSON 载荷）组成，以双换行分隔：

event: agent_start
data: {}

event: message_delta
data: {"delta":"你"}

event: message_delta
data: {"delta":"好"}

event: message_delta
data: {"delta":"！"}

event: agent_end
data: {"messageCount":2,"lastMessage":{"content":"你好！","role":"assistant"},"tokenUsage":{"promptTokens":50,"completionTokens":5,"totalTokens":55}}

心跳：

每 30 秒发送一次 SSE 注释行，保持连接：

: heartbeat

连接终止条件：

• 客户端主动断开
• 收到 agent_end 或 agent_abort 事件后 SSE 流自动关闭
• 60 秒无事件超时自动断开

cURL 示例：

curl -N http://localhost:4000/v1/sessions/my-session-001/events \
  -H "X-API-Key: sk-abc123"

SSE 事件类型详解

共 15 种对外事件类型，按 Agent 生命周期阶段分组：

1. 会话生命周期

agent_start — Agent 开始处理当前 prompt

event: agent_start
data: {}

agent_end — Agent 完成当前 prompt 处理

event: agent_end
data: {"messageCount":4,"lastMessage":{"content":"代码已完成","role":"assistant"},"tokenUsage":{"promptTokens":500,"completionTokens":200,"totalTokens":700}}

agent_abort — Agent 被中止

event: agent_abort
data: {"reason":"max_turns_exceeded"}

prompt_received — Agent 确认收到用户 prompt

event: prompt_received
data: {"text":"帮我写个排序算法"}

2. 流式响应

message_start — LLM 开始生成回复

event: message_start
data: {}

message_delta — 流式文本片段（逐 token）

event: message_delta
data: {"delta":"def quick_sort"}

一次 LLM 回复会产生大量 message_delta 事件，客户端应逐个追加拼接完整回复。

thinking_start — Agent 思考链（Chain-of-Thought）开始

event: thinking_start
data: {}

thinking_delta — 思考链文本片段

event: thinking_delta
data: {"delta":"让我分析一下这个问题..."}

3. 工具执行

tool_calls — Agent 本轮决定调用的工具数量

event: tool_calls
data: {"count":2}

tool_execution_start — 工具开始执行

event: tool_execution_start
data: {"toolName":"Shell","callId":"tc_a1b2c3","args":{"command":"python3 sort.py","working_dir":"."}}

tool_execution_end — 工具执行完成

event: tool_execution_end
data: {"toolName":"Shell","callId":"tc_a1b2c3","status":"ok","result":"[1, 2, 3, 4, 5]"}

4. 人机交互（HITL）

approval_required — Agent 需要人类审批才能继续

event: approval_required
data: {"approvalId":"apr_x7y8z9","toolName":"Shell","args":{"command":"rm -rf /tmp/old"},"hint":"危险操作：删除文件","requestedAt":"2026-04-08T12:00:00Z"}

收到此事件后，Agent 会暂停等待，直到客户端发送 approve 或 reject。

approval_resolved — 审批已决定

event: approval_resolved
data: {"approvalId":"apr_x7y8z9","status":"approved"}

ask_user — Agent 向用户提问，等待回答

event: ask_user
data: {"ref":"ask_001","question":"你希望使用哪种排序算法？","options":["快速排序","归并排序","堆排序"]}

收到此事件后，Agent 会暂停等待，直到客户端发送 respond。

5. 错误

error — 运行时错误

event: error
data: {"reason":"Provider stream failed: connection timeout"}

WebSocket 双向通信

全双工连接，出站推送事件 + 入站接收控制消息。适合需要实时双向交互的场景（如审批、对话式 Agent）。

WS /v1/sessions/:id/ws

连接参数：

连接 URL 示例：

ws://localhost:4000/v1/sessions/my-session-001/ws?api_key=sk-abc123

连接失败响应：

连接配置：

入站消息（客户端 → Gateway）

所有入站消息为 JSON 格式，必须包含 action 字段。

1. 发送 Prompt

{
  "action": "prompt",
  "text": "帮我写一个 Hello World"
}

成功响应：

{"ok": true, "action": "prompt"}

2. 审批通过

{
  "action": "approve",
  "approvalId": "apr_x7y8z9"
}

成功响应：

{"ok": true, "action": "approve"}

3. 审批拒绝

{
  "action": "reject",
  "approvalId": "apr_x7y8z9"
}

成功响应：

{"ok": true, "action": "reject"}

4. 回答 Agent 提问

{
  "action": "respond",
  "ref": "ask_001",
  "response": "快速排序"
}

成功响应：

{"ok": true, "action": "respond"}

入站错误响应：

出站消息（Gateway → 客户端）

与 SSE 事件内容一致，但封装为 JSON 对象：

{
  "event": "<event_type>",
  "data": { ... }
}

示例：

{"event": "agent_start", "data": {}}
{"event": "message_delta", "data": {"delta": "Hello"}}
{"event": "message_delta", "data": {"delta": " World"}}
{"event": "tool_execution_start", "data": {"toolName": "Shell", "callId": "tc_001", "args": {"command": "echo hi"}}}
{"event": "tool_execution_end", "data": {"toolName": "Shell", "callId": "tc_001", "status": "ok", "result": "hi\n"}}
{"event": "approval_required", "data": {"approvalId": "apr_001", "toolName": "Shell", "args": {"command": "rm -rf /tmp"}, "hint": "危险操作", "requestedAt": null}}
{"event": "agent_end", "data": {"messageCount": 3, "lastMessage": {"content": "完成", "role": "assistant"}, "tokenUsage": {"promptTokens": 100, "completionTokens": 50, "totalTokens": 150}}}

JavaScript 客户端示例：

const ws = new WebSocket('ws://localhost:4000/v1/sessions/my-session-001/ws?api_key=sk-abc123');

ws.onopen = () => {
  ws.send(JSON.stringify({ action: 'prompt', text: '你好' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.event) {
    case 'message_delta':
      process.stdout.write(msg.data.delta);
      break;
    case 'approval_required':
      // 自动审批示例
      ws.send(JSON.stringify({ action: 'approve', approvalId: msg.data.approvalId }));
      break;
    case 'ask_user':
      ws.send(JSON.stringify({ action: 'respond', ref: msg.data.ref, response: '是的' }));
      break;
    case 'agent_end':
      console.log('\nAgent 完成');
      ws.close();
      break;
  }
};

控制 API

REST 版本的控制接口，适合不使用 WebSocket 的场景（如服务端集成、CLI 工具）。功能与 WebSocket 入站消息等价。

审批通过

POST /v1/sessions/:id/approve

路径参数：

请求头：

Content-Type: application/json
X-API-Key: sk-abc123

请求体：

{
  "approvalId": "apr_x7y8z9"
}

响应 200：

{
  "ok": true,
  "action": "approve",
  "approvalId": "apr_x7y8z9"
}

响应 400：

{
  "error": "bad_request",
  "message": "Missing 'approvalId'"
}

审批拒绝

POST /v1/sessions/:id/reject

路径参数：

请求头：

Content-Type: application/json
X-API-Key: sk-abc123

请求体：

{
  "approvalId": "apr_x7y8z9"
}

响应 200：

{
  "ok": true,
  "action": "reject",
  "approvalId": "apr_x7y8z9"
}

响应 400：

{
  "error": "bad_request",
  "message": "Missing 'approvalId'"
}

回答 Agent 提问

POST /v1/sessions/:id/respond

路径参数：

请求头：

Content-Type: application/json
X-API-Key: sk-abc123

请求体：

{
  "ref": "ask_001",
  "response": "快速排序"
}

响应 200：

{
  "ok": true,
  "action": "respond",
  "ref": "ask_001"
}

响应 400：

{
  "error": "bad_request",
  "message": "Missing 'ref' or 'response'"
}

统计与历史

用量统计

获取 Session 运行状态 + API Key 维度的用量计量数据。

GET /v1/sessions/:id/stats

路径参数：

请求：

GET /v1/sessions/my-session-001/stats HTTP/1.1
X-API-Key: sk-abc123

响应 200：

{
  "sessionId": "my-session-001",
  "state": "idle",
  "turns": 5,
  "toolCalls": 12,
  "totalTokens": 25600,
  "uptimeMs": 120000,
  "meter": {
    "promptCount": 5,
    "totalPromptTokens": 15000,
    "totalCompletionTokens": 10600,
    "totalTokens": 25600
  }
}

meter 数据是 API Key 维度的全局统计，不仅限于当前 Session。

对话历史

获取 Session 的完整消息列表。

GET /v1/sessions/:id/messages

路径参数：

请求：

GET /v1/sessions/my-session-001/messages HTTP/1.1
X-API-Key: sk-abc123

响应 200：

{
  "sessionId": "my-session-001",
  "messages": [
    {
      "id": "msg_001",
      "role": "system",
      "content": "你是一个专业的编程助手",
      "toolCalls": null,
      "callId": null,
      "name": null,
      "isError": false
    },
    {
      "id": "msg_002",
      "role": "user",
      "content": "帮我用 Python 写一个快速排序",
      "toolCalls": null,
      "callId": null,
      "name": null,
      "isError": false
    },
    {
      "id": "msg_003",
      "role": "assistant",
      "content": "好的，这是一个 Python 快速排序实现：\n\n```python\ndef quick_sort(arr):\n    ...\n```",
      "toolCalls": [
        {
          "id": "tc_001",
          "name": "WriteFile",
          "args": {"path": "sort.py", "content": "def quick_sort(arr): ..."}
        }
      ],
      "callId": null,
      "name": null,
      "isError": false
    },
    {
      "id": "msg_004",
      "role": "tool",
      "content": "File written successfully",
      "toolCalls": null,
      "callId": "tc_001",
      "name": "WriteFile",
      "isError": false
    }
  ]
}

Message 对象字段：

回调工具注册

为 Session 动态注册外部 HTTP 回调工具。注册后 Agent 可像使用内置工具一样调用它，Gateway 会代理 HTTP 请求到你的服务。

POST /v1/sessions/:id/tools

路径参数：

请求头：

Content-Type: application/json
X-API-Key: sk-abc123

请求体：

{
  "name": "query_database",
  "description": "Run a SQL query on the production database",
  "callbackUrl": "https://my-service.example.com/tools/query",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "SQL query to execute"
      },
      "database": {
        "type": "string",
        "description": "Target database name",
        "enum": ["production", "staging"]
      }
    },
    "required": ["query"]
  },
  "timeoutMs": 30000
}

响应 201 Created：

{
  "ok": true,
  "sessionId": "my-session-001",
  "toolName": "query_database"
}

响应 422：

{
  "error": "registration_failed",
  "message": "Missing required fields: name, callbackUrl"
}

回调执行流程

当 Agent 决定调用已注册的回调工具时：

1. Gateway → 你的服务（POST 请求）

Gateway 向 callbackUrl 发送 POST 请求：

POST https://my-service.example.com/tools/query HTTP/1.1
Content-Type: application/json

{
  "callId": "tc_a1b2c3d4",
  "toolName": "query_database",
  "args": {
    "query": "SELECT count(*) FROM users WHERE active = true",
    "database": "production"
  },
  "sessionId": "my-session-001"
}

2. 你的服务 → Gateway（HTTP 响应）

成功返回（HTTP 2xx）：

{
  "result": "Active users: 42,851"
}

错误返回（HTTP 2xx，业务错误）：

{
  "error": "Permission denied: read-only user cannot execute write queries"
}

HTTP 非 2xx 状态码或网络错误会被 Gateway 转换为工具执行失败，Agent 会收到包含错误详情的 tool_execution_end 事件（status: "error"）。

完整回调工具示例（Python Flask）

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/tools/query', methods=['POST'])
def handle_query():
    data = request.json
    call_id = data['callId']
    args = data['args']
    query = args.get('query', '')
    
    try:
        result = execute_sql(query)  # 你的业务逻辑
        return jsonify({"result": str(result)})
    except Exception as e:
        return jsonify({"error": str(e)})

if __name__ == '__main__':
    app.run(port=9999)

对应注册请求：

curl -X POST http://localhost:4000/v1/sessions/my-session-001/tools \
  -H "X-API-Key: sk-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "query_database",
    "description": "Execute SQL queries on the database",
    "callbackUrl": "http://localhost:9999/tools/query",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {"type": "string", "description": "SQL query"}
      },
      "required": ["query"]
    }
  }'