---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: completed
tags:
  - langchain
  - langsmith
  - api-reference
  - oauth
topic: LangSmith Control Plane 与 Agent Connections v2
sources:
  - https://docs.langchain.com/api-reference/agent-connections-v2/create-connection
  - https://docs.langchain.com/api-reference/agent-connections-v2/list-connections
  - https://docs.langchain.com/api-reference/agent-connections-v2/remove-connection
  - https://docs.langchain.com/api-reference/agent-connections-v2/upsert-agent-provider-token
last_verified: 2026-08-11
---

# 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` 的流程。

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

1. 同一个 `agent_id + provider_id` 的旧连接会被替换。
2. 旧 token 只有在“Agent 自有、没有用户 owner、也没有其他 Agent 连接引用”时才会删除。
3. 用户 Vault 凭据和共享 token 会被保留。
4. 导入的 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 进程中缓存长期可用结论。