工程化工作流部署：让工作流服务也能灰度和回滚

一、Agent 上线后，行为版本比镜像版本更复杂

AI Agent 从 demo 走到生产环境后，会遇到和普通服务一样的问题：版本发布、配置变更、权限控制、监控告警、灰度回滚。但 Agent 又更复杂，因为它的行为不仅取决于代码，还取决于模型版本、提示词、工具权限和外部知识库。只部署一个容器，远远不够。

一个 Agent 服务应把运行时拆开管理。代码镜像决定业务逻辑，Prompt 版本决定推理风格，工具配置决定可执行动作，知识库索引决定上下文范围，模型网关决定调用哪个模型。任何一部分变更，都可能改变最终输出。生产部署必须能记录这些版本组合。

二、版本组合架构：代码、Prompt、模型和工具要一起追踪

flowchart TD
    A[Agent 服务] --> B[代码镜像]
    A --> C[Prompt 版本]
    A --> D[工具权限]
    A --> E[知识库索引]
    A --> F[模型网关]
    B --> G[灰度发布]
    C --> G
    D --> G
    E --> G
    F --> G

灰度策略不能只看 HTTP 200。Agent 输出可能格式正确但业务错误，例如误创建任务、引用过期知识、调用了不该调用的工具。灰度期间要采集任务成功率、人工修改率、工具失败率、拒答率和用户反馈。对于高风险动作，灰度版本应先进入“建议模式”，由人工确认后再执行。

三、执行上下文实现：每次任务都带版本指纹

下面是一个版本记录结构示例。每次执行任务时都带上这些元信息，方便回放和排障。

def build_agent_context(request, versions):
    required = ["image", "prompt", "model", "tool_policy", "index"]
    for key in required:
        if key not in versions:
            raise ValueError(f"missing version: {key}")
    return {
        "request_id": request["id"],
        "tenant": request["tenant"],
        "versions": versions,
        "mode": request.get("mode", "suggestion"),
    }

四、灰度与观测：Agent 成功不是 HTTP 成功

Kubernetes 部署 Agent 服务时，可以用 Deployment 管理代码版本，用 ConfigMap 或配置中心管理 Prompt，用 Secret 管理凭据，用模型网关控制模型路由。注意 Prompt 不应随意在线修改后立即影响所有请求，最好也走版本发布和回滚流程。否则线上行为变化无法追踪。

可观测性要覆盖推理链路。传统服务关注 QPS、延迟、错误率；Agent 还要关注 token 消耗、工具调用次数、上下文长度、输出解析失败和安全拦截。成本监控尤其重要，一个循环调用工具的错误可能迅速烧掉预算。

回滚也要分层。代码可以回滚镜像，Prompt 可以回滚模板版本，知识库可以回滚索引，工具权限可以回滚策略。只有把这些版本拆开，故障时才不会被迫整体回退，影响无关能力。

生产落地补充：从能跑到可维护

从生产落地角度看，这类方案不能只停留在主流程。更关键的是把输入校验、失败分支、资源上限和回滚路径提前写清楚。主流程通常容易在演示环境里跑通，真正暴露问题的是异常输入、依赖抖动、并发放大和权限边界。一篇技术方案如果没有解释这些约束，读者很难判断它能否放进真实系统。

评估时建议先定义三类指标：正确性指标、稳定性指标和成本指标。正确性指标回答结果是否可信，稳定性指标回答失败时是否可控，成本指标回答持续运行是否划算。三类指标要同时进入验收清单，不能只用平均耗时或单次成功率证明方案有效。

实现层面还需要把观测数据留出来。日志至少包含请求标识、关键参数摘要、耗时、状态和错误类型；指标至少覆盖成功率、超时率、重试次数和队列长度；必要时再补 Trace 关联上下游调用。这样排查问题时不用靠猜，也能区分是代码逻辑、外部依赖还是容量配置导致的故障。

测试策略也要覆盖边界条件。除了正常样例，还要准备空输入、超大输入、重复请求、依赖超时、权限不足和部分成功等用例。涉及并发时，应补充压力测试和资源泄漏检查；涉及数据处理时，应补充幂等校验和结果一致性校验。测试不是装饰，而是保证后续重构仍然可信的依据。

五、总结

AI Agent 云原生部署要把代码、Prompt、模型、工具权限和知识库版本统一纳入发布体系。只有支持灰度、回滚、回放和成本观测，智能体服务才能从演示走向稳定生产。