中文译本。原文见同目录 README.md

第 11 课：从原型到生产 - 交付你的 Agent

引言

你已经做出一个能跑的 Agent。它能过测试用例，演示时让团队眼前一亮，感觉像魔法。现在你需要把它交给真实用户。难关从这里开始。

从「在我笔记本上能跑」到「对成千上万用户可靠运行」之间的鸿沟非常大。在传统软件里，生产就绪主要意味着处理边界情况、扩缩容和监控。对 Agent 而言，这些全都要，外加一个根本挑战：系统行为是非确定性的，很难完全预测。

ELI5：把 Agent 上生产，就像开餐馆

你一直在家给朋友做很棒的饭，大家都很爱吃。现在你想开餐馆。突然你要考虑家里从不重要的事：卫生检查、供应链、保证每道菜味道一致的标准配方、培训员工、处理投诉、管成本，以及确保繁忙周六晚上厨房不会着火。厨艺本身没变，但周围的一切完全不同了。

这就是原型到生产的鸿沟。Agent 的核心逻辑可能变化不大，但周围的一切——评估、部署、监控、成本管理、团队流程——都需要从零建起。

核心要点： 从原型到生产的「最后一公里」往往占全部工作量的 80%。从一开始就要为此做规划。

生产鸿沟

从原型走向生产时，变化包括：

维度 原型 生产
用户 你和你的团队 成百上千真实用户
输入 精心挑选的测试用例 任何人键入的任何内容，包括对抗性输入
可用性 坏了就重启 必须 7×24 可用，并有优雅降级
延迟 「几秒也没关系」 简单查询用户期望亚秒级响应
成本 烧钱速度无所谓 规模下每个 token 都花钱
质量 「通常能用」可接受 要求稳定质量；差回复会侵蚀信任
安全 非正式测试 系统化护栏、监控与事件响应
调试 print 语句 结构化日志、追踪与指标
更新 改完重启 带评估门控的 CI/CD 流水线

为什么演示会骗人

演示有效，是因为演示的人知道哪些输入效果好。他们避开边界情况。失败在镜头外重试。从多次运行中挑最好的例子。

生产恰好相反。真实用户会：

  • 拼错字、用俚语、用不预期的语言写
  • 问 Agent 从未设计去处理的问题
  • 提供极长或极短的输入
  • 对结果不满意时反复问完全相同的问题
  • 发现你从未想象过的失败模式

这就是为何评估门控部署如此重要。未经针对全面真实场景测试的 Agent 版本，不应上线。

团队角色：谁参与

把 Agent 产品化不是一个人的事。通常涉及多个角色协作：

角色 职责
AI Engineer Agent 逻辑、提示词设计、工具集成、eval 创建
Platform Engineer 基础设施、部署流水线、服务网格、扩缩容
Data Engineer RAG 数据流水线、知识库、训练数据管理
ML Ops / AI Ops 模型服务、版本管理、A/B 测试、监控看板
DevOps / SRE 可靠性、事件响应、告警、成本追踪
Product Manager 用户需求、成功指标、优先级
Security / Trust & Safety 护栏、红队、合规、安全评审

小团队里一个人可能身兼多职。但无论多少人分担，这些职责都仍然存在。

评估门控部署（Evaluation-Gated Deployment）

这是安全交付 Agent 最重要的实践。原则很简单：任何 Agent 版本未通过 eval 不得上线。

第 9 课讲了如何构建 eval。它们如何嵌入部署流程如下：

Code Change --> Evals Pass? --No--> Fix and retry
                    |
                   Yes
                    |
                    v
              Deploy to staging
                    |
                    v
            Staging evals pass? --No--> Fix and retry
                    |
                   Yes
                    |
                    v
            Deploy to production (canary)
                    |
                    v
          Production metrics OK? --No--> Rollback
                    |
                   Yes
                    |
                    v
            Full production rollout

好的评估门控包含什么？

用于部署的 eval 套件应覆盖：

