Control Plane 与 Agent Connections v2

API 基线

Control Plane 主机是 https://api.host.langchain.com，路径本身带版本号，例如 /v2/...。
文档给出的服务端认证基线是 X-Api-Key: <LangSmith API key>。各 OpenAPI 操作还列出 API Key、Tenant ID、Bearer Auth 安全方案，但客户端不应据此猜测三者可以随意互换；应采用账户与部署模式明确授权的方式。
这些接口管理的是 Agent 与 OAuth 凭据之间的引用关系，不是把明文 token 返回给 Agent。日志、Trace、异常信息都不能记录 access token、refresh token 或 OAuth authorization code。

四个操作

方法与路径	请求	成功	语义
`POST /v2/auth/agents/{agent_id}/connections`	`oauth_token_id` 必填	201	将一个已有 OAuth token 连接到 Agent
`GET /v2/auth/agents/{agent_id}/connections`	`agent_id` 路径参数	200	列出 Agent 的全部连接
`DELETE /v2/auth/agents/{agent_id}/connections/{connection_id}`	Agent 与连接 ID	204	删除连接关系
`POST /v2/auth/agents/{agent_id}/providers/{provider_id}/tokens`	见下文	201	导入外部取得的 token，并替换同 Agent + Provider 的旧连接

参数或结构不合法统一可能返回 422。

连接模型

AgentConnectionResponse 是可公开给调用方的连接摘要，包含：

id、agent_id、oauth_token_id、provider_id；
可空的 provider_account_label 与 expires_at；
scopes、created_by、created_at。

它不包含 access token 或 refresh token。oauth_token_id 是引用，不应被当成凭据本身。

导入并绑定 Provider Token

UpsertAgentProviderTokenRequest 只有 access_token 必填；可选字段为 refresh_token、expires_in_seconds、scopes、provider_account_label 和自由结构 metadata。该入口用于 Managed Deep Agents 一类在外部完成 OAuth、再把凭据绑定到合成 agent_id 的流程。

替换规则比普通“覆盖”更谨慎：

同一个 agent_id + provider_id 的旧连接会被替换。
旧 token 只有在“Agent 自有、没有用户 owner、也没有其他 Agent 连接引用”时才会删除。
用户 Vault 凭据和共享 token 会被保留。
导入的 token 没有 LangSmith 用户 owner，通过 Agent connection 路径解析。

因此，业务端不能在替换后擅自级联删除用户凭据；服务端引用计数和 owner 语义才是删除依据。

生产设计要点

将 (agent_id, provider_id) 视作逻辑唯一键；重试前先查询或使用服务端 upsert 语义，避免并发创建重复连接。
删除连接是解绑，不等同于撤销 Provider 侧授权。若产品要求彻底撤销，还需调用 OAuth Provider 的 revoke 能力或 Auth Service 的 token 删除接口。
scopes 应按最小权限申请，并在工具调用前再次校验；UI 展示 provider_account_label 时避免暴露邮箱、租户等不必要标识。
token 的过期与刷新必须由凭据服务处理；不要仅凭 expires_at 在 Agent 进程中缓存长期可用结论。