A2A、MCP、Protocol v2 与 System API

A2A JSON-RPC

POST /a2a/{assistant_id} 暴露 Assistant 为 A2A Agent；/a2a 聚合页与具体页是同一操作的两个文档入口。Accept 对 message/stream 必须含 text/event-stream，其余用 JSON。

支持方法：

message/send：发送并等最终 Task；
message/stream：SSE 流式 JSON-RPC 响应；
tasks/get：按 Task ID 查询；
tasks/cancel：当前不支持，会返回错误。

message.contextId 映射 LangGraph thread_id；省略会创建新上下文。只支持 text/data parts，不支持 file part。text part 要求 Assistant input schema 有 messages 字段。A2A role 是 user/agent；message ID 由客户端生成。JSON-RPC envelope 使用 2.0、id、method 和对应 params。

因此，接入前必须读取 Assistant schema；文件用受控上传/Store 工具传递，不能伪装成 file part。context ID 是会话授权边界，服务端要校验 caller 是否有权访问该 Thread。

MCP Streamable HTTP 的实际边界

方法	路径	当前行为
POST	`/mcp/`	接收 JSON-RPC request/notification/response；200 返回结果，202 表示已接收无 body
GET	`/mcp/`	405，GET streaming 不支持；聚合页与 GET 页同一操作
DELETE	`/mcp/`	服务端无持久 session，因此 terminate 是 no-op/404

POST 的 Accept 必须同时包含 application/json, text/event-stream。服务端实现是 stateless，跨请求 session 状态不会保留；客户端不能依赖 Mcp-Session-Id 或 GET 长连接恢复。400 表示 JSON/消息/Accept 不合法，500 是服务端失败。

Protocol v2：命令面与事件面分离

Command

POST /threads/{thread_id}/commands 接受 {id, method, params}。已知方法：run.start、input.respond、agent.getTree；WebSocket 同一连接还支持 subscription subscribe/unsubscribe。启动 Run 的命令只把任务放到后台 worker，事件必须从并发事件连接观察。

响应用同一 command ID 关联：success 带 method-specific result；error 带标准错误码，如 invalid argument、unknown command、no such run/namespace/interrupt/checkpoint、permission denied、not supported。meta 的 applied_through_seq 表示响应生成时已观察到的最高事件序号，可帮助客户端对齐命令与事件。

Event SSE

POST /threads/{thread_id}/stream/events 的 body 必填 channels，可选 namespace 前缀、depth 与 since。返回 SSE：frame id 是单调 seq，event 是 method，data 是 ProtocolEvent。

通道包括 values、updates、messages、tools、lifecycle、input、tasks、custom，以及 custom:<name>。Protocol 0.0.10 起移除了 debug/checkpoints 通道：task debug 进入 tasks，checkpoint 指针附在 values 事件。

这是 POST SSE，浏览器原生 EventSource 的 Last-Event-ID 自动恢复不适用。客户端保存最后 seq，重连时在 body 传 since，服务端先回放 seq > since 再进入 live。消费者仍要按 seq 去重，并处理 buffer 过期/无可回放事件。

System 端点

方法与路径	用途
`GET /docs`	本地 Agent Server API HTML 参考
`GET /ok?check_db=0\|1`	liveness；可选真实数据库连通检查，失败 500
`GET /info`	API version、LangGraph Python version、feature flags、deployment metadata；聚合页与该操作同源
`GET /metrics?format=prometheus\|json`	Prometheus 文本或 JSON queue/worker/HTTP 指标

Kubernetes 中 /ok 不查 DB 可作为轻量 liveness，带 DB 检查更适合作 readiness；不能让数据库短抖动触发无休止重启。/info、/metrics、/docs 可能暴露版本、拓扑、队列和 feature 信息，应限内网/鉴权访问。

协议层生产要求

A2A/MCP/Protocol params 都是非可信输入，按 Assistant schema、大小、方法 allowlist 和租户权限校验。
SSE/WS 客户端设置心跳、重连退避、seq 去重、总缓冲上限与取消；断线不等于取消 Run。
JSON-RPC ID、Run ID、Thread ID 和 event seq 分别解决不同关联问题，不要混用。
metrics 建立 queue depth、worker saturation、Run latency/error/timeout、SSE reconnect 和 replay gap 告警。
对未知 method/channel fail closed；协议升级先协商版本并跑兼容测试。