Reliability and Routing2026年7月27日Flatkey Team

面向 AI 代理的 Gemini API：生产集成清单

面向 Gemini 驱动代理的生产清单，涵盖稳定端点、受控模型切换、工具安全、重试、备用路由和成本可见性。

将代理连接到 Gemini API 很容易。在模型、工具、流量和预算变化时保持该集成稳定，才是生产环境中的问题。

对于代理工作流来说，API 调用只是更长系统中的一步。规划器选择一个动作，模型生成或验证参数，工具运行，记忆被更新，然后另一个模型可能会审查结果。脆弱的端点、无声的模型变更、失控的重试，或缺失的成本信号，都可能破坏整条链路。

这份清单展示了如何将一个由 Gemini 驱动的代理从成功演示推进到生产集成。它聚焦于上线后真正重要的三个决策：端点稳定性、受控的模型切换，以及成本可见性。

一张表看懂生产就绪度

领域	最低生产规则	要收集的证据
端点	将基础 URL 和凭据保存在环境配置中	来自已部署运行时的冒烟测试
模型选择	使用精确模型 ID 或已批准别名的允许列表	显示当前活动模型的配置记录
代理工具	在执行前验证工具参数	提议、接受和拒绝调用的日志
结构化输出	强制执行模式并处理无效响应	使用代表性提示的契约测试
重试	仅对短暂性故障进行重试，并设置限制和抖动	重试次数、最终状态和总延迟
回退	定义何时可使用另一个模型	日志中的路由策略和回退原因
成本	记录 token、请求、模型和工作流步骤	按运行和按功能的成本报告
安全	将提供方凭据保留在服务端并限定范围	密钥所有者、环境、轮换日期和访问策略

1. 决定 Gemini 是直接依赖还是路由能力

直接的 Gemini 集成可让你的团队使用该提供方原生的 SDK 和功能面。当应用依赖 Gemini 特有能力，且团队能够接受维护提供方特定代码时，这可能是正确的选择。

当 Gemini 只是更大代理系统中的一项能力时，API 网关会更有用。代理构建者通常需要一个用于分类的快速模型、一个用于规划的更强模型、另一个用于回退的提供方，以及单独的图像或视频模型。如果每一步都拥有不同的凭据、端点、响应格式和计费账户，运维工作会迅速扩大。

在编写更多代码之前，请先定义边界：

直接提供方边界：应用代码了解 Gemini 特定端点、模型名称、错误和 SDK 行为。
网关边界：应用代码调用一个稳定的 API 表面，而提供方选择和模型变更保留在路由配置中。
混合边界：Gemini 原生功能使用直接 API，而可移植的聊天、工具和结构化输出步骤使用网关。

目标不是隐藏每一种提供方差异。目标是避免提供方变更扩散到你的代理编排代码中。

如果你正在比较运营取舍，请阅读面向自动化构建者的 AI Gateway 和统一 AI API：何时一个访问层胜过分别管理各家供应商账户。

2. 将端点和凭据置于应用逻辑之外

不要把生产端点或 API 密钥硬编码到代理、工具定义、仓库、浏览器打包产物或提示配置中。将它们存放在部署环境或密钥管理器里。

对于直接的 Gemini 集成，请遵循 Google 当前的 API 密钥指南，并将密钥保留在服务器端。对于经由路由的集成，请将网关密钥和基础 URL 保存在同一种受保护的配置中。

兼容 OpenAI 的客户端可以让传输边界更加明确：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url=os.environ["AI_GATEWAY_BASE_URL"],
)

在 Flatkey 中，兼容 OpenAI 的基础 URL 是 https://router.flatkey.ai/v1。Flatkey API 快速开始会演示首个请求和日志检查。

生产测试必须从已部署的环境中运行，而不只是从笔记本电脑上运行。这样才能发现缺失的密钥、出站网络限制、错误的基础 URL，以及特定环境下的模型访问问题。

3. 将模型策略与提示代码分离

Google 的 Gemini 模型文档区分了模型和生命周期阶段。可用性和推荐的模型选择可能会变化，因此代理不应把模型字符串分散在规划器、工作器、评估器和后台任务中。

改为创建一个统一的模型策略对象：

{
  "planner": "APPROVED_GEMINI_MODEL",
  "tool_worker": "APPROVED_FAST_MODEL",
  "reviewer": "APPROVED_REVIEW_MODEL",
  "fallbacks": ["APPROVED_FALLBACK_MODEL"],
  "policy_version": "2026-07-27"
}

当可复现性很重要时，请使用精确的模型标识符。如果你有意使用一个可能切换到更新模型的别名，那么应将其视为一项运营决策：记录下来、监控它，并在行为发生变化时运行回归测试。

你的允许列表应回答：

哪些模型可以接收生产数据？
哪些工作流角色可以使用每个模型？
需要哪些模型功能？
每一步可接受的最高成本和延迟是多少？
谁可以更改当前生效的模型策略？

4. 测试代理实际使用的能力

一个基础的文本回复并不能证明代理集成已经准备就绪。请测试工作流中实际用到的能力组合。