类别 测什么 通过标准
功能正确性 Agent 是否给出正确答案？ 准确率指标 ≥ 阈值
工具使用 Agent 是否用正确参数调用正确工具？ ≥ X% 的用例工具调用正确
安全 Agent 是否抵抗提示注入并遵循策略？ 安全关键用例 100% 通过
延迟 Agent 是否在可接受时间内响应？ P95 延迟 < 目标
成本 Agent 是否落在 token 预算内？ 每次交互平均成本 < 预算
回归 以前通过的用例是否仍通过？ 已知良好用例无回归

安全 eval 应是硬门控——任一失败即阻断部署。其他类别可以有更软的阈值：若整体质量提升，可接受小幅回归。

Deployment Pipeline Simulator
Simulate a commit flowing through CI/CD gates
Canary: Route 5% of traffic to the new version. Monitor metrics. Gradually increase to 100% if healthy.
📦
Code Commit
Push to repo
⏳
🔍
Pre-merge
Unit tests, lint, evals
~5 min
⏳
🧪
Post-merge
Integration tests, staging
~30 min
⏳
🐤
Canary
5% traffic rollout
~1 hour
⏳
🚀
Production
Full deployment
100% traffic
⏳
Click "Simulate Deploy" to watch a commit flow through the pipeline

Agent 的 CI/CD

Agent 的持续集成与持续部署遵循与传统 CI/CD 相同的原则，但有 Agent 特有步骤。可分成三个阶段来想。

阶段 1：合并前（每个 pull request）

这些检查跑得快，在合并前抓住明显问题。

# Example: Pre-merge checks
pre_merge:
  - lint:
      - Check prompt formatting and syntax
      - Validate tool definitions match schemas
      - Static analysis of agent configuration

  - unit_tests:
      - Test individual tool functions
      - Test guardrail logic
      - Test input/output parsers

  - basic_evals:
      - Run a small, fast eval set (50-100 cases)
      - Focus on regression detection
      - Target: completes in < 5 minutes

阶段 2：合并后（每次合入 main）

代码合并后，在晋级到 staging 前跑更全面的检查。

# Example: Post-merge validation
post_merge:
  - staging_deployment:
      - Deploy to staging environment
      - Verify health checks pass

  - broad_evals:
      - Run full eval suite (500-1000+ cases)
      - Include safety evals
      - Include latency and cost benchmarks
      - Target: completes in < 30 minutes

  - integration_tests:
      - Test end-to-end flows with real tool connections
      - Verify external service integrations

阶段 3：生产门控（生产部署前）

真实用户看到新版本前的最后一道检查。

# Example: Production gate
production_gate:
  - full_evals:
      - Complete eval suite including edge cases
      - Adversarial test cases
      - Cross-model consistency checks (if using multiple models)

  - safety_review:
      - Automated safety evals must pass 100%
      - Human review for significant prompt changes
      - Red team sign-off for major feature changes

  - approval:
      - Automated approval if all checks pass
      - Manual approval required if any check is marginal

在 CI/CD 中管理提示词

提示词应与代码同等对待版本控制：

  • 把提示词放在版本控制里（不要放在难以 diff 的数据库或配置服务里）
  • 在 pull request 里像审代码一样审提示词变更
  • 追踪哪个提示词版本部署到了哪个环境
  • 让回滚到先前提示词版本变得容易
prompts/
  customer_support/
    system_prompt.txt      # The main system instructions
    tool_descriptions.txt  # Tool descriptions and schemas
    safety_rules.txt       # Safety-specific instructions
    version.txt            # Current version identifier

安全发布策略

即使有全面 eval，生产仍可能出意外。安全发布策略在出问题时限制爆炸半径。

金丝雀部署（Canary）

把一小部分流量路由到新版本。在提高比例前监控问题。

Traffic ---> [Load Balancer]
                |         |
               95%       5%
                |         |
                v         v
         [Version 1]  [Version 2 - Canary]
         (current)     (new)

