AI Gateway Architecture2026年7月2日Big Y

AI Agent 网关控制：工具使用、预算、日志和停止条件

在 AI Agent 进入生产环境之前，使用 AI Agent 网关控制来管理工具访问、预算、请求日志、回退行为和停止条件。

AI Agent 网关控制是决定 Agent 可以调用什么、可以花费多少、必须记录什么证据以及何时必须暂停、回退或停止运行的操作规则。没有这些控制，Agent 网关就会成为隐藏工具泛滥、失控的 token 支出和不明确的生产故障的更快方式。

目标不是将每个 Agent 都包裹在流程中。目标是在 Agent 行为到达生产用户之前使其可被检查。一个可以查询订单的支持 Agent、一个可以编辑文件的编码 Agent 和一个可以比较发票的财务 Agent，不应共享相同的工具访问权限、预算、日志记录或停止策略。

使用本指南将 AI Agent 网关控制设计为策略、证据字段和验收测试。然后在推出前，在 Flatkey 定价页面上验证当前的 Flatkey 模型、路由、使用情况和计费证据。

AI Agent 网关控制始于策略边界

Agent 网关位于 Agent 运行时、模型 API、内部工具和财务审查之间。这使其成为标准化四项决策的理想位置：

控制领域	网关问题	生产证据
工具使用	此工作流可以调用哪些工具，使用哪些参数，以及需要谁的批准？	工具名称、模式版本、参数、批准状态、结果状态
预算	允许多少输入、输出、推理、工具、重试和回退支出？	Token 数量、请求成本、所有者密钥、预算结果、回退支出
日志	发生了什么，哪个路由为其提供服务，以及稍后可以审查什么？	请求 ID、工作流、模型、路由、工具调用、停止原因、错误代码
停止条件	运行应何时完成、重试、请求批准、回退或关闭失败？	停止条件、回退原因、审查者决定、最终状态

这些 AI Agent 网关控制应像基础设施策略一样进行审查，而不是像提示文案一样。提示可以解释意图，但网关策略应强制执行当模型请求敏感工具、超出预算、收到意外的工具结果或循环时会发生什么。

工具使用控制：允许比 Agent 已知更少的工具

工具调用功能强大，因为它将模型连接到真实系统。这也是 Agent 从建议跨越到行动的地方。OpenAI 的函数调用文档将工具调用描述为一个多步骤流程：模型请求一个工具，您的应用程序执行它，然后将工具输出返回给模型。Anthropic 的工具使用文档类似地让 Claude 返回 tool_use 块，由应用程序代码负责执行。Google Gemini 函数调用也依赖于声明的函数和模型生成的函数调用。

这种通用模式对于 AI Agent 网关控制至关重要：模型不应直接执行工具。您的网关或运行时应决定是否允许所请求的工具、参数是否符合策略、是否需要批准以及工具结果是否可以安全地发回。

使用三层工具策略：

工具目录：组织中存在的全套工具。
工作流允许列表：特定 Agent 路由可以调用的较小工具集。
回合级限制：在经过角色、租户、环境、预算和风险检查后，此请求可用的工具。

例如，客户支持 Agent 在正常模式下可以访问 lookup_order、search_policy 和 open_ticket。在工作流达到批准的升级路径之前，它不应接收 issue_refund、cancel_contract 或 delete_account。

控制应该是明确的：

workflow: support_resolution_agent
tool_policy:
  default_mode: deny
  allowed_tools:
    - lookup_order
    - search_policy
    - open_ticket
  approval_required:
    - issue_refund
    - cancel_subscription
  blocked_tools:
    - export_customer_database
schema_rules:
  require_strict_arguments: true
  reject_unknown_fields: true
  log_redacted_arguments: true
on_violation:
  action: stop
  user_message: ask_for_human_review

OpenAI 的函数调用指南建议使用清晰的函数描述、JSON 模式、在支持的情况下使用严格模式，并保持初始可用函数集较小。这不仅仅是模型性能建议，也是一种 Agent 网关控制：暴露的工具越少，意味着事件发生后需要审查的无效状态就越少。

预算控制：限制整个运行，而不仅仅是单个模型调用

Agent 成本很少来自一次干净的请求。它来自工具模式、对话历史、检索上下文、推理 token、工具结果、重试、回退模型以及部分失败后的重复尝试。

预算 AI Agent 网关控制应涵盖整个运行：

预算层面	限制内容	重要性
请求预算	输入 token、输出 token、推理 token、最大模型调用次数	防止单次交互变成意外的支出事件
工具预算	工具调用次数、工具结果大小、外部 API 支出	防止工具循环和昂贵的数据拉取
重试预算	重试次数、可重试状态码、退避窗口	将弹性与不受控制的重复分离开
回退预算	回退模型数量、回退成本上限、回退原因	避免可靠性掩盖了主路由损坏的问题
所有者预算	项目、团队、客户、环境、密钥或工作流限制	使支出可供财务和工程部门审查

当超出硬性限制时，网关应采用失败关闭策略。它可以进行总结、请求缩小范围、将任务排入人工审核队列或返回受控错误。它不应静默地发送更大的提示、切换到更昂贵的路由或持续重试。

使用此预算形态：

