---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - agent-server
  - a2a
  - mcp
  - streaming
  - observability
topic: LangSmith Agent Server A2A、MCP、Protocol v2 与 System API
sources:
  - https://docs.langchain.com/langsmith/agent-server-api/a2a
  - https://docs.langchain.com/langsmith/agent-server-api/a2a/a2a-json-rpc
  - https://docs.langchain.com/langsmith/agent-server-api/mcp
  - https://docs.langchain.com/langsmith/agent-server-api/mcp/mcp-get
  - https://docs.langchain.com/langsmith/agent-server-api/mcp/mcp-post
  - https://docs.langchain.com/langsmith/agent-server-api/mcp/terminate-session
  - https://docs.langchain.com/langsmith/agent-server-api/streaming/protocol-v2-command
  - https://docs.langchain.com/langsmith/agent-server-api/streaming/protocol-v2-event-stream-sse
  - https://docs.langchain.com/langsmith/agent-server-api/system
  - https://docs.langchain.com/langsmith/agent-server-api/system/api-documentation
  - https://docs.langchain.com/langsmith/agent-server-api/system/health-check
  - https://docs.langchain.com/langsmith/agent-server-api/system/server-information
  - https://docs.langchain.com/langsmith/agent-server-api/system/system-metrics
last_verified: 2026-08-11
---

# 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；协议升级先协商版本并跑兼容测试。