Agent 工具权限怎么管:LangSmith Tool Gateway 上手

LangChain 美国时间 11 月 19 日推出 LangSmith Tool Gateway(公测)。它把 Agent 调外部工具这件事集中到一层:MCP 服务器只登记一次,账号只连一次,每个 Agent 拿到一个只含自己要用的工具的 MCP 地址,调用时用谁的凭证、能不能调、调了什么,都由网关来管和记。做内部 Agent 平台、手里攒了一堆 MCP 服务器的团队,可以照下面的步骤搭一遍。
它解决的是凭证和权限散落各处的问题
官方博客举了一个美国大型零售商的例子:工程团队写了 50 多个 MCP 服务器,加起来上千个工具。门店助手要用每个店员自己的账号查库存和排班,凌晨 3 点跑的库存对账 Agent 用的是服务账号。凭证硬编码在 Agent 里、或者把整台工具服务器直接挂给 Agent,就没有任何确定性的检查能拦住它用错凭证、调用没批准的工具,安全团队事后也查不清楚。
Tool Gateway 的做法是三层认证分开:调用方只向 LangSmith 证明身份(个人访问令牌、服务密钥或身份提供商令牌);网关按「替谁调用」挑出存好的凭证;再用 OAuth 令牌或 API Key 去访问上游 MCP 服务器。Agent 手里不持有任何第三方令牌。
| 概念 | 管什么 | 容易误解的地方 |
|---|---|---|
| MCP 服务器 | 远程服务器登记一次,声明要哪种凭证 | 只支持 HTTPS 上的 Streamable HTTP,内网要走隧道 |
| 已连接账号 | 凭证归属:用户、Agent、profile 或整个工作区 | 设了工作区凭证,其他人的凭证全部被替换 |
| 工具包 | 挑一组工具,发布成一个 MCP 地址 | 不是访问控制,同一调用方走 kits/me/mcp 能看到全部 |
| 策略 | 拦截(Block)或先审批(Ask for approval) | 默认放行;拦截和审批同时命中时拦截优先 |
前置条件
- LangSmith Plus 或 Enterprise 套餐;要建工作区级服务器和工具包,得是 Workspace Admin(Editor 只能建个人的)。
- 一个个人访问令牌。文档特别说明,建服务器和工具包要用户凭证,服务密钥不行。
- 工作区 ID,所有 API 请求放在
X-Tenant-Id头里。 - 一个支持 Streamable HTTP、能加自定义请求头的 MCP 客户端,官方示例用的是 Claude Code。
五步搭一个工具包
1. 设好环境变量,确认密钥可用
export LANGSMITH_API_KEY="<个人访问令牌>"
export LANGSMITH_WORKSPACE_ID="<工作区 ID>"
export LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
curl -sS -o /dev/null -w "%{http_code}\n" \
"$LANGSMITH_ENDPOINT/v1/managed-tools/servers" \
-H "X-Api-Key: $LANGSMITH_API_KEY" \
-H "X-Tenant-Id: $LANGSMITH_WORKSPACE_ID"
打印 200 说明配置没问题。组织不在 GCP 美国区的,把 LANGSMITH_ENDPOINT 换成所在区域的地址。
2. 登记 MCP 服务器
界面里是 Tools → MCP servers → Add MCP server。快速上手用 Linear(https://mcp.linear.app/mcp)和 Notion(https://mcp.notion.com/mcp),认证方式都选 OAuth。API 写法:
curl -sS -X POST "$LANGSMITH_ENDPOINT/v1/managed-tools/servers" \
-H "X-Api-Key: $LANGSMITH_API_KEY" \
-H "X-Tenant-Id: $LANGSMITH_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"name": "Linear", "upstream_url": "https://mcp.linear.app/mcp",
"scope": "workspace", "connection": {"type": "oauth"}}'
Google、Microsoft、Salesforce、GitHub、Linear 这些常用服务有内置服务器,由 LangSmith 托管 OAuth 应用,点 Connect 登录就行;Exa、Tavily、Parallel 搜索这类填 API Key 即可。没有 Linear 和 Notion 账号,也可以先把 LangChain 文档的公开 MCP 服务器(https://docs.langchain.com/mcp)按 Public 类型加进来练手。
3. 连接自己的账号
在服务器列表点 Connect,浏览器里授权一次,状态变成 Connected。之后凡是「以你的身份」发起的调用,网关都自动带上你的令牌。
4. 建工具包,接进 Claude Code
Tools → Tool kits → Create tool kit,挑 list_issues、save_issue、notion-search 三个工具,保存后面板上会显示工具包的 MCP 地址,/kits/ 和 /mcp 中间那串 UUID 就是工具包 ID。Agent 看到的工具名会带服务器前缀,比如 linear_save_issue。接进 Claude Code:
claude mcp add --transport http quickstart-kit \
"$LANGSMITH_ENDPOINT/v1/managed-tools/kits/$KIT_ID/mcp" \
--header "X-Api-Key: $LANGSMITH_API_KEY"
claude mcp list # 确认 quickstart-kit 显示已连接
工具包面板里也直接给了 Cursor 和 Managed Deep Agents 的配置片段,地址已经填好。
5. 给写操作加一道审批
Tools → Policies → Create policy,效果选 Ask for approval,工具选 Linear 的 save_issue。API 对应 POST /v1/agent-policies,注意它不在 /v1/managed-tools/ 下面:
{
"name": "approve-linear-issues",
"description": "每次创建 Linear issue 前先确认",
"effect": "REQUIRE_APPROVAL",
"workspace_id": "<工作区 ID>",
"scope": {
"principals": [{"type": "*", "id": "*"}],
"actions": ["<linear-server-id>_save_issue"]
}
}
策略在下一次调用时立即生效。effect 换成 FORBID 就是直接拦截;principals 可以细到某个用户、用户组、服务密钥或某个 Agent 环境,except_principals 写例外。按官方博客的说法,拦截策略和审计日志目前要联系 LangChain 团队开通,审计日志只在 Enterprise 套餐提供。
工具包只决定 Agent 看见什么,真正拦得住调用的是策略。
身份怎么选:替用户调,还是替 Agent 调
一次调用只能用一种身份。以用户身份调用时,用的是这个人自己连过的账号;还没连的话,支持 MCP URL elicitation 的客户端会把登录链接弹给用户,不支持的客户端收到 428 和链接,用户登录后后续调用自动继续。以 Agent 身份调用时,用 Agent 自己的凭证(agent auth)或者管理员预先连好的 profile;凭证缺失直接返回 409,因为没人在场登录,得管理员先补上。凌晨跑的后台任务就该走这条路。
工具多了开 search mode
很多客户端会把服务器列出的所有工具定义都塞进提示词,工具一多,上下文被占满,选错工具的概率也上来了。在工具包地址后加 ?mode=search,工具包对外只列三个工具:search_tools(按关键词找,默认返回 10 个、最多 50 个)、get_tool(取完整 schema)、call_tool(执行)。在 shell 里加这个地址记得给 URL 加引号,? 会被当成通配符。search mode 只能用在保存好的工具包和 me kit 上,单个服务器的端点不支持。思路和站内写过的 Gemini 工具检索 defer_loading 一致:先检索,再按需加载定义。
常见坑
- 拿工具包当权限控制。文档明说工具包只是筛选,同一个调用方换成
kits/me/mcp就能看到自己能用的所有工具。要限制,就写策略。被拦截的工具依旧会出现在工具列表里,策略只在调用时检查。 - 只靠身份提供商令牌认证。这类调用方能访问工作区里任何服务器和工具包,公测期的已知限制,需要配合策略收紧。
- 把工具输出当可信内容。网关把上游返回原样转给调用方,返回内容要按不可信输入处理,防提示注入。
- 撞上硬上限。单次请求 1 MB、响应 8 MB,上游 60 秒内不开始响应就超时,每个工具包最多 10,000 个工具,速率 100 次/秒、突发 1,000 次。
- 随手设工作区凭证。给某个服务器设了工作区级 API Key,其他人连过的凭证会被全部移除,所有调用都用这一把钥匙。
完成标准
claude mcp list里工具包显示已连接,让 Agent 查一次 Linear issue 能返回结果。- 让 Agent 新建 issue 时,客户端弹出审批确认。
- LangSmith 的 trace 里能看到这次调用的工具、服务器、身份、结果和耗时(trace 不记录工具的输入输出内容)。
- 后台 Agent 走 profile 或 agent auth,凭证缺失时收到 409 而不是去弹登录。
想顺带算清楚编程 Agent 花了多少钱,可以接着看站内的 LangSmith 每个 PR 成本追踪。
最后
先挑一个只读、最常用的服务器(比如文档检索)建一个三五个工具的小工具包,接进团队已在用的客户端,跑顺了再加写操作和审批策略。