如何运作：

  1. 与当前版本并行部署新版本
  2. 把 5% 流量路由到新版本
  3. 监控关键指标（错误率、延迟、用户满意度、安全事件）
  4. 若在设定观察期内指标健康，再升到 25%、50%、100%
  5. 若任一指标恶化，把全部流量切回当前版本

蓝绿部署（Blue-green）

维护两套相同的生产环境。把全部流量从一套切到另一套。

Before:  Traffic --> [Blue - v1.2 ACTIVE]    [Green - idle]
During:  Traffic --> [Blue - v1.2]            [Green - v1.3 ACTIVE]

优点是切换干净，且可瞬间回滚（切回 Blue 即可）。缺点是过渡期间需要双倍基础设施。

A/B 测试

把流量分到不同 Agent 版本，在真实交互上对比表现。

版本 A 版本 B 指标 胜者
基于 GPT、冗长提示 基于 Gemini、简洁提示 任务完成率 N 次交互后对比
ReAct 模式 先规划再执行 用户满意度 N 次交互后对比
模型 A，工具重试 3 次 模型 A，工具重试 1 次 每次交互成本 N 次交互后对比

对 Agent 而言 A/B 测试特别有价值，因为你可以在真实流量上对比不同模型、提示词与架构。

功能开关（Feature flags）

用可在不重新部署的情况下切换的运行时开关控制 Agent 能力。

# Example: Feature flags for agent capabilities
if feature_flags.is_enabled("new_refund_flow", user_id=user.id):
    agent.enable_tool("process_refund_v2")
else:
    agent.enable_tool("process_refund_v1")

if feature_flags.is_enabled("extended_context_window"):
    agent.set_max_context(128000)
else:
    agent.set_max_context(32000)

功能开关让你可以逐步推出新能力、快速关掉有问题的功能，并在用户子集上做实验。

生产中的可观测性

Agent 在生产跑起来后，你需要看清它在做什么。Agent 的可观测性同样有三大支柱，与传统系统一样——但具体内容不同。

日志（Logs）

捕获 Agent 生命周期中每个重要事件的结构化日志：

{
  "timestamp": "2025-06-15T10:23:45Z",
  "session_id": "sess_abc123",
  "event": "tool_call",
  "tool": "search_knowledge_base",
  "arguments": {"query": "return policy for electronics"},
  "result_status": "success",
  "latency_ms": 234,
  "tokens_used": {"input": 1250, "output": 380}
}

应记录什么：

  • 每次 LLM 调用（模型、输入 token、输出 token、延迟）
  • 每次工具调用（工具名、参数、结果状态、延迟）
  • Agent 决策（选了哪条路径、为何）
  • 护栏触发（拦了什么、为何）
  • 升级事件
  • 会话起止及摘要指标

追踪（Traces）

追踪展示单次请求穿越 Agent 的完整旅程，包括沿途所有步骤、工具调用与决策。

[User Request] "Help me return my order"
    |
    +-- [LLM Call 1] Understand intent (150ms)
    |       Model: gemini-3.5-flash, Tokens: 800 in / 120 out
    |
    +-- [Tool Call] lookup_order(order_id="12345") (340ms)
    |       Status: success
    |
    +-- [Tool Call] check_return_eligibility(order_id="12345") (180ms)
    |       Status: success, eligible=true
    |
    +-- [LLM Call 2] Generate response (200ms)
    |       Model: gemini-3.5-flash, Tokens: 1200 in / 250 out
    |
    +-- [Output Guardrail] PII check (15ms)
    |       Status: pass
    |
    [Response] "Your order #12345 is eligible for return..."

    Total: 885ms, Cost: $0.003

OpenTelemetry 是分布式追踪的行业标准。许多 Agent 框架开箱支持 OpenTelemetry，Google Cloud 运维套件（Cloud Logging、Cloud Trace、Cloud Monitoring）也原生集成 OpenTelemetry。

指标（Metrics）

随时间聚合、告诉你 Agent 整体表现如何的数值：

