教程2026-11-20 · 智涌AI

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

LangSmith Tool Gateway 教程头图:左侧 Tool Gateway 上手教程大字与 50+ MCP 服务器案例、检索模式 3 个工具、缺凭证返回码 409 三张数据卡,右侧流程图展示 Agent 调用工具包地址、网关识别身份、策略检查、带凭证访问上游 MCP 服务器、写入 trace 五步

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)默认放行;拦截和审批同时命中时拦截优先

前置条件

五步搭一个工具包

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 一致:先检索,再按需加载定义。

常见坑

完成标准

想顺带算清楚编程 Agent 花了多少钱,可以接着看站内的 LangSmith 每个 PR 成本追踪。

最后

先挑一个只读、最常用的服务器(比如文档检索)建一个三五个工具的小工具包,接进团队已在用的客户端,跑顺了再加写操作和审批策略。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。