AuraBoot
免费开始
English简体中文

ACP 协议

Agent Communication Protocol（ACP）是 AuraBoot 用于运行 Agent 回合的服务对服务接口。MCP 向外部客户端暴露单个 Tool，而 ACP 则向后端集成方暴露整次 Agent 运行。调用方提交一份输入，获得该回合进度的 Server-Sent Events（SSE）流，并可在审批决定之后恢复已暂停的回合。

概念

ACP 封装了同样支撑 Copilot 面板与 Aura Bot 的 ConversationTurnService。差异在于传输与调用方。Copilot 由登录用户驱动；而 ACP 由另一个服务驱动，该服务希望以持久契约获得 Agent 行为。

Endpoint用途
POST /api/ai/aurabot/chat/stream启动新的 Agent 运行；打开 SSE 流
POST /api/ai/aurabot/execute在审批决定后恢复已暂停回合
GET /api/admin/agent-runs/{runId}检查运行状态，包括持久化消息与 trace

三个 Endpoint 均要求鉴权，并与其他调用一样解析 Permission。

何时使用

  • 工作流引擎希望将一个步骤委托给 Agent，并将结果流式回传。
  • 定时任务每晚运行分析 Agent 并存储输出。
  • 第三方平台通过 SSE 将 AuraBoot Agent 集成到其 UI 中。
  • Approval Gate 需要暂停一个回合，直至人工在别处处理。

交互式 UI 使用 Copilot 面板；IM 使用 Aura Bot；逐个 Tool 调用使用 MCP。

架构

   Caller (service / job / platform)
        |
        | POST /api/ai/aurabot/chat/stream
        v
   +----+--------------------------+
   |  ACP Controller               |
   |  - auth, idempotency key      |
   |  - opens SSE response         |
   +----+--------------------------+
        |
        v
   +----+--------------------------+
   |  ConversationTurnService      |
   |  runTurn(input, sseSink)      |
   +----+--------------------------+
        |
        v
   +----+--------------------------+
   |  Agent Runtime + Command      |
   |  pipeline + Approval gate     |
   +----+--------------------------+
        |
        |  events: chunk, tool_start, tool_result,
        |          confirm_required, done, error
        v
   SSE stream back to caller

事件流

SSE 流承载带类型的事件。调用方至少必须处理 chunk、confirm_required 与 done。

event: chunk
data: {"content":"Looking up customer..."}

event: tool_start
data: {"toolId":"toolu_01...","toolName":"customer.query","input":{"keyword":"acme"}}

event: tool_result
data: {"toolId":"toolu_01...","result":{"rows":3},"success":true}

event: confirm_required
data: {"toolId":"toolu_02...","toolName":"customer.archive","description":"destructive","input":{},"pendingTurnId":"01HX..."}

event: done
data: {"content":"3 customers match \"acme\". Archive them?","traceId":"..."}

done 事件表示该 SSE 流结束。若流中出现过 confirm_required 事件，则下一步是携带 pendingTurnId 调用 execute 恢复回合；否则回合已正常完成。

Approval Gate 与 resumeTurn

当一个 Tool 的风险等级需要审批时，回合会暂停。Agent 运行时发出 confirm_required（携带 pendingTurnId），随后 SSE 流关闭。调用方必须存储 pendingTurnId，将审批问题交给人工（或其他系统），然后调用 execute：

POST /api/ai/aurabot/execute
Content-Type: application/json

{
  "pendingTurnId": "01HX...",
  "toolId": "toolu_02...",
  "confirmed": true
}

execute 打开新的 SSE 流，并通过 ConversationTurnService.resumeTurn 继续同一回合。confirmed: true 对应 APPROVED，confirmed: false 对应 DENIED；拒绝的决定会用一条解释拒绝的最终助手消息短路回合。

Idempotency

/chat/stream 通过 conversationId + clientMsgId 做入站消息去重（映射到 ab_im_message，去重索引 idx_ab_im_message_dedup (conversation_id, client_msg_id)）。在同一 conversationId 下重发相同的 clientMsgId 会返回此前已持久化的消息行，而不会重复插入。请为每条入站消息生成稳定的 clientMsgId，以覆盖网络与调度重试。

POST /api/ai/aurabot/chat/stream
Content-Type: application/json

{
  "agentCode": "analyst",
  "message": "Summarize yesterday's orders and flag anomalies.",
  "conversationId": 1024,
  "clientMsgId": "nightly-analyst-2026-05-28"
}

Permission 与审计

  • 调用方以服务 principal 或被模拟用户身份鉴权。
  • 运行内的 Tool 调用尊重该 principal 的 Permission。
  • 每次运行写入带 source: "acp"、调用方、Agent、模型与 trace ID 的审计记录。
  • 通过 /api/admin/agent-runs/{runId} 可检查持久化消息与 Tool 调用。

验证清单

  • 调用方处理实际发出的事件类型（chunk、tool_start、tool_result、confirm_required、done、error；以及可选的 thinking、warning、result_contract）。
  • resume 路径 POST 到 /api/ai/aurabot/execute 并消费新的 SSE 流。
  • 可重试的调用方（任务、队列）为每条入站消息设置稳定的 clientMsgId（配合 conversationId）。
  • 审计日志显示 source: "acp" 与调用方身份。
  • 调用 principal 的 Permission 覆盖 Agent 可能选择的每个 Tool。

相关