指标 告诉你什么 告警阈值示例
任务完成率 Agent 成功完成用户请求的频率 降至 85% 以下
平均延迟 用户等待回复多久 P95 超过 5 秒
每次交互成本 每次对话花多少钱 平均超过 $0.10
升级率 Agent 交给人的频率 超过 20%
安全事件率 护栏被触发的频率 相对基线任何上升
工具错误率 工具调用失败频率 超过 5%
用户满意度 点赞/点踩或 CSAT 降至 4.0/5.0 以下

搭建看板

生产 Agent 看板应一眼能看清：

+-------------------------------------------------------+
|  Agent Health Dashboard                                |
+-------------------------------------------------------+
|                                                        |
|  Status: HEALTHY          Active Sessions: 1,247       |
|                                                        |
|  +-------------------+  +-------------------+          |
|  | Completion Rate   |  | Avg Latency       |          |
|  | 92.3% (+0.5%)     |  | 1.2s (-0.1s)      |          |
|  +-------------------+  +-------------------+          |
|                                                        |
|  +-------------------+  +-------------------+          |
|  | Cost / Session    |  | Escalation Rate   |          |
|  | $0.042 (-$0.003)  |  | 8.1% (+0.2%)      |          |
|  +-------------------+  +-------------------+          |
|                                                        |
|  Recent Safety Incidents: 0 (last 24h)                 |
|  Recent Errors: 12 (last 24h, 0.04% of sessions)      |
|                                                        |
+-------------------------------------------------------+

观察-行动-演进循环（Observe-Act-Evolve）

生产不是终点。它是持续改进循环的开始。

    +----------+
    | Observe  |  <-- Collect metrics, logs, traces, user feedback
    +----+-----+
         |
         v
    +----+-----+
    |   Act    |  <-- Identify issues, prioritize improvements
    +----+-----+
         |
         v
    +----+-----+
    |  Evolve  |  <-- Update prompts, tools, evals, guardrails
    +----+-----+
         |
         +-------> Back to Observe

观察（Observe）

收集 Agent 在生产中的表现数据：

  • 定量： 指标看板、生产流量上的自动 eval 结果
  • 定性： 用户反馈、工单、对话抽查
  • 对抗： 持续红队、新攻击模式检测

行动（Act）

把观察变成具体动作：

  • 某类查询总失败？加入 eval 集并改进提示词。
  • 工具错误飙升？查根因并加强错误处理。
  • 用户总被某种回复模式搞糊涂？修订 Agent 指令。
  • 发现新攻击向量？加护栏和安全 eval。

演进（Evolve）

通过评估门控的 CI/CD 流水线部署改进：

  • 更新提示词并重跑 eval
  • 添加新工具或修改现有工具
  • 扩展 eval 套件以覆盖新发现的边界情况
  • 根据观察到的威胁调整护栏
  • 若有更好选项，重训或更换模型

关键洞见是：你的 eval 套件会随时间增长。每个生产事故、每条用户投诉、每个边界情况都会变成新的 eval。这意味着每次迭代后，Agent 都更难被搞垮。

成本管理

基于 LLM 的 Agent 在规模下可能很贵。单次对话可能涉及多次 LLM 调用，每次消耗数千 token。乘以成千上万用户，成本很快累积。

模型路由（Model routing）

对每项任务使用能胜任的最便宜模型。并非每一步都需要最强模型。

User Query
    |
    v
[Router] --Simple query--> Gemini Flash-Lite ($)
    |
    +-----Medium complexity--> Gemini Flash ($$)
    |
    +-----Complex reasoning--> Gemini Pro ($$$)
任务类型 建议模型档位 理由
意图分类 Small / Flash-Lite 简单分类任务
信息检索 Medium / Flash 需要较好理解与适度生成
复杂推理 Large / Pro 多步推理、细微判断
摘要 Medium / Flash 质量与成本的良好平衡
安全检查 Small / Flash-Lite 模式匹配、分类

