通过 AI API 网关进行代理工具治理：范围、批准、预算和审计跟踪
通过 AI API 网关管理代理工具的实用参考架构：工具注册表、范围密钥、批准门、每个工具的预算、MCP 允许列表以及联合模型/工具审计跟踪。
代理风险不再仅限于模型提示。生产代理可以搜索内部文件、查询客户记录、调用 MCP 服务器、执行代码、打开浏览器、发送电子邮件、更新 CRM 或触发计费工作流程。治理问题变成：哪个用户、密钥、模型、代理和工具被允许采取哪个操作，有多少预算、审计跟踪和回滚路径？
如果每个团队都在自己的 SDK 代码中处理工具访问，那么策略就会分散在环境变量、提供商仪表板、应用程序中间件和未记录的 MCP 服务器中。更安全的模式是将代理工具执行视为控制平面问题，并通过每个代理必须使用的 AI API 网关或标准工具执行包装器来强制执行。
本文将事实、建议和预测分开。事实来自当前的公共指导：OWASP 的 LLM 申请 Top 10 包括敏感信息泄露、供应链漏洞和过度代理等风险； NIST 的 AI 风险管理框架的生成式 AI 配置文件强调绘制、测量和管理生成式 AI 风险； OpenAI 的代理指南建议通过读/写访问、可逆性、权限和财务影响来评估工具风险； MCP 授权指南对敏感资源和操作使用范围授权概念。以下建议是实施模式，而不是通用要求。
读者问题：模型访问和工具访问混淆
在许多早期的 LLM 申请中，API 密钥回答了一个基本问题：该服务可以调用模型吗？特工们做得太粗糙了。可以发送聊天完成信息的密钥不应自动导出客户数据、运行 shell 命令、发布到 Slack、修改票证、浏览任意网站或提交付款更改。
治理层需要回答更具体的问题：
- 哪个租户、工作区、用户、服务帐户或经销商客户发起了运行？
- 使用了哪种模型、提示模板、代理版本和工具架构？
- 请求的工具是只读的、可逆的、不可逆的、面向外部的、财务的还是特权的？
- 请求者是否具有所需的范围？
- 是否需要批准、批准、拒绝、过期或被紧急政策绕过？
- 该工具的成本是多少，调用了多少次，以及剩余的累计预算是多少？
- 有哪些证据可用于调试、合规性审查和回滚？
下面的架构假设网关已经接收模型调用。然后，可以通过同一个网关、sidecar 服务或通过在每次工具调用之前和之后向网关报告的标准库来路由工具执行。
参考架构：网关级工具治理层
实用的代理治理系统有七个组成部分：
- 工具注册表：已批准的工具、MCP 服务器、托管函数、本地执行工具和内部 API 的权威列表。
- 身份和密钥层：网关密钥、用户、租户、服务帐户、团队和经销商客户。
- 范围引擎：策略检查，决定密钥或用户是否可以调用特定工具功能。
- 风险分类器：描述爆炸半径、数据敏感性、可逆性、外部影响和成本风险的元数据。
- 审批工作流程：在执行前对高风险操作进行人工或系统审批。
- 预算和速率限制账本：每个工具和每个代理的限制，而不仅仅是每个模型令牌的限制。
- 审核和跟踪存储：模型调用、工具调用、批准、错误和结果的连接记录。
重要的设计决策是使网关成为策略决策点，即使实际工具在其他地方运行。例如，浏览器工具可以在沙盒工作线程中执行，CRM 写入可以在内部服务内部执行。网关仍然评估是否允许调用、记录决定、跟踪成本并返回签名的授权决定或拒绝。
第 1 步：构建中央工具注册表
工具注册表是防止“未知代理功能”成为默认设置的清单。每个工具都应该有一个所有者、一个风险层和操作元数据。最小的注册表记录可能如下所示：
<前><代码>{ "tool_id": "crm.create_ticket", "display_name": "创建 CRM 支持票证", "owner_team": "支持自动化", "execution_type": "internal_api", "server_url": "https://tools.internal.example/crm", "allowed_tenants": ["企业", "支持"],“allowed_models”：[“一般大”，“一般快速”]， "risk_tier": "reversible_write", "data_classification": "customer_metadata", "required_scopes": ["工具:crm.create_ticket"], "approval_policy": "not_required_under_100_tickets_per_day", “default_timeout_ms”：8000， “每次通话最大成本”：0.05， “max_calls_per_run”：3， "rollback_owner": "支持操作 oncall", “retention_policy”：“redacted_30_days” }对于 MCP 服务器，注册表还应包括服务器 URL、广告工具、架构版本、授权方法、上次审核日期以及默认情况下是否禁用新工具。 MCP提高了互操作性，但协议兼容性与生产授权不同。敏感资源和操作仍然需要明确的范围、路由检查和租户隔离。
推荐的注册表字段
- 工具名称、规范 ID、所有者和待命联系人。
- 执行位置：托管提供商工具、MCP 服务器、内部 API、浏览器工作线程、代码运行程序、队列作业或本地 SDK 工具。
- 允许的租户、团队、用户、代理版本和模型配置文件。
- 数据分类：公共、内部、客户元数据、客户内容、机密、支付数据、凭据、监管数据。
- 风险等级和可逆性。
- 所需范围和审批政策。
- 超时、速率限制、每次运行的最大调用次数、累计运行预算以及每次调用的最大费用。
- 日志模式：禁止、编辑、散列、采样或显式保留完整负载。
- 回滚说明和升级路径。
第 2 步：将模型范围与工具范围分开
生产网关密钥应表达调用者可以执行的操作。模型访问和工具访问应该是独立的。例如：
模型：聊天
模型：嵌入
工具：docs.search_readonly
工具：crm.create_ticket
工具：email.send_requires_approval
工具：billing.refund_blocked
工具：code.execute_blocked这可以防止低风险的聊天机器人意外成为自动化代理。它还支持角色模板：
- 开发助手：模型聊天、文档搜索、代码讲解、无生产编写工具。
- 支持机器人：客户查找、工单创建、起草回复、外部发送所需的批准。
- 分析代理：具有行数限制的只读数据仓库查询，默认情况下无客户导出。
- 管理代理：狭窄的特权操作、强大的批准、短期密钥、全面审核。
- 经销商租户代理租户范围的模型访问、租户范围的工具、每个客户的预算上限。
建议失败关闭：拒绝未知工具、缺少作用域拒绝执行、新公布的 MCP 工具在获得批准之前处于非活动状态，并且本地工具必须使用与托管工具相同的策略包装器。
第 3 步：按爆炸半径对工具进行分类
并非每个工具调用都需要人工批准。治理应该与风险成正比。一个有用的分类模型是：
<表> <标题>此分类应该在代码审查和管理 UI 中可见。仅工具描述是不够的，因为代理可能将描述视为指令。策略引擎应依赖注册表元数据和范围，而不仅仅是自然语言工具名称。
第 4 步：为高风险操作添加审批关口
批准应该有针对性。如果每个工具调用都需要一个人，那么代理就变得无法使用。如果没有工具调用需要批准，系统可能会授予过多的代理权。
常见的审批流程：
- 代理请求使用结构化参数进行工具调用。
- 网关评估身份、范围、风险等级、预算和政策。
- 如果需要批准，网关会返回待批准事件，而不是执行该工具。
- 应用程序向用户显示预览或向审批渠道发送操作通知。
- 审批者可以批准、拒绝、编辑参数（如果政策允许）或请求澄清。
- 网关记录决策并仅执行批准的版本。
批准有效负载应以人类术语显示操作，而不仅仅是原始 JSON：
<前><代码>{ "approval_id": "appr_123", "agent_run_id": "run_456", "requested_by_user": "user_789", "tool_id": "电子邮件.发送", "risk_tier": "external_communication", "summary": "向 [email protected] 发送有关票证 #4812 的回复", “redacted_arguments”：{ “至”：“[email protected]”， "subject": "票号#4812更新", “body_hash”：“sha256：...” }, “expires_at”：“2026-08-09T12:30:00Z” }批准对于外部通信、财务行为、不可逆转的写入、特权管理和广泛的数据导出最有用。对于小批量的公共文档搜索通常是不必要的。
第 5 步：跟踪每个工具的预算和速率限制
代币预算不够。廉价的模型可能会触发昂贵的搜索、浏览器会话、代码运行、第三方 API 调用或长工具循环。网关应跟踪至少四个计数器：
- 每个工具调用计数：每次运行、用户、租户和时间窗口的最大调用次数。
- 每个工具的成本：直接第三方费用、浏览器/运行时成本、搜索成本或内部退款估算。
- 代理运行累计成本：模型代币加上工具成本。
- 循环深度：模型-工具-模型迭代的最大次数。
当达到限制时，网关应尽可能避免静默硬故障。更安全的降级模式包括返回进度摘要、请求批准才能继续、降低检索深度、对后台作业进行排队或切换到只读模式。硬拒绝仍然适用于被阻止的工具、丢失的范围、未知的 MCP 功能和危险的操作。
第 6 步：将模型和工具遥测数据加入到一条审核记录中
当模型日志位于一个位置而工具日志位于其他位置时，代理调试会失败。审计记录应连接全链：
- 租户、工作区、用户、服务帐号和网关密钥。
- 代理 ID、代理版本、提示模板版本和模型 ID。
- 工具名称、注册表版本、服务器 URL 或执行环境以及架构哈希。
- 工具输入哈希或经过编辑的输入，默认情况下绝不是原始敏感负载。
- 批准状态、批准者身份、批准时间戳和批准的参数哈希。
- 延迟、重试、提供商错误、工具错误、令牌成本、工具成本和最终结果。
- 如果操作更改状态，则回滚参考。
OpenAI 的 Agents SDK 跟踪文档包括 LLM 生成、工具调用、切换、护栏和自定义事件的跟踪，支持更广泛的可观察性原则：代理跟踪应包括工具活动，而不仅仅是令牌使用和延迟。但是，单个 SDK 管道可能无法涵盖每个托管工具、本地执行路径或内部 API。网关级审计有助于规范跨提供商和框架的记录。
隐私很重要。详细的日志可以改善调试和合规性审查，但原始提示和工具负载保留可能会产生新的安全责任。编辑或散列包含秘密、凭证、支付数据、个人数据或专有文档的输入。仅在明确的保留策略、访问控制和删除规则下存储原始有效负载。
第 7 步：将 MCP 服务器和第三方工具视为供应链依赖项
MCP 服务器和第三方工具应经历与库、Webhook 和基础设施依赖项相同的审核流程。推荐的控件包括：
- 维护已批准的 MCP 服务器和工具来源的许可名单。
- 尽可能固定版本并记录架构哈希。
- 要求每台服务器和高风险工具都有一个所有者。
- 在启用工具之前检查工具名称、描述、架构和权限声明。
- 在审核之前禁用新添加的工具。
- 验证每条路线或功能所需的范围。
- 单独的租户凭据并避免跨客户共享令牌。
- 在受到网络和文件系统限制的沙箱中运行不受信任或高风险的工具。
工具通过标准协议公开的事实并不意味着它是安全的。治理层仍然需要最低权限、显式授权、版本控制和可审计性。
实施清单
政策设计
- 为常见代理用户和服务帐户定义角色模板。
- 为模型调用和工具调用创建单独的范围。
- 按数据敏感性、可逆性、外部影响、财务影响和权限级别对工具进行分类。
- 为未知工具和缺失范围设置默认拒绝行为。
- 仅为高风险操作定义审批规则。
网关执行
- 要求每个代理通过网关或签名的策略包装器调用工具。
- 在执行前检查租户、用户、密钥、代理、模型、工具、范围、预算和审批状态。
- 强制执行最大工具调用深度和累积运行成本。
- 记录每次调用的工具注册表版本和架构哈希。
- 当策略引擎无法做出决定时，失败关闭。
审计和运营
- 在一个跟踪或代理运行 ID 下加入模型调用和工具调用。
- 默认情况下会对敏感工具输入进行编辑或哈希处理。
- 保留批准证据和最终执行记录。
- 向管理员公开每个工具的成本和速率限制分析。
- 记录改变状态的工具的回滚所有者。
预期的权衡
一致性与集成工作。网关级治理可在模型、SDK 和团队之间提供一致的执行。成本在于采用：开发人员必须通过批准的路径路由工具执行，而不是直接从应用程序代码调用工具。
最小权限与策略复杂性。细粒度范围可减少爆炸半径，但它们需要模板、命名约定和定期清理。如果没有模板，团队可能会过度授予权限以加快行动速度。
批准与自治。人工批准可以降低不可逆转操作的风险，但会增加延迟。对高风险工具使用批准，而不是每次查找或搜索。
可审核性与数据暴露。丰富的日志有助于事件响应和调试。原始有效负载日志记录可能会暴露秘密和个人数据。编辑、散列、可配置保留和访问审查不是可选细节。
硬限制与任务完成。每个工具的成本限制可防止代理失控。它们还可能中断合法的长时间运行的工作。提供延续路径，例如批准继续、后台队列或汇总的部分结果。
预测：此模式的走向
预测：代理治理将变得更加以身份为中心。团队会更少地问“这个使用了哪种模型？”更常见的是“哪个经过身份验证的人员或服务允许此工具操作？”
预测：工具注册表将变得像模型注册表一样正常。随着 MCP 服务器、内部 API 和托管工具的增加，生产团队将需要一份允许的功能、所有者、模式和风险层的清单。
预测：成本治理将从仅令牌报告转向行动级别报告。代理运行中最昂贵的部分可能是检索、浏览器自动化、代码执行或第三方 API，而不是模型调用本身。
可行的结论
从一条规则开始：模型密钥不是工具密钥。然后向外建造。创建批准工具的注册表，分配所有者和风险等级，要求明确的范围，仅在操作具有有意义的爆炸半径时添加批准，强制执行每个工具的预算，以及将模型和工具事件加入到一个审计跟踪中。
我们的目标不是让代理变得无能为力。目标是使他们的权力清晰可见、范围明确、尽可能可逆且可问责。这是代理从回答问题转向采取行动时团队 API 治理的实践基础。