通过 AI API 网关进行代理工具治理：范围、批准、预算和审计跟踪

代理风险不再仅限于模型提示。生产代理可以搜索内部文件、查询客户记录、调用 MCP 服务器、执行代码、打开浏览器、发送电子邮件、更新 CRM 或触发计费工作流程。治理问题变成：哪个用户、密钥、模型、代理和工具被允许执行哪个操作，有多少预算、审计跟踪和回滚路径？

如果每个团队都在自己的 SDK 代码内处理工具访问权限，则策略会分散在环境变量、提供商仪表板、应用程序中间件和未记录的 MCP 服务器中。更安全的模式是将代理工具执行视为控制平面问题，并通过每个代理都必须使用的 AI API 网关或标准工具执行包装器来强制执行。

本文将事实、建议和预测分开。事实来自当前的公共指导：OWASP 的 LLM 申请 Top 10 包括敏感信息泄露、供应链漏洞和过度代理等风险； NIST 的 AI 风险管理框架的生成式 AI 配置文件强调绘制、测量和管理生成式 AI 风险； OpenAI 的代理指南建议通过读/写访问权限、可逆性、权限和财务影响来评估工具风险； MCP 授权指南对敏感资源和操作使用范围授权概念。以下建议是实施模式，而不是通用要求。

读者问题：模型访问和工具访问被混淆了

在许多早期的法学硕士申请中，API 键回答了一个基本问题：此服务可以调用模型吗？特工们做得太粗糙了。可以发送聊天完成信息的密钥不应自动导出客户数据、运行 shell 命令、发布到 Slack、修改票证、浏览任意网站或提交付款更改。

治理层需要回答更具体的问题：

• 哪个租户、工作区、用户、服务帐户或转销商客户发起了运行？
• 使用了哪种模型、提示模板、代理版本和工具架构？
• 请求的工具是只读的、可逆的、不可逆的、面向外部的、财务的还是特权的？
• 请求者是否具有所需的范围？
• 紧急政策是否需要批准、批准、拒绝、过期或绕过批准？
• 该工具的成本是多少，调用了多少次，以及剩余的累计预算是多少？
• 有哪些证据可用于调试、合规性审查和回滚？

下面的架构假设网关已接收模型调用。然后，可以通过同一网关、sidecar 服务或通过在每次工具调用之前和之后向网关报告的标准库来路由工具执行。

参考架构：网关级工具治理层

实用的代理治理系统有七个组成部分：

1. 工具注册表：批准的工具、MCP服务器、托管函数、本地执行工具和内部 API 的权威列表。
2. 身份和密钥层：网关密钥、用户、租户、服务帐户、团队和转销商客户。
3. 范围引擎：策略检查，决定密钥或用户是否可以调用特定工具功能。
4. 风险分类：描述爆炸半径、数据敏感性、可逆性、外部影响和成本风险的元数据。
5. 审批工作流程：在执行前对高风险操作进行人工或系统审批。
6. 预算和速率限制分类账：每个工具和每个代理的限制，而不仅仅是每个模型令牌的限制。
7. 审核和跟踪存储：模型调用、工具调用、批准、错误和结果的连接记录。

重要的设计决策是让网关成为政策决策点，即使实际工具在其他地方运行也是如此。例如，浏览器工具可以在沙盒工作线程中执行，CRM 写入可以在内部服务内部执行。网关仍会评估是否允许调用、记录决定、跟踪费用并返回签名的授权决定或拒绝。

第 1 步：构建中央工具注册表

工具注册表是防止“未知代理功能”成为默认功能的清单。每个工具都应该有一个所有者、一个风险层和操作元数据。最小的注册表记录可能如下所示：

{
  "tool_id": "crm.create_ticket",
  "display_name": "Create CRM support ticket",
  "owner_team": "support-automation",
  "execution_type": "internal_api",
  "server_url": "https://tools.internal.example/crm",
  "allowed_tenants": ["enterprise", "support"],
  "allowed_models": ["general-large", "general-fast"],
  "risk_tier": "reversible_write",
  "data_classification": "customer_metadata",
  "required_scopes": ["tool:crm.create_ticket"],
  "approval_policy": "not_required_under_100_tickets_per_day",
  "default_timeout_ms": 8000,
  "max_cost_per_call_usd": 0.05,
  "max_calls_per_run": 3,
  "rollback_owner": "support-ops-oncall",
  "retention_policy": "redacted_30_days"
}

对于 MCP 服务器，注册表还应包括服务器 URL、公布的工具、架构版本、授权方法、上次审核日期以及默认情况下是否禁用新工具。 MCP 提高了互操作性，但协议兼容性与生产授权不同。敏感资源和操作仍然需要明确的范围、路由检查和租户隔离。

推荐的注册表字段

• 工具名称、规范 ID、所有者和待命联系人。
• 执行位置：托管提供程序工具、MCP 服务器、内部 API、浏览器工作线程、代码运行程序、队列作业或本地 SDK 工具。
• 允许的租户、团队、用户、代理版本和模型配置文件。
• 数据分类：公共、内部、客户元数据、客户内容、机密、付款数据、凭据、监管数据。
• 风险等级和可逆性。
• 所需的范围和审批政策。
• 超时、速率限制、每次运行的最大调用次数、累计运行预算和每次调用的最大费用。
• 日志记录模式：禁止、编辑、散列、采样或显式保留完整负载。
• 回滚说明和升级路径。

第 2 步：将模型范围与工具范围分开

生产网关密钥应表达调用者可以执行的操作。模型访问和工具访问应该是独立的。例如：

model:chat
model:embeddings
tool:docs.search_readonly
tool:crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blocked

这可以防止低风险聊天机器人意外成为自动化代理。它还支持角色模板：

• 开发助手：模型聊天、文档搜索、代码讲解、无生产编写工具。
• 支持机器人：客户查找、票据创建、回复起草、外部发送所需的批准。
• 分析代理：具有行数限制的只读数据仓库查询，默认情况下无客户导出。
• 管理代理：狭窄的特权操作、强审批、短期密钥、全面审核。
• 经销商租户代理：租户范围的模型访问权限、租户范围的工具、每个客户的预算上限。

建议失败关闭：拒绝未知工具、缺少作用域拒绝执行、新公布的 MCP 工具在获得批准之前处于非活动状态，并且本地工具必须使用与托管工具相同的策略包装器。

第 3 步：按爆炸半径对工具进行分类

并非每个工具调用都需要人工批准。治理应该与风险成正比。一个有用的分类模型是：

风险等级	示例	默认控制
只读公开	公共文档搜索、公共网站提取	允许但有速率限制
只读内部	内部 wiki、产品文档	允许范围内的团队；编辑日志
只读客户数据	帐户查找，支持历史记录	租户和用户范围检查；严格审核
可逆写入	创建票证、添加草稿注释	允许但有限制并回滚所有者
外部通信	发送电子邮件、发布消息、发布内容	大多数用例的批准或预览
不可逆写入	删除记录，提交法律表格	默认拒绝或需要高信任批准
财务行动	退款、购买、结算更改	强力批准、低限额、全面审核
代码执行	运行 shell，执行 Python，部署脚本	沙箱、网络限制、超时、需要时批准
特权管理员	创建用户、更改角色、轮换凭据	默认拒绝；仅限碎玻璃工艺

此分类应在代码审核和管理界面中可见。仅工具描述是不够的，因为代理可能将描述视为指令。政策引擎应依赖注册表元数据和范围，而不仅仅是自然语言工具名称。

第 4 步：为高风险操作添加审批关口

批准应该有针对性。如果每个工具调用都需要一个人，那么代理就变得无法使用。如果没有工具调用需要批准，系统可能会授予过多的代理权。

常见审批流程：

1. 代理请求使用结构化参数调用工具。
2. 网关评估身份、范围、风险等级、预算和政策。
3. 如果需要批准，网关会返回待批准事件，而不是执行该工具。
4. 应用程序向用户显示预览或向审批渠道发送操作通知。
5. 审批者可以批准、拒绝、编辑参数（如果政策允许）或请求澄清。
6. 网关记录决策并仅执行批准的版本。

批准负载应以人性化的方式显示操作，而不仅仅是原始JSON:

{
  "approval_id": "appr_123",
  "agent_run_id": "run_456",
  "requested_by_user": "user_789",
  "tool_id": "email.send",
  "risk_tier": "external_communication",
  "summary": "Send a reply to customer@example.com about ticket #4812",
  "redacted_arguments": {
    "to": "customer@example.com",
    "subject": "Update on ticket #4812",
    "body_hash": "sha256:..."
  },
  "expires_at": "2026-08-09T12:30:00Z"
}

批准对于外部通信、财务行为、不可逆转的写入、特权管理和广泛的数据导出最有用。对于小批量公共文档搜索通常没有必要。

第 5 步：跟踪每个工具的预算和速率限制

代币预算不够。廉价的模型可能会触发昂贵的搜索、浏览器会话、代码运行、第三方API 调用或长工具循环。网关应跟踪至少四个计数器：

• 每个工具调用计数：每次运行、用户、租户和时间窗口的最大调用次数。
• 每个工具的费用：直接第三方费用、浏览器/运行时费用、搜索费用或内部退款估算。
• 代理运行累计成本：模型令牌加上工具成本。
• 循环深度：模型-工具-模型迭代的最大次数。

达到限制时，网关应尽可能避免静默硬故障。更安全的降级模式包括返回进度摘要、请求批准才能继续、降低检索深度、对后台作业进行排队或切换到只读模式。硬拒绝仍然适用于被阻止的工具、缺失范围、未知的MCP功能和危险操作。

第 6 步：将模型和工具遥测数据加入到一条审核记录中

当模型日志位于一处而工具日志位于其他位置时，代理调试会失败。审核记录应连接全链：

• 租户、工作区、用户、服务帐户和网关密钥。
• 代理 ID、代理版本、提示模板版本和模型 ID。
• 工具名称、注册表版本、服务器网址或执行环境以及架构哈希。
• 工具输入哈希或经过编辑的输入，默认情况下绝不是原始敏感负载。
• 批准状态、批准者身份、批准时间戳和批准的参数哈希。
• 延迟、重试、提供商错误、工具错误、令牌成本、工具成本和最终结果。
• 如果操作更改状态，则回滚引用。

OpenAI 的代理 SDK 跟踪文档包括 LLM 生成、工具调用、切换、护栏和自定义事件的跟踪，支持更广泛的可观察性原则：代理跟踪应包括工具活动，而不仅仅是令牌使用和延迟。但是，单个 SDK 管道可能无法覆盖每个托管工具、本地执行路径或内部 API。网关级审核有助于规范跨提供商和框架的记录。

隐私很重要。详细的日志可以改善调试和合规性审查，但原始提示和工具负载保留可能会产生新的安全责任。编辑或散列包含秘密、凭证、支付数据、个人数据或专有文档的输入。仅根据明确的保留策略、访问控制和删除规则存储原始负载。

第 7 步：将 MCP 服务器和第三方工具视为供应链依赖项

MCP 服务器和第三方工具应经历与库、网络钩子和基础架构依赖项相同的审核流程。推荐的控件包括：

• 维护已批准的 MCP 服务器和工具来源的许可名单。
• 尽可能固定版本并记录架构哈希值。
• 每个服务器和高风险工具都需要一个所有者。
• 在启用工具名称、说明、架构和权限声明之前检查它们。
• 在审核之前禁用新添加的工具。
• 验证每个路由或功能所需的范围。
• 单独的租户凭据并避免跨客户共享令牌。
• 在具有网络和文件系统限制的沙箱中运行不受信任或高风险的工具。

工具通过标准协议公开这一事实并不意味着它就安全。治理层仍然需要最低权限、显式授权、版本控制和可审核性。

实施清单

政策设计

• 为常见代理用户和服务帐户定义角色模板。
• 为模型调用和工具调用创建单独的范围。
• 按数据敏感性、可逆性、外部影响、财务影响和权限级别对工具进行分类。
• 为未知工具和缺失范围设置默认拒绝行为。
• 仅为高风险操作定义审批规则。

网关实施

• 要求每个代理通过网关或签名的策略包装器调用工具。
• 执行前检查租户、用户、密钥、代理、模型、工具、范围、预算和审批状态。
• 强制执行最大工具调用深度和累积运行成本。
• 记录每次调用的工具注册表版本和架构哈希。
• 当策略引擎无法做出决定时失败关闭。

审核和运营

• 在一个跟踪或代理运行 ID 下加入模型调用和工具调用。
• 默认情况下会对敏感工具输入进行编辑或哈希处理。
• 保留批准证据和最终执行记录。
• 向管理员公开每个工具的成本和速率限制分析。
• 记录改变状态的工具的回滚所有者。

预期的权衡

一致性与集成工作。网关级治理可在模型、SDK 和团队之间提供一致的执行。成本在于采用：开发者必须通过批准的路径路由工具执行，而不是直接从应用程序代码调用工具。

最小权限与策略复杂性。细粒度范围可减少影响范围，但需要模板、命名约定和定期清理。如果没有模板，团队可能会过度授予权限以加快行动速度。

批准与自主。人工批准可降低不可逆转操作的风险，但会增加延迟。对高风险工具使用批准，而不是每次查找或搜索。

可审核性与数据暴露。丰富的日志有助于事件响应和调试。原始有效负载日志记录可能会暴露秘密和个人数据。密文、散列、可配置的保留和访问审查不是可选的详细信息。

硬限制与任务完成。每个工具的成本限制可防止代理失控。它们还可能中断合法的长时间运行的工作。提供继续路径，例如批准继续、后台队列或汇总的部分结果。

预测：此模式的走向

预测：代理治理将变得更加以身份为中心。团队会更少地问“这个使用了哪种模型？”更常见的是“哪个经过身份验证的人员或服务允许此工具操作？”

预测：工具注册表将变得与模型注册表一样正常。随着MCP服务器、内部 API 和托管工具的增加，制作团队将需要一份允许的功能、所有者、架构和风险等级的清单。

预测：成本治理将从仅令牌报告转向行动级别报告。代理运行中成本最高的部分可能是检索、浏览器自动化、代码执行或第三方 API，而不是模型调用本身。

可行的结论

从一条规则开始：模型密钥不是工具密钥。然后向外建造。创建已批准工具的注册表、分配所有者和风险级别、要求明确的范围、仅在操作具有有意义的影响范围时添加批准、强制执行每个工具的预算以及将模型和工具事件加入到一个审核跟踪中。

我们的目标不是让代理无能为力。目标是使他们的权力清晰可见、范围明确、尽可能可逆且可问责。当代理从回答问题转向采取行动时，这是团队 API 治理的实践基础。

相关阅读

• 团队 API 密钥隔离和轮换实践
• 连接跟踪、令牌账本和安全提示日志记录
• 结构化输出和工具调用验证模式