缓存（Caching）

对重复或相似查询缓存回复，避免多余 LLM 调用。

缓存策略 何时使用
精确匹配缓存 许多用户问同样内容的 FAQ 类查询
语义缓存 措辞不同但含义相同的查询
工具结果缓存 不常变化的工具输出（如产品目录查询）
提示词缓存 跨调用复用系统提示词的缓存前缀（Vertex AI 支持 context caching）

Token 预算

对每个会话 Agent 可消耗的 token 数设置硬上限。

# Example: Token budget enforcement
class TokenBudget:
    def __init__(self, max_tokens: int):
        self.max_tokens = max_tokens
        self.used_tokens = 0

    def can_proceed(self, estimated_tokens: int) -> bool:
        return (self.used_tokens + estimated_tokens) <= self.max_tokens

    def record_usage(self, actual_tokens: int):
        self.used_tokens += actual_tokens

# Usage
budget = TokenBudget(max_tokens=50000)  # per session

while agent.has_next_step():
    estimated = agent.estimate_next_step_tokens()
    if not budget.can_proceed(estimated):
        agent.respond("I have reached my processing limit for this session. "
                      "Let me summarize what I have found so far.")
        break
    result = agent.execute_next_step()
    budget.record_usage(result.tokens_used)

成本监控

在多个层级追踪成本：

层级 追踪什么 为何
每次请求 已用 token、模型档位、工具调用 调试昂贵的单次请求
每个会话 一次对话的总成本 设定并强制每会话预算
每个用户 用户随时间的聚合成本 识别使用模式与异常值
每个功能 特定 Agent 能力的成本 判断哪些功能划算
整体 日/周/月支出 预算规划与预测

生产就绪检查清单

向生产用户发布 Agent 前，过一遍这份清单：

可靠性

  • 已配置健康检查与存活探针
  • 依赖失败时有优雅降级（模型 API 宕机、工具不可用）
  • 对瞬时失败有指数退避重试
  • 对外部服务调用有熔断器
  • 所有 LLM 与工具调用有超时上限

部署

  • 各阶段带评估门控的 CI/CD 流水线
  • 回滚流程已测试并成文
  • 已配置金丝雀或蓝绿部署
  • 新能力有功能开关
  • 提示词版本管理与变更追踪

可观测性

  • 所有 Agent 事件有结构化日志
  • 使用 OpenTelemetry 的分布式追踪
  • 关键指标看板（完成率、延迟、成本、安全）
  • 关键阈值已配置告警
  • 值班轮换与事件响应 runbook

成本

  • 已配置模型路由（每项任务用对模型）
  • 已实现缓存策略
  • 每会话 token 预算
  • 成本监控与告警
  • 定期成本复盘与优化

安全

  • 第 10 课的护栏已实现并测试
  • 安全 eval 100% 通过
  • 已完成红队评审
  • 安全失败的事件响应计划
  • 用户反馈与问题上报渠道

关键要点

  1. 原型到生产的鸿沟真实且巨大。 从一开始就为生产关切做规划。「最后一公里」是工作的大头。

  2. 评估门控部署不可妥协。 任何 Agent 版本未通过全面 eval 套件都不应进入生产。eval 套件就是你的质量保证。

  3. Agent 的 CI/CD 有三个阶段。 合并前检查快速抓住明显问题。合并后验证跑更广的 eval。生产门控在影响真实用户前确保安全与质量。

  4. 安全发布策略限制爆炸半径。 金丝雀部署、功能开关与 A/B 测试让你在影响全体用户前发现问题。

  5. 可观测性必不可少。 看不见就改不了。从第一天就投入日志、追踪与指标。

  6. 成本管理需要主动关注。 模型路由、缓存与 token 预算可在不牺牲质量的前提下大幅降本。

  7. 生产是开始，不是结束。 Observe-Act-Evolve 循环意味着 Agent 会基于真实使用持续改进。

延伸阅读

下一课：开始使用 Vertex AI 与 ADK