Agent 一旦从“回答问题”进入真实系统,最危险的部分往往不是模型本身,而是它可以调用哪些工具、以谁的身份调用、一次调用消耗多少预算,以及出了问题能不能追溯。
LangChain 在 2026 年 11 月 19 日发布了 LangSmith Tool Gateway 相关内容,并把 Agent 治理放到可观测性、评测和运行时同等重要的位置。本文不复述产品宣传,而是把这个热点拆成一套与 LangChain/LangGraph 无关的工程方法:工具目录、身份边界、预算门禁、审批和审计必须同时存在。
【配图 1:Agent 工具治理的四道门——发现、授权、预算、审计】
先看一个真实的故障模式
很多项目的工具调用链只有三步:模型选择工具、后端执行函数、把结果返回模型。上线后常见问题却是:
- 同名工具在不同环境指向不同服务,Agent 无法判断风险。
- 用户 A 的凭据被错误地用于用户 B 的请求。
- 重试机制把扣款、发货等副作用工具执行了两次。
- 失败日志只记录“tool error”,没有参数摘要、授权决策或 trace。
- 团队为了排障把完整 token 和业务数据写入 trace。
工具治理的目标不是让所有调用都弹窗审批,而是让每一次高风险动作都具备可解释的决策和可追溯的证据。
工具目录:先把“能调用什么”说清楚
工具目录至少应包含名称、版本、风险级别、所需权限、超时和副作用类型。不要只依赖函数名或 docstring:
TOOLS = {
"search_orders": {
"version": "2026-11",
"risk": "read",
"scopes": {"orders:read"},
"timeout_s": 5,
"idempotent": True,
},
"refund_order": {
"version": "2026-11",
"risk": "write",
"scopes": {"orders:refund"},
"timeout_s": 8,
"idempotent": False,
"approval": "human",
},
}
目录中的 risk 不代表工具一定安全,而是告诉策略层需要走哪条门。读操作可以自动执行,写操作需要幂等键和更严格的权限,资金、删除和外发消息则应默认进入人工审批或独立策略。
【配图 2:工具按风险分层——读、写、高影响动作】
身份边界:模型不应该拥有“万能凭据”
工具调用必须绑定真实请求的 user_id、tenant_id 和 scopes。模型可以提出“调用退款工具”,但不能自行决定使用哪个用户的 token,也不能把一个请求里的凭据写入长期记忆。
def authorize(call, principal, tool):
if call["tool"] not in TOOLS:
return False, "unknown_tool"
required = TOOLS[call["tool"]]["scopes"]
if not required.issubset(principal["scopes"]):
return False, "missing_scope"
if call["tenant_id"] != principal["tenant_id"]:
return False, "tenant_mismatch"
return True, "allowed"
授权结果要写入审计事件,但日志只保留必要的身份摘要,不能把完整密钥、Cookie、银行卡号或原始业务文件放进 trace。
预算门禁:限制的不只是 token
工具治理还要限制时间、次数、金额和并发。可以把一次 Agent run 的预算写成状态对象:
from dataclasses import dataclass
@dataclass
class Budget:
tool_calls: int = 0
seconds: float = 0
amount: float = 0
max_calls: int = 12
max_seconds: float = 30
max_amount: float = 1000
def allow(self, cost=0, seconds=0):
return (self.tool_calls < self.max_calls
and self.seconds + seconds <= self.max_seconds
and self.amount + cost <= self.max_amount)
预算拒绝也应该是结构化结果,例如 budget_exceeded、approval_required、rate_limited,而不是让模型把异常文本当成普通工具输出继续猜测。
幂等与审批:副作用工具要能安全重试
对写操作,先生成业务幂等键,再执行副作用:
def execute_write(call, store, executor):
key = (call["tenant_id"], call["idempotency_key"])
previous = store.get(key)
if previous:
return previous
result = executor(call["args"])
store.put(key, result)
return result
真实系统还需要数据库唯一约束或分布式锁,不能只靠内存字典。审批状态也要和工具调用绑定:pending、approved、rejected、expired。审批通过后如果参数、用户、租户或版本发生变化,应重新审批。
【配图 3:一次工具调用的决策流——策略拒绝、审批或执行】
审计事件:记录为什么,而不是只记录做了什么
最小审计事件可以长这样:
{
"run_id": "run_123",
"tool": "refund_order",
"tool_version": "2026-11",
"principal": "user:hash_abc",
"tenant": "tenant:hash_xyz",
"decision": "approval_required",
"reason": "write operation",
"input_digest": "sha256:...",
"trace_id": "trace_456"
}
input_digest 用于关联同一请求,不等于把原始参数写入日志。需要排障时,再按权限从受保护存储读取脱敏后的参数。对于敏感 trace,可以设置字段级遮罩、保留周期和访问审计。
LangGraph 接入时的状态边界
把治理逻辑放在模型节点之后、真正工具执行之前,通常比把规则写进 prompt 可靠:
model node
↓ tool_call
policy node:目录、身份、预算、审批
├─ denied → 结构化错误 → model / human
├─ pending → interrupt 等待审批
└─ allowed → tool executor → audit event → result
LangGraph 的 checkpoint 可以帮助恢复中断状态,但恢复不等于重新执行副作用。恢复时要再次检查幂等键、审批版本和预算余额。
排障顺序:先看决策,再看工具
当 Agent “不会用工具”时,按下面顺序查:
- 工具目录是否发布了正确版本和 schema。
- 模型产生的 tool call 是否经过解析和参数校验。
- principal 的租户和 scope 是否正确。
- 策略节点返回了 allowed、denied 还是 pending。
- 是否因为预算、限流或审批过期而拒绝。
- 真正执行后,副作用是否带幂等键。
- trace 是否能关联 run、tool、decision 和结果。
不要先修改 prompt。很多“模型不会调用”的问题,实际是工具被策略层拒绝、参数 schema 过期,或者授权上下文没有传递。
上线前的最小验收清单
[ ] 工具有版本、风险、scope、超时和幂等属性
[ ] 每次调用绑定 user_id、tenant_id 和 trace_id
[ ] 模型不能直接选择凭据或越过策略节点
[ ] 写操作具备幂等键,重试不会重复副作用
[ ] 高影响动作有审批、过期和参数变更重审
[ ] 工具次数、时间、金额和并发都有预算
[ ] 拒绝原因结构化,不让模型猜异常文本
[ ] trace 脱敏,不记录完整 token 和业务密文
[ ] 恢复 checkpoint 时不会自动重放副作用
[ ] 审计能回答“谁、何时、为何、调用哪个版本”
结语
Tool Gateway 的价值不只是提供一个统一入口,而是把工具调用从“模型想做什么就做什么”变成可治理的执行请求:先发现工具,再校验身份,检查预算,必要时审批,最后执行并留下证据。
当 Agent 走向后台运行、多租户和高影响业务时,这条决策链比继续堆提示词更重要。
本文依据 LangChain 2026 年 11 月 19 日公开的 Tool Gateway 与 Agent Governance 动态整理,代码为原创教学实现,不代表 LangSmith 内部实现,也未连接真实生产工具。