协议接入 · agent-harness 开发文档

为什么需要协议接入

不论调用方是直接 import SDK，还是通过网络或 stdio 对接，这些入口都对应同一套运行时记录和行为。区别主要在于接入方式和适用场景。

边界规则

这些入口不是第二套执行语义。它们暴露的是 `agent-harness` 已经提供的运行时能力，而 agent execution 仍然留在现有执行后端和未来适配器中。

协议分工矩阵

ACP

面向 IDE、CLI、远程控制面的主 client-to-runtime 协议入口。

A2A

面向另一套 agent 平台的最小 agent-to-agent bridge，负责 task 提交、轮询、取消和 agent card。

AG-UI

面向前端界面的 SSE 事件面，负责 run 生命周期、文本流、thinking、step 和 tool call 投影。

Runtime MCP

把运行时控制面以 MCP tools 的形式暴露给外部 agent 或运维界面。

要把分层讲清楚：MCP 负责工具与上下文面，ACP 负责 editor / client 的主运行时边界，A2A 负责 agent 平台之间的桥接， AG-UI 负责 UI 事件面。这些适配层都不应该变成第二套执行引擎。

兼容性检查点

已发布的协议承诺不能只停留在文档里，还必须有回归测试兜底。当前的检查门会验证：ACP 提交的 request、A2A 查询或继续的 task，以及 runtime MCP 的 inspection，最终都必须落到同一组持久化 sessionId 与 requestId 记录上。

也就是说，外部协议表面可以把字段命名成 contextId 或 task.id，但不能在稳定 runtime contract 之外再偷偷引入一套协议私有的持久化模型或状态机。

ACP

createAcpServer(...)
serveAcpStdio(...)
serveAcpHttp(...)

ACP 是最适合作为标准运行时入口的方式。它适合 IDE、CLI、远程客户端等需要 session-centered 协议能力的场景，包括 request 提交、事件订阅、审批决策和 artifact 查询。

已验证的 wire shape

当前发布版已经覆盖 ACP 核心参考客户端流程：capability discovery、request submit、session lookup、request lookup、 newline-delimited stdio JSON-RPC、HTTP JSON-RPC、SSE runtime notifications、invalid JSON 处理，以及无 id notification 不返回响应。

Stdio

适合本地嵌入式客户端、subprocess 集成，以及直接 IDE 对接。

HTTP + SSE

适合远程界面或服务端，需要 JSON-RPC 加 runtime 事件流。

如果你要从最薄的一层 editor 或 CLI starter 开始，优先用 agent-harness acp serve --workspace . --transport stdio，并参考 examples/03_protocol-surfaces/app/acp-stdio/main.mjs。它演示的就是 IDE sidecar 或 subprocess client 会发送的 newline-delimited JSON-RPC wire shape。

如果产品侧需要嵌入式 client，而不只是启动一个 server process，使用 createAcpStdioClient(...)。它是用于 stdio request / notification 分流的最小 reference client，避免 IDE 和 CLI sidecar 重写 JSON-line parser。

A2A

serveA2aHttp(...)

当另一个智能体平台需要一层轻量、稳定的 agent-to-agent HTTP JSON-RPC 桥接时，使用 A2A bridge。它把 task 提交、列表、取消、agent card 发现、SSE task streaming，以及带轮询兼容性的 webhook push notifications 映射到同一套运行时记录上。

适配层同时保留 message/send 这类旧方法，以及 SendMessage、 GetTask、ListTasks、CancelTask、SubscribeToTask 这类更新的方法别名，把兼容工作留在 adapter 层，而不是扩散成新的产品语义。

A2A bridge 现在把公开 agent card 与 PascalCase JSON-RPC 方法对齐到 A2A v1.0 形态： supportedInterfaces 使用 protocol binding entries，task state 使用 TASK_STATE_* 枚举字符串，SendMessage 返回 { task } response wrapper， ListTasks 接受 status、pageSize 与 pageToken。旧 lowercase 方法仍继续兼容已有集成。

发现层现在也更友好：agent-card 路径会同时响应 GET、HEAD 与 OPTIONS，而 JSON-RPC 调用方则可先用 GetAgentCard 读取基础 card，再决定是否继续请求 GetExtendedAgentCard。

如果团队正在试验 registry 或 signed-card rollout，bridge 也可以额外暴露 registry URL 与 detached card-signature metadata。但这些字段只是外围发现基础设施的兼容提示，不代表 `agent-harness` 自己要接管第二套身份或信任系统。

需要流式结果时，可通过 SendStreamingMessage 或 SubscribeToTask 配合 Accept: text/event-stream 接收 SSE task snapshots；较旧的轮询型 client 仍可继续使用 task lookup 与 list 流程，而不需要改变 runtime contract。

AG-UI

serveAgUiHttp(...)

当 UI 客户端只需要基于 HTTP SSE 的 run 生命周期和文本流时，用 AG-UI。它把稳定 runtime events 映射到 AG-UI 风格的 run 、text、thinking、step 和 tool call message，让 UI 不只是显示一段纯文本 transcript。

Runtime MCP

createRuntimeMcpServer(...)
serveRuntimeMcpOverStdio(...)

Runtime MCP 把运行时本身暴露为 MCP tools。适合另一个 agent 或管理界面通过 MCP 查询 sessions、requests、approvals、events、artifacts，或者导出证据包，而不是自己再写一层 SDK glue。

这也是把治理能力讲清楚的入口：remote MCP allowlist、trust tier、tenant scope、审批升级、prompt-injection risk 与 OAuth scope policy 都应当继续由 runtime 持有，而不是分散成各个工具自己的暗规则。

同一个 control plane 现在还会显式暴露受治理工具是走人工审批，还是走 auto-approve / auto-reject 这类自动决策模式，避免审计视图只能从零散的工具定义里反推运行时策略。

怎么选

选 ACP

当你要的是最明确、最标准的外部运行时入口。

选 A2A

当另一个 agent runtime 或平台需要支持 SSE streaming、webhook push notifications、同时兼容轮询 task flow 的最小 agent-to-agent bridge。

选 AG-UI

当前端只需要基于 HTTP SSE 的 run 与文本流接口。

选 runtime MCP

当检查和操作动作更适合以 MCP tools 的方式暴露给另一个 agent。

运维检查点

审批、恢复和 artifact 查询必须仍然锚定到 harness 持久化层，而不是 backend 原生 checkpoint 对象。
不要让 transport adapter 发明第二份 runtime state 或第二套执行语义。
把真正验证过的 compatibility matrix 发出来，尤其是 ACP 的 client discovery、session lookup、submit、stream、approval 和 replay 流程。
在产品文档里明确当前采用哪一种接入方式，避免团队对“该走哪个入口”产生歧义。
发布前必须通过所选 transport 验证 session 查询、request 提交、审批流和证据导出。