工具调用

Gemini 支持函数调用，但模型提出的参数仍然必须通过应用侧验证。应将每一次工具调用都视为不可信输入。

对于每个工具：

验证必填字段、类型、范围和允许值。
将授权检查与模型意图分开。
在重试副作用之前添加幂等性保护。
记录提议的调用、验证结果、执行结果和关联 ID。
对破坏性或具有财务影响的操作要求确认。

结构化输出

当另一个系统会消费响应时，请使用结构化输出。一个看起来像 JSON 的字符串并不等于契约。请根据你的 schema 验证响应，处理拒绝或截断，并定义在缺少必填字段时的行为。

长上下文和多模态输入

如果代理会发送文档、图像、音频或很长的历史记录，请测试真实的负载大小。测量延迟、token 用量、上传行为和故障恢复。不要假设短提示基准能够预测生产路径。

5. 围绕整个代理运行设计重试

重试可以提高可靠性，但代理内部可能已经包含循环。工作流中的工具重试内再套模型重试，可能会成倍增加请求和成本。

请使用有界策略：

重试瞬态传输故障和符合条件的限流响应。
使用带抖动的指数退避。
设置最大尝试次数和最大耗时。
在不更改输入的情况下，不要自动重试无效的工具参数或 schema 失败。
除非操作是幂等的或具有幂等键，否则不要重试会产生副作用的工具。
在一个代理运行标识下记录每一次尝试。

Google 文档说明了当前 Gemini API 的速率限制。你的应用仍应使用自身的并发、队列和预算限制来保护自己，因为提供商限制并不是工作负载策略。

6. 让模型切换显式且可逆

“回退”不应意味着“随机尝试不同模型，直到有结果返回”。不同模型可能会生成不同的工具参数、格式、安全行为、延迟和成本。

生产环境中的回退策略应明确规定：

决策	示例策略问题
触发条件	回退是在超时、限流、提供商错误还是验证失败时运行？
兼容性	回退是否支持相同的工具和输出 schema？
质量	它是否通过了相同的代理回归测试套件？
预算	它是否可能超出主模型单次运行的成本？
限制	一次运行中允许切换多少次模型？
证据	日志中是否可见回退模型及其原因？

通过配置标志或路由规则来推出模型变更，而不是匆忙进行代码部署。先从影子测试或很小比例的流量开始，比较任务成功率和成本，然后再扩大范围。保留之前的模型策略以便回滚。

这正是API 网关架构可以降低运营风险的地方：应用保持一种访问模式，而经批准的路由在其后端发生变化。

7. 在工作流步骤级别衡量成本

发票总额来得太晚，也太粗粒度。一个代理团队需要知道是哪个工作流、租户、功能、模型以及重试路径产生了开销。

至少要捕获：

代理运行 ID 和工作流名称。
租户、环境和功能。
模型和提供方路由。
在可用时，输入、输出和缓存 token 字段。
请求次数、重试次数和回退次数。
工具调用次数和端到端总延迟。
每一步以及整个运行的估算或记录成本。

Gemini 响应会暴露用量信息，Google 也提供了关于 token 计数的指南。将这些字段映射到一个内部使用量模式中，这样仪表板就不会依赖某一家提供商的命名方式。

然后在三个层级添加预算：

每一步：阻止单个规划器或审查器消耗不合理的量。
每次运行：限制整个代理任务中的循环、重试和回退。
每个周期：按租户、团队、项目或环境进行告警或限流。

在流量变更之前，先查看当前模型费率。Flatkey 的定价页面提供了通过该平台可用模型的当前目录和定价视图。

8. 在切换模型前构建回归套件

即使应用代码没有变化，模型切换也属于软件变更。要基于真实且已批准的案例创建一个小型评估集。

包括：

带有已知成功结果的正常请求。
需要澄清的模糊输入。
无效的工具参数。
检索内容中的提示注入尝试。
长上下文和多模态场景。
提供方超时和模拟限流。
结构化输出边缘情况。
代理必须停止而不是执行的任务。

评分不应只看答案质量。还要衡量工具选择、参数有效性、任务完成度、策略合规性、延迟、token、成本以及人工升级率。

只有当模型通过其分配角色的验收阈值时，才将其提升。一个更快但会导致更多重试或工具错误的模型，在工作流层面可能成本更高。

9. 添加生产可观测性和责任归属

每一次失败的代理运行都应该能够被追踪，同时又不必不必要地暴露秘密或敏感的提示内容。

记录结构化元数据，例如：

{
  "agent_run_id": "run_…",
  "workflow": "support_resolution",
  "step": "tool_worker",
  "model_policy_version": "2026-07-27",
  "model": "APPROVED_GEMINI_MODEL",
  "route": "primary",
  "attempt": 1,
  "status": "success",
  "latency_ms": 0,
  "input_tokens": 0,
  "output_tokens": 0,
  "estimated_cost_usd": 0
}

为端点、凭证、模型策略、提示词、工具权限、预算和事件响应分配负责人。没有责任归属，仪表板就会变成问题记录，而不是控制系统。