实用提示：我通过谷歌发送生产级AI智能体所学到的经验

可将此文档视为《通过 Google 的 Gemini 函数调用机制部署生产级 AI 智能体：我的经验总结》中内容的面向操作人员的重构版本：清晰的阶段划分、有序的代码模块以及便于交接时参考的恢复说明。在扩大范围之前，最好将“概览”阶段视为一个可量化的基准，记录一份最佳实践案例、一个失败案例以及对应的回滚说明。应将此阶段视为输入与经过验证的输出之间的契约，为相关成果命名、明确成功标准，并杜绝默许的半完成状态。

1. 函数声明：将其视为与模型之间的 API 契约

在“1个函数声明思考阶段”，在修改代码之前需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前显示成本可避免在从演示环境切换到共享环境时出现意外费用。应将客户端构建部分与消息循环分开，这样即便更换提供方也不必重写对话状态机。

// ❌ Vague — model won’t know when to use it
{ name: ‘get_data’, description: ‘Gets data about a location.’ }

// ✅ Trigger-specific — model knows exactly when this is relevant
{
 name: ‘find_backup_spots’,
 description: ‘Finds nearby indoor/covered alternatives within walking distance ‘
 + ‘if the venue is crowded or weather turns.’,
}

{
 name: ‘calculate_transit_route’,
 description: ‘Calculates precise walking/driving/transit travel times to the venue.’,
 parameters: {
 type: ‘OBJECT’,
 properties: {}, // No parameters — dispatcher injects from context
 },
}

2. 多轮工具循环：状态机而非单次调用

在“多轮工具”阶段，修改代码之前需先明确输入参数、该步骤的负责人以及结束条件。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作员无需查看整个系统结构即可进行审计。 将客户端构建与消息处理循环分开，这样在更换提供方时无需重写对话状态机。

Turn 0: [user prompt + system instructions]
 → Model returns: functionCall { name: “tool_a”, args: {…} }

Turn 1: [user prompt, model’s functionCall, your functionResponse for tool_a]
 → Model returns: text response (synthesized from tool_a’s output)

Turn 0: [user prompt]
 → Model returns: functionCall { name: “tool_a”, args: {…} }

Turn 1: [user prompt, functionCall_a, functionResponse_a]
 → Model returns: functionCall { name: “tool_b”, args: {…} }

Turn 2: [user prompt, functionCall_a, functionResponse_a, functionCall_b, functionResponse_b]
 → Model returns: final text (synthesized from both tools)

3. 模型级联：避免依赖单一模型

对于3模型级联Don阶段，在修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 应将客户端构建逻辑与消息循环分离，这样即便更换服务提供方，也无需重写对话状态机。 对于3模型级联Don阶段，在修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。为相关输出文件命名，明确成功判定标准，杜绝无声的半完成状态。

Primary: gemini-3.5-flash-lite (fastest, cheapest, zero-thinking overhead)
Secondary: gemini-3.1-flash-lite (slightly older, same tier)
Tertiary: gemini-2.5-flash (thinking-capable, higher quality)

4. API密钥架构：代理模式

在实施4个API密钥架构阶段时，首先需明确相关规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果之外，还需记录处理时间以及令牌或查询的成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外的费用支出。 每次调用时都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务提供商错误就会被视为应用程序的故障。

解决方案：服务器端代理

在处理“解决方案A：服务器端”阶段时，首先需明确相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，以便操作人员无需查看整个系统结构即可进行审计。 每次调用时都要记录请求ID、模型ID以及响应延迟。如果没有这些记录，偶尔出现的服务端错误就会被误认为是应用程序的故障。

const res = await Promise.race([
 proxyCallable({ model: modelName, body: requestBody }),
 new Promise((_, reject) =>
 setTimeout(() => reject(new Error(‘AI proxy timeout’)), 15000)
 ),
]);

5. 上下文压缩：输入模型的内容比所使用的模型本身更重要

在处理“5个上下文压缩阶段”时，首先需明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。 每次调用时都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务错误就会被视为应用程序的缺陷。 在处理“5个上下文压缩阶段”时，首先需明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，定义成功判定标准，并杜绝无声的半完成状态。

[CONTEXT]
Category: Coffee
Date: Saturday, Aug 30, 2026
Time: 10:00 AM — 11:30 AM (90 mins)
Group Size: 4/8 participants
User Role: Attendee
Country: AU
Currency: AUD
[END CONTEXT]

6. 以离线优先为原则的智能体设计：确定性回退机制

在将“6. 以离线优先为原则的智能体设计”这一阶段视为可度量的指标时，其效果最佳。在扩大范围之前，需记录一份理想的运行示例、一个故障案例以及回滚说明。 在功能结果旁还需记录执行时间以及令牌或查询成本。提前了解这些成本信息，可避免在从演示环境过渡到共享环境时出现意外费用。 在教授循环逻辑之前，需先固定解释器及依赖项的锁定文件。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障原因。

7. generationConfig 参数调优

将第7代config调优阶段视为可测量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的运行结果、一个故障案例以及回滚说明。 应将配置置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一个位置，这样操作人员无需查看整个架构即可进行审计。 在设置循环逻辑之前，先锁定解释器及依赖项的版本。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障原因。

{
 “responseMimeType”: “application/json”,
 “temperature”: 0.4,
 “maxOutputTokens”: 600
}

{
 “temperature”: 0.7,
 “maxOutputTokens”: 700
}

8. 工具使用的系统提示工程

将8个系统提示工程阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，需记录一份理想运行案例、一个故障案例以及回滚说明。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及错误处理都属于产品功能的一部分，而非后续需要补充的内容。 在讲解循环逻辑之前，先锁定解释器及依赖项的配置文件。笔记本电脑与持续集成环境之间的配置差异是API演示中最常见的隐性故障原因。 将8个系统提示工程阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，需记录一份理想运行案例、一个故障案例以及回滚说明。 应将这一阶段视为输入与经过验证的输出之间的契约。为相关输出文件命名，明确成功标准，杜绝隐性部分完成的情况。

You have access to autonomous action tools. When users ask for rides,
ALWAYS call request_rideshare. When users ask to book a table,
ALWAYS call reserve_table. When users ask about cultural norms,
ALWAYS call get_cultural_etiquette.

NO RAW MARKDOWN HEADINGS: Never use ‘#’. Use **Bold Text** for headers.
NO ASTERISKS FOR BULLETS: Use clean unicode bullet points (• ).
CONCISE: Jump straight to the answer. No filler introductions.

9. 经验总结

在“9个经验教训”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解这些成本可以避免在从演示环境过渡到共享环境时出现意外费用。应将客户端构建与消息循环分开，这样即便更换提供方，也无需重写对话状态机。

操作检查清单

在处理操作检查清单阶段时，首先需明确合同条款：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。

应优先选择小型、可测试的单元，而非结构复杂的脚本。当某个步骤出错时，故障应能指向具体的责任模块，而非混乱的流程链。

每次调用时都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务错误就会被视为应用程序的缺陷。

保持图结构简洁且具有类型约束。嵌套的数据结构会掩盖哪个节点修改了哪个字段的信息，还会导致在流程中断后无法继续执行。

只要预算允许，就应在持续集成过程中使用测试用例来验证关键路径，而非依赖真实的付费API。

将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便运维人员无需查看整个图结构即可进行审计。

在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如注重扎实的可靠性。

关于0ead08720324的批处理说明：请将提供商密钥存放在仓库之外，设定单会话令牌上限，并将日志存储在评估用示例文件旁，以便后续模型更换时仍能保持对比性。