Agent 接入工具后就能上线?LangSmith Tool Gateway 热点背后的权限、预算与审计实战

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 “不会用工具”时,按下面顺序查:

  1. 工具目录是否发布了正确版本和 schema。
  2. 模型产生的 tool call 是否经过解析和参数校验。
  3. principal 的租户和 scope 是否正确。
  4. 策略节点返回了 allowed、denied 还是 pending。
  5. 是否因为预算、限流或审批过期而拒绝。
  6. 真正执行后,副作用是否带幂等键。
  7. 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 内部实现,也未连接真实生产工具。

来源