budget_policy:
  workflow: invoice_reconciliation_agent
  owner_key: finance_ops
  per_request:
    max_input_tokens: 32000
    max_output_tokens: 4000
    max_model_calls: 4
    max_tool_calls: 5
  per_session:
    max_total_tokens: 90000
    max_total_cost_usd: reviewed_threshold
  retry:
    max_attempts: 2
    retryable_statuses: [408, 409, 429, 500, 502, 503, 504]
  fallback:
    max_fallbacks: 1
    require_reason: true
  on_over_budget:
    action: stop_or_request_scope_reduction

这就是 Flatkey 公开产品层面发挥作用的地方。当前的 Flatkey 主页将平台定位为围绕统一模型访问、路由、计费、使用分析和操作控制。当前的定价页面描述了预付充值、使用分析、成本控制、请求日志、跨提供商的统一发票以及团队采购路径。将这些视为当前的公开规划证据，然后在生产前在仪表板中运行您自己的验证。

日志：记录证据，而不仅仅是原始提示

Agent 日志需要回答两个问题：运行时发生了什么，以及谁能证明策略有效？

Vercel 的 AI Gateway 可观测性文档描述了用于支出、模型使用、可观测性指标、请求摘要、API 密钥和请求日志的网关日志。OpenAI 的 Agents SDK 可观测性文档描述了可包括模型调用、工具调用、交接、护栏和自定义跨度的追踪。这些示例指向了相同的操作要求：agent 网关需要能够将模型行为与路由、工具、预算和停止决策联系起来的日志。

对于 AI agent 网关控制，至少应记录以下字段：

字段	示例	重要性
`request_id`	网关生成的 UUID	连接模型、工具、计费和支持记录
`workflow_class`	support_agent, code_agent, finance_agent	对策略和验收测试进行分组
`owner_key`	团队、应用、客户、环境	支持支出分配和滥用审查
`requested_model`	模型别名或路由名称	显示应用请求的内容
`served_model`	实际的提供商/模型	显示网关提供的内容
`tool_calls`	名称、模式版本、已编辑的参数、状态	证明工具策略的行为
`usage`	输入、输出、推理、缓存、总 token 数	将行为与成本联系起来
`budget_result`	允许、警告、阻止	证明成本门控已运行
`stop_condition`	完成、达到最大步数、超出预算、需要批准	解释运行如何结束
`fallback_reason`	超时、429、提供商错误、质量门控	将恢复与漂移分离开

不要因为容易就永久记录所有内容。客户数据、提示、工具结果和文件可能包含敏感信息。一个持久的日志设计应定义编辑、保留、访问审查、导出需求和事件处理程序。网关应存储足够的证据来调试和核对使用情况，而不是将每个请求都变成一个不受控制的数据存档。

停止条件：在模型启动前定义运行的终点

停止条件不仅仅是模型的停止序列。它们是安全结束 agent 运行的规则。

提供商 API 暴露了不同的响应和停止层面。Anthropic 的 Messages API 在其文档中暴露了 stop_reason 字段，例如工具使用、回合结束、达到最大 token 数和停止序列。OpenAI 的 Agents SDK 护栏文档将护栏和人工审核框定为决定运行是继续、暂停还是停止的控制措施。在生产中，您的网关应将这些特定于提供商的状态规范化为您的团队能够理解的工作流状态。

使用停止矩阵：

停止条件	网关操作	面向用户的行为	所需证据
已完成	返回最终答案	正常响应	最终模型、使用情况、无未解决的工具
需要工具批准	暂停	“此操作需要审核”	工具调用、参数、批准人、决定
超出预算	停止或要求缩小范围	“缩小请求范围”	预算字段、阈值、所有者密钥
达到最大步数	停止	“本次运行无法完成”	步数、最后操作、循环信号
工具错误	重试、回退或停止	清晰的失败路径	工具状态、错误类别、重试次数
提供商超时	重试或回退	降级但受控的响应	路由、超时、回退原因
违反策略	停止	拒绝或转接人工	触发的策略、经编辑的样本
置信度低或缺少证据	追问或上报	“需要更多信息”	缺失字段、评估结果

重点是每个终端状态都有一个名称。如果仅有的状态是“成功”和“错误”，团队就无法判断代理是遵守了策略还是仅仅意外停止。

一个实用的 AI Agent 网关控制模板

使用一个策略文件，工程、安全、财务和产品团队可以共同审查：

policy_name: ai_agent_gateway_controls_v1
owner:
  team: ai_platform
  reviewers:
    - engineering
    - finance
    - security
workflow_classes:
  support_agent:
    route: balanced_text_tool_route
    allowed_tools: [lookup_order, search_policy, open_ticket]
    approval_tools: [issue_refund, cancel_subscription]
    max_tool_calls: 5
    max_model_calls: 4
  code_agent:
    route: code_review_route
    allowed_tools: [read_repo, search_repo, propose_patch]
    approval_tools: [apply_patch, run_shell_command]
    max_tool_calls: 12
    max_model_calls: 8
budget_rules:
  require_owner_key: true
  block_when_owner_budget_exceeded: true
  require_fallback_reason: true
log_rules:
  capture_request_id: true
  capture_requested_and_served_model: true
  capture_tool_call_status: true
  redact_sensitive_arguments: true
stop_rules:
  max_steps: 12
  max_retries_per_tool: 1
  on_policy_violation: stop
  on_approval_required: pause
acceptance_tests:
  - blocked_tool_is_not_executed
  - over_budget_request_fails_closed
  - approval_tool_pauses_run
  - fallback_records_reason
  - request_log_contains_usage_and_stop_condition

此文件不能取代应用程序代码。它为代码提供了一个需要强制执行的契约，并为审查人员提供了一个可供检查的具体产物。