Agent工程化落地：轻量级AgentOps方法论与实践

ama7449

394人浏览 · 2026-06-24 09:24:26

ama7449 · 2026-06-24 09:24:26 发布

1. 项目概述：这不是又一个LLM封装工具，而是一套面向工程落地的Agent构建方法论

我干了十多年后端、数据平台和AI基础设施，从最早手写Flask API、搭Airflow DAG，到后来搞模型服务化、做MLOps流水线，踩过的坑比写的代码还多。最近半年，我带着一个小团队在真实业务场景里落地Agent——不是PoC，不是Demo，是每天处理几百单客户支持请求、自动执行退款审批、实时调用知识库生成工单摘要的生产级系统。过程中最深的体会是： 把Agent当成“带大模型的API”来设计，等于给自己埋下一颗定时炸弹 。它不光会返回错误，更可能在你没注意的时候悄悄发错邮件、误退全款、把PII数据打到日志里，或者因为一次prompt微调，让原本95%准确率的工单分类突然掉到60%，而监控告警纹丝不动。

这篇内容讲的，就是我们从零开始搭建AgentCrewOps Lite这套轻量级Agent运维体系的真实过程。它不追求炫技，不堆砌框架，核心就一件事： 让小团队（2~5人）能像发布一个REST API一样，安全、可观察、可评估地交付Agent服务 。关键词很明确： Agent、Builder、Goals、Gotchas、Practical Stack ——全是工程师视角下的硬核问题：目标怎么定？哪些坑最容易被忽略？第一版技术栈到底该选什么、为什么这么选？没有Kubernetes，没有自建向量库，没有复杂编排引擎，只用一个容器、几个托管服务，就能跑起来。它适合已经上线过API、做过ETL流程、甚至跑过简单ML模型的工程师，但不适合想找现成MLOps平台开箱即用的人，也不适合想直接上LangChain+AutoGen全家桶却没想清楚“谁来负责线上质量”的团队。本质上，这是SRE思维在Agent领域的迁移：把“成功率”“P95延迟”“每成功任务成本”这些指标，从API监控面板里搬进Agent的决策链路中；把“变更前必须跑回归测试”这个常识，扩展成“每次prompt修改都必须跑10次采样看分布变化”。接下来所有内容，都是我们一行行代码、一次次部署、一个个告警背后的真实选择和计算依据。

2. 核心设计思路拆解：为什么放弃“大而全”，选择“小而精”的AgentOps路径

2.1 Agent的本质不是API，而是有状态、有成本、会漂移的程序

很多团队第一次做Agent，习惯性地把它当做一个“更聪明的API”来设计。输入一个用户问题，输出一段JSON或文本，中间调用几个工具。这种思路在Demo阶段很顺，但一上生产就崩。根本原因在于，Agent和传统API存在三个不可忽视的底层差异：

第一， 它是有状态的循环程序，不是无状态的函数调用 。一个典型的Agent执行流是：接收目标 → 分析上下文 → 决策下一步动作 → 调用工具（搜索/数据库/API）→ 解析结果 → 判断是否完成 → 若未完成则回到决策环节。这个循环可能执行3步，也可能执行15步，每一步都依赖上一步的输出。这意味着它的执行路径是动态生成的，无法像REST API那样用OpenAPI文档穷举所有可能的输入输出组合。我们曾遇到一个工单分类Agent，在处理“重置密码”类请求时，80%的概率走“KB搜索→生成摘要→关闭工单”路径，20%的概率因KB返回空结果，触发“创建新工单→人工介入”分支。如果只测单次，永远发现不了这20%的隐性路径。

第二， 它的副作用是真实且昂贵的 。API调用失败，最多返回500错误；Agent调用工具失败，可能意味着一封本不该发的客服邮件已送达客户邮箱，一笔本不该退的15美元已打入用户账户。更关键的是，这些操作都有真金白银的成本：一次GPT-4调用按token计费，一次外部API调用按请求计费，一次数据库写入按IO计费。我们上线初期没设预算上限，结果某天凌晨因一个prompt bug导致Agent陷入无限重试循环，3小时内烧掉$237，而监控只显示“API延迟升高”，没人意识到是成本在飙升。

第三， 它的质量是概率分布，不是确定布尔值 。传统API测试，一个输入对应一个预期输出，“通过/失败”二元判定足够。Agent不行。同一个用户问题“帮我查订单#123的状态”，在不同时间、不同模型温度、不同工具返回结果下，可能生成“已发货”“正在分拣”“系统异常，请稍后再试”三种答案。我们实测过，对同一组100个测试用例，用temperature=0.0跑10次，平均成功率92%；用temperature=0.4跑10次，平均成功率降到85%，但P95延迟下降了37%。如果只跑一次，你会认为0.4版本“性能更好”，而忽略它带来的质量损失。这就是“漂移”（Drift）——不是突然崩溃，而是缓慢、隐蔽、累积性的质量退化。

提示：判断你的Agent是否已进入生产风险区，就看这三个问题：1）有没有记录每一次执行的完整决策链路（而非仅最终输出）？2）有没有为每一次工具调用设置成本预算和审批机制？3）有没有对每个核心用例进行N次采样测试，观察成功率分布而非单点结果？

2.2 AgentOps不是新概念，而是SRE在Agent时代的必然延伸

既然Agent是新型程序，那它的运维（Ops）自然不能照搬API那一套。我们把AgentOps的核心诉求，拆解成四个必须解决的维度，每个维度都对应着传统API运维的升级：

可观测性（Observability）升级 ：API监控看“请求量/错误率/延迟”，AgentOps必须看“决策链路/工具调用序列/每步耗时/重试次数”。我们曾定位一个退款失败问题，传统日志只显示“退款接口返回500”，而OpenTelemetry追踪显示：Agent先调用billing.refund工具，工具返回“余额不足”，Agent未正确处理该错误码，反而尝试再次调用，触发风控拦截。没有span级别的trace，这个问题会一直被归因为“第三方API不稳定”。
质量保障（Quality Assurance）升级 ：API测试跑Postman脚本，AgentOps必须跑“N样本评估（N-sample evals）”。我们定义了一个基础评估套件（suite），包含20个高频工单场景，每个场景强制运行N=10次。评估不只看“是否成功”，更看成功率分布、P95延迟分布、成本分布。当某次PR合并后，“重置密码”用例的成功率从92%±3%（CI基线）跌到85%±8%，虽然单次测试仍可能“通过”，但统计检验（bootstrap置信区间）明确提示“漂移发生”，CI直接阻断发布。
安全治理（Safety Governance）升级 ：API关注认证鉴权，AgentOps必须管“工具权限/PII脱敏/支出审批”。我们的policy.yaml里明确规定：kb.search工具默认只读，billing.refund工具任何调用都需人工审批，所有日志和trace在落盘前必须擦除email和phone字段。这避免了“Agent自动退款”变成“Agent自动批量退款”的灾难。
发布流程（Release Process）升级 ：API发布是“打包→部署→验证”，AgentOps必须是“Spec/Prompt变更→N样本评估→安全扫描→人工审批→灰度发布”。我们用GitHub Actions实现：PR提交后，自动触发10次采样评估，生成HTML报告（含trace链接、输入输出对比、与基线差异），只有报告达标且PR被指定Reviewer批准，才能合并。这堵住了“改一行prompt就上线”的高危路径。

这套思路的本质，是把Agent当作一个需要持续治理的“数字员工”，而不是一个可以甩给LLM厂商托管的黑盒服务。它的设计哲学很朴素： 用最小的抽象，覆盖最大的风险面 。不追求理论完美，只确保每个环节都有明确的Owner、可量化的指标、可追溯的操作记录。

2.3 “Lite Stack”的选型逻辑：为什么是容器+托管服务，而不是K8s+自建组件

看到“AgentCrewOps Lite”这个名字，很多人第一反应是：“Lite？是不是功能阉割版？”恰恰相反，Lite指的是 心智负担最小、运维开销最低、启动速度最快 的生产就绪方案。我们放弃Kubernetes、自建向量库、私有模型集群，并非能力不足，而是经过严格成本效益分析后的主动选择。以下是每个关键组件的选型推演：

容器（Container）替代K8s ：
我们评估过K8s的收益：水平扩缩容、服务网格、细粒度资源隔离。但现实是，v0.1版本Agent的QPS峰值不到5，单实例CPU使用率常年低于30%。此时引入K8s，意味着要额外维护etcd集群、配置Ingress Controller、学习Helm Chart语法、处理Pod CrashLoopBackOff故障……这些工作消耗的工程师时间，远超它带来的弹性收益。而托管容器服务（如Cloud Run、ECS Fargate）提供了几乎相同的API： docker build && docker push && gcloud run deploy 。它自动处理扩缩容（冷启动除外）、健康检查、TLS终止，且计费按实际使用毫秒级结算。我们测算过，同等负载下，托管容器的月度成本比自建K8s集群低62%，而工程师投入时间减少85%。 结论：水平扩展不是刚需，快速迭代才是生命线 。

托管Postgres替代自建DB ：
Agent的运行历史（Run表）、步骤详情（Step表）、成本记录，必须持久化且强一致。有人提议用MongoDB存JSON日志，但我们坚持用关系型数据库。原因有三：1）Run和Step之间是严格的1:N关系，SQL JOIN比嵌套JSON查询更可靠；2）成本统计需要SUM/GROUP BY等聚合，Postgres的窗口函数和物化视图比NoSQL的MapReduce更高效；3）最重要的是，托管Postgres（如Cloud SQL、RDS）提供开箱即用的备份、点恢复、读副本、慢查询日志，而自建MongoDB集群的备份策略、一致性校验、故障切换，都是需要专职DBA的重活。我们用Postgres的JSONB字段存储非结构化数据（如工具返回的原始JSON），既保留了灵活性，又不失关系型数据库的可靠性。

对象存储（Object Storage）替代文件系统 ：
Agent执行中产生的大量中间产物——原始prompt、LLM返回的完整response、工具调用的输入输出快照、HTML评估报告——体积大、访问频次低、需长期保存。用本地磁盘或NFS，会带来单点故障、容量瓶颈、跨实例同步难题。而S3/GCS这类对象存储，天然具备高可用、无限扩展、按需付费、版本控制特性。我们约定：每个Run生成唯一artifact_uri，格式为 s3://my-bucket/artifacts/{run_id}/prompt.json ，所有服务（Agent服务、Eval服务、UI）通过这个URI访问，彻底解耦存储与计算。实测上传一个10MB的prompt-response包，S3平均耗时320ms，比挂载NFS卷（平均850ms）快得多，且无需担心磁盘爆满。

托管APM（Application Performance Management）替代自建OTel Collector ：
OpenTelemetry是Agent可观测性的基石，但OTel Collector本身是个需要运维的组件。它要处理采样策略、后端路由、TLS加密、高可用部署。而托管APM（如Datadog APM、Grafana Cloud Tempo）只需在应用中注入OTel SDK，配置一个exporter endpoint和API Key，所有trace ingestion、存储、查询、告警都由服务商托管。我们对比过：自建OTel Collector集群，每月需投入1.5人日维护（升级、扩容、故障排查）；托管方案零维护，且提供开箱即用的“Trace Heatmap”“Span Dependency Graph”等高级分析能力。 关键决策点：OTel SDK必须自己集成（保证span命名规范），但Collector必须外包 。

这套Lite Stack的终极目标，是让团队在 第一天就能跑通端到端流程 ：写好agent.yaml和policy.yaml → 构建容器镜像 → 推送到仓库 → 部署到托管容器 → 发起一个HTTP请求 → 在APM后台看到完整的trace → 在Postgres里查到Run记录 → 在S3里找到artifact。所有环节，没有一个需要等待“基础设施团队排期”。

3. 核心细节解析与实操要点：从spec/policy定义到N样本评估的落地细节

3.1 agent.yaml：用声明式语法定义Agent行为，而非写Python逻辑

agent.yaml不是配置文件，而是Agent的“行为契约”。它用YAML的简洁语法，强制约束了Agent的三个核心维度：模型能力、工具权限、执行边界。我们摒弃了在代码里硬编码model_name、tool_list的做法，因为那会导致“代码即配置”的混乱——修改一个prompt要改Python，调整一个工具权限又要改Python，版本管理一团糟。以下是我们的标准模板及每个字段的实操含义：

# agent.yaml
agent:
  name: "support-triage"          # Agent唯一标识，用于日志、监控、权限控制
  model: "openai:gpt-4.1-mini"    # 模型标识符，格式为"{provider}:{model_name}"
  temperature: [0.0, 0.4]         # 温度范围，非单值！表示允许的随机性区间
  max_steps: 8                    # 最大循环步数，防死循环，硬性熔断
  tools:
    - name: "kb.search"           # 工具名，必须与注册的Tool Class名一致
      allow: ["read"]             # 权限列表，"read"表示只读，"create/update/delete"需审批
    - name: "billing.refund"
      allow: ["create"]
      approval:                   # 高风险工具的审批规则
        required: true            # 是否强制人工审批
        timeout_hours: 2          # 审批超时时间，超时自动拒绝

为什么temperature是数组而非单值？
这是对抗“随机性漂移”的关键设计。LLM的temperature参数控制输出的随机程度。设为0.0，输出最确定；设为0.8，输出最发散。如果只允许单值（如 temperature: 0.2 ），那么一次PR修改可能把0.2改成0.3，看似微小，但实测可能导致“工单分类”用例成功率从95%跌到82%。而定义为区间 [0.0, 0.4] ，意味着Agent在运行时会从该区间内随机采样一个值（如0.17、0.33），这样既能保持一定多样性（应对模糊查询），又能将随机性框定在可控范围内。我们在eval阶段，会对每个用例在该区间内均匀采样10个temperature值各跑1次，确保评估覆盖整个随机谱系。

max_steps的熔断逻辑如何实现？
这不是简单的for循环计数。我们在Agent主循环中嵌入了两层保护：

应用层熔断 ：每执行一步，检查当前step_index是否>=max_steps，若是，则强制终止循环，返回“执行超时”错误。
基础设施层熔断 ：托管容器服务（如Cloud Run）本身支持 --timeout 参数（如 --timeout=300 秒）。当Agent卡在某一步超过5分钟，容器进程会被OS SIGKILL，避免资源被长期占用。两者结合，确保万无一失。

tools.allow的权限模型为何如此设计？
我们采用“最小权限原则”的渐进式授权：

所有工具默认只读（ allow: ["read"] ），如kb.search、db.query。
任何可能改变状态或产生费用的工具（ billing.refund , email.send ），必须显式声明 allow: ["create"] 并配置 approval 。
approval.required: true 触发一个异步工作流：Agent暂停执行，向Slack指定频道发送审批请求（含Run ID、输入、拟执行操作），等待指定角色（如Support Lead）在Web UI或Slack按钮上点击“Approve”或“Reject”。审批结果通过消息队列（如Pub/Sub）通知Agent继续。

注意： approval.timeout_hours 是硬性要求。我们曾因设置为0（永不超时），导致一个退款审批卡住3天，阻塞了整个Agent队列。现在所有审批都带倒计时，超时自动拒绝并告警。

3.2 policy.yaml：运行时的“数字宪法”，守护安全与成本底线

如果说agent.yaml定义了Agent“能做什么”，policy.yaml则定义了它“必须遵守什么”。它是Agent运行时的强制性守则，由Policy Engine在每次执行前加载并校验。我们的policy.yaml聚焦三个不可妥协的领域：数据安全、输出契约、财务管控。

# policy.yaml
policy:
  pii_redaction: ["email", "phone"]     # PII字段列表，自动从所有日志、trace、artifact中擦除
  output_contract:                      # 输出格式契约，确保下游系统可解析
    type: "json"
    schema_ref: "schemas/triage.json"   # JSON Schema文件路径，存于对象存储
  spend:
    per_run_usd_max: 0.25               # 单次执行最大花费，单位美元
    per_day_usd_max: 30                 # 每日总花费上限，单位美元
  domains_allowlist: ["*.your-company.com"]  # 外部API调用白名单，防止Agent调用恶意域名

PII脱敏的实操陷阱与绕过方案 ：
pii_redaction 看似简单，但实操中极易出错。常见误区是只在日志打印前做正则替换，而忽略了：1）OpenTelemetry trace中的 attributes 字段可能包含原始email；2）S3 artifact里的prompt.json可能明文存储用户输入；3）Postgres Run表的 input 字段可能存有PII。我们的解决方案是“源头净化”：在Agent接收到HTTP请求后，第一件事就是调用 redact_pii(input) 函数，对整个输入JSON做深度遍历，将匹配 email / phone 模式的值替换为 [REDACTED_EMAIL] / [REDACTED_PHONE] ，并将净化后的input传入后续所有环节。同时，Policy Engine在写Run记录、emit trace、save artifact前，再次校验所有数据结构，双重保险。 实测心得：不要相信任何“事后脱敏”，必须在数据进入系统的第一毫秒就净化 。

output_contract的校验时机与失败处理 ：
output_contract 不是装饰性字段，而是强制校验点。Policy Engine在Agent完成所有步骤、准备返回最终输出前，会：1）解析输出为JSON；2）加载 schemas/triage.json （一个标准JSON Schema文件）；3）用 jsonschema.validate() 校验。若校验失败，Agent不返回错误，而是触发 agent.critic 步骤：调用LLM，用自然语言提示“你的输出不符合schema，请重试”，并附上schema定义。这比直接抛500错误更符合Agent的自治理念。我们曾因schema缺失 status 字段，导致Agent反复重试12次才成功，而 per_run_usd_max 限制让它在第8次就因超支被熔断。现在，schema定义和Agent逻辑必须同步更新，CI流水线会校验二者一致性。

spend限额的精确计量与熔断 ：
per_run_usd_max 的计量绝非粗略估算。我们在每个 tool.call span结束时，从工具响应头（如OpenAI的 x-ratelimit-remaining-tokens ）或响应体中提取本次调用的精确token数，乘以该模型的实时单价（从Provider API获取），累加到 run_cost 变量。当 run_cost > per_run_usd_max ，Policy Engine立即中断执行，返回 {"error": "cost_exceeded", "budget": 0.25, "spent": 0.27} 。 per_day_usd_max 则通过Postgres的 daily_spend 物化视图实时计算，每日0点重置。 关键技巧：成本计量必须与工具调用原子绑定，不能靠事后汇总，否则熔断就失去意义 。

3.3 N样本评估（N-sample evals）：用统计思维取代“单点测试”的质量观

这是AgentOps区别于传统API测试的最核心实践。我们彻底抛弃了“一个输入，一个预期输出，跑一次看是否相等”的测试范式，代之以“一个输入，N次执行，看成功率分布”的统计范式。以下是我们的评估框架设计与落地细节：

评估套件（Suite）的构建原则 ：

真实性优先 ：20个用例全部来自过去30天真实工单日志，经脱敏处理。例如 refund_15_small 用例，输入是“please refund $15 for order #123”，oracle（黄金标准）是“amount==15 and contains('refund processed')”。
覆盖关键路径 ：包含4类场景：1）高频简单任务（重置密码）；2）多跳复杂任务（查订单→查物流→生成摘要）；3）边界模糊任务（“我的东西怎么还没到？”需结合时效规则判断）；4）高风险任务（退款、发邮件）。
可自动化执行 ：每个用例的 evaluator 字段定义校验逻辑，支持 json_schema 、 string_match 、 regex 、 custom_python 四种类型，全部可编程实现。

N=10的科学依据与动态调整 ：
为什么是10？我们做了蒙特卡洛模拟：对一个理论成功率p=0.9的用例，运行N次，计算成功率的95%置信区间宽度。当N=5时，区间宽达±0.25（0.65~0.90），无法区分p=0.9和p=0.75；当N=10时，区间宽收窄至±0.12（0.78~0.90），能较可靠检测出10%以上的漂移；当N=30时，区间宽±0.07，但执行时间增加3倍。 结论：N=10是精度与效率的最佳平衡点 。对于高风险用例（如退款），我们会在CI中动态提升N=30；对于低风险用例（如KB搜索），N=5即可。

评估报告（HTML Report）的关键信息 ：
每次评估生成一个独立HTML文件，存于S3，链接嵌入CI评论。报告包含：

概览页 ：总用例数、通过率、P95延迟、平均成本，与基线（baseline）的差值。
用例详情页 ：每个用例的10次执行记录，每条记录含：输入、输出、是否通过、耗时、成本、trace链接。
差异分析 ：用红色高亮显示与基线相比，成功率下降>5%、P95延迟上升>20%、成本上升>15%的用例。
trace快照 ：嵌入关键trace的简化视图（只显示 agent.plan → tool.call → tool.result → agent.critic 链路），无需跳转APM后台。

实操心得：评估报告必须“一眼可读”。我们曾用纯文本报告，工程师要手动打开10个trace链接比对，平均耗时22分钟。改为HTML报告后，5分钟内即可定位问题。 好的评估报告，应该让一个实习生也能看出哪里坏了 。

3.4 可观测性基线：从span命名到关键指标的工程化落地

Agent的可观测性，不是堆砌监控图表，而是建立一套能精准映射到决策链路的指标体系。我们基于OpenTelemetry，定义了4个核心span和5个关键指标，全部在代码中硬编码，确保跨团队、跨服务的一致性。

核心span命名规范（必须严格遵守） ：

agent.plan ：Agent接收输入后，生成第一个行动计划（如“调用kb.search查询重置密码流程”）的时刻。span的 attributes 包含 agent.name 、 input_hash 。
tool.call ：Agent决定调用工具时。 attributes 包含 tool.name 、 tool.method （如 search ）、 input_truncated （前100字符）。
tool.result ：工具返回结果后。 attributes 包含 tool.status （success/error）、 latency_ms 、 output_truncated 。
agent.critic ：Agent评估工具结果并决定下一步（继续/重试/终止）的时刻。 attributes 包含 decision （continue/retry/terminate）、 retry_count 。

为什么span命名如此重要？
因为所有后续的指标聚合、告警规则、trace分析，都依赖这些标准化的名称。例如，要计算“kb.search工具的平均成功率”，APM后台只需写查询： count() by (tool.name) (rate(tool_call_status{tool_name="kb.search", status="success"}[1h])) 。如果有人随意命名为 kb_search_invoke ，这个查询就失效了。我们强制在CI中加入span名称校验：扫描所有Python文件，确保只出现上述4个名称，否则PR被拒绝。

5个必须追踪的关键指标 ：

指标名	类型	计算方式	用途
`agent_task_success_total`	Counter	每次 `agent.critic` 决策为 `terminate` 且 `status=success` 时+1	衡量整体成功率
`agent_task_latency_seconds`	Histogram	从 `agent.plan` 开始到 `agent.critic` 结束的耗时	监控P95延迟
`agent_tokens_total`	Counter	累加每次 `tool.call` 返回的token数	成本核算基础
`agent_cost_usd_total`	Counter	累加每次 `tool.call` 的实时花费	直接财务监控
`$ per successful task`	Gauge	`agent_cost_usd_total / agent_task_success_total`	成本效率核心指标

告警阈值的设定逻辑 ：
我们不设固定阈值，而是基于历史基线动态计算。例如， $ per successful task 的告警规则是： current_value > baseline_mean * 1.3 AND current_value > baseline_p95 * 1.1 。这意味着，只有当成本同时显著高于均值（+30%）和高于日常波动上限（+10%）时，才触发告警。这避免了因单次高成本任务（如长上下文处理）引发的误报。Slack告警消息包含：超标幅度、关联Run ID、trace链接、最近3次同用例成本对比。 经验：告警不是越多越好，而是要让每次告警都指向一个可行动的根因 。

4. 实操过程与核心环节实现：从本地开发到CI/CD流水线的完整闭环

4.1 本地开发环境：FastAPI + Docker Compose，5分钟启动全链路

本地开发的目标是： 让工程师在写第一行Agent逻辑前，就能看到完整的trace、Run记录、artifact 。我们摒弃了“先写代码，再配监控”的老路，采用“监控先行”策略。以下是 docker-compose.yml 的核心片段：

version: '3.8'
services:
  app:
    build: .
    ports: ["8000:8000"]
    environment:
      - POSTGRES_HOST=postgres
      - S3_ENDPOINT=http://minio:9000
      - OTLP_ENDPOINT=http://tempo:4317
    depends_on: [postgres, minio, tempo]
  postgres:
    image: postgres:15
    environment: [POSTGRES_PASSWORD=dev]
  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment: [MINIO_ROOT_USER=minio, MINIO_ROOT_PASSWORD=miniostorage]
  tempo:
    image: grafana/tempo:latest
    command: [ "-config.file=/etc/tempo.yaml" ]

关键配置说明 ：

app 服务构建自 Dockerfile ，其中预装了 opentelemetry-instrument 和 opentelemetry-exporter-otlp ，启动时自动注入OTel SDK。
tempo 是轻量级trace后端， minio 是本地S3兼容对象存储， postgres 是本地数据库。所有服务通过Docker网络互通。
启动命令： docker compose up -d ，30秒内全部就绪。

本地调试的黄金组合 ：

CLI快速触发 ： curl -X POST http://localhost:8000/run -d '{"input":"reset password","agent":"support-triage"}'
实时查看trace ：打开 http://localhost:16686 （Jaeger UI），搜索 agent.name=support-triage ，看到完整4步span链路。
验证Run记录 ： docker exec -it app-db psql -U postgres -c "SELECT * FROM runs ORDER BY start_ts DESC LIMIT 1;"
检查artifact ： mc alias set myminio http://localhost:9000 minio miniostorage ，然后 mc ls myminio/my-bucket/artifacts/ 。

实操心得：本地环境必须“所见即所得”。我们曾因OTel exporter配置错误，导致本地trace正常而CI环境丢失，花了3天排查。现在，CI的OTel配置与本地完全一致，只是endpoint指向托管APM。 本地能跑通的trace，CI里必然能看见 。

4.2 CI/CD流水线：GitHub Actions驱动的“评估-安全-发布”铁闸

我们的CI/CD不是简单的“build-test-deploy”，而是一个多阶段质量门禁（Quality Gate）系统。每个PR必须通过三道关卡，缺一不可。以下是 .github/workflows/ci.yml 的核心逻辑：

name: AgentCrewOps CI
on: [pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build Container
        run: docker build -t ${{ secrets.REGISTRY }}/agent:${{ github.sha }} .

  eval:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run N=10 Eval Suite
        run: |
          docker run --rm \
            -e POSTGRES_HOST=... \
            -e S3_ENDPOINT=... \
            ${{ secrets.REGISTRY }}/agent:${{ github.sha }} \
            python eval_runner.py --suite support-triage --n 10
        # 生成HTML报告，上传为workflow artifact

  security:
    needs: eval
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Safety Pack
        run: |
          # 1. Prompt Injection Scan: 用预设恶意payload测试agent.yaml
          python safety/prompt_inject.py --agent-yaml agent.yaml
          # 2. Output Handling Check: 验证policy.yaml的output_contract是否有效
          python safety/output_contract.py --policy policy.yaml
          # 3. PII Redaction Test: 用含email/phone的输入，验证输出是否脱敏
          python safety/pii_test.py --input '{"email":"test@example.com"}'

  deploy:
    needs: [eval, security]
    if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Staging
        run: gcloud run deploy agent-staging --image ${{ secrets.REGISTRY }}/agent:${{ github.sha }}

三道关卡的不可绕过性设计 ：

Eval关卡 ：必须生成HTML报告，且报告中 success_rate 不低于基线值减去3个百分点（如基线92%，则要求≥89%）。报告作为workflow artifact永久保存，链接嵌入PR评论。
Security关卡 ：三项检查（Prompt Injection、Output Contract、PII Test）全部必须通过。任何一项失败，PR被标记为 security-failed ，禁止合并。
Deploy关卡 ：仅在PR被明确标记为 ready-for-deploy 且由指定Reviewer批准后才触发。部署命令 gcloud run deploy 后，自动触发一次 canary 评估（N=5），验证staging环境是否健康。

Canary评估的巧妙设计 ：
Canary不是全量评估，而是轻量级健康检查。它只运行3个最高频用例（重置密码、查订单、KB搜索），各跑N=5次。如果全部通过，视为staging健康；若有任一失败，则自动回滚上一版本，并告警。这比全量评估快5倍，且足以捕获90%的严重回归。 经验：Canary不是为了发现所有问题，而是为了阻止明显有毒的版本上线 。

4.3 生产部署架构：云原生托管服务的最小可行组合

生产环境不是本地环境的简单放大，而是针对可靠性、安全、合规的加固。我们采用GCP Cloud Run作为核心，因为它完美契合“无服务器容器”的需求。以下是生产架构的逐层解析：

第一层：API网关（WAF）

使用Cloud Armor（GCP WAF）作为入口。配置：TLS 1.3强制、JWT认证（验证用户身份）、速率限制（100 req/min per IP）、IP黑名单。
关键作用： 剥离所有与Agent无关的流量治理 。WAF处理认证、限流、DDoS防护，Agent服务只专注业务逻辑。

第二层：AgentCrewOps Lite Service

部署在Cloud Run，配置：最小实例=0（节省冷启动成本）、最大实例=10（应对突发流量）、内存=2GB、CPU=1。
环境变量： POSTGRES_HOST=cloudsql-instance , S3_ENDPOINT=storage.googleapis.com , OTLP_ENDPOINT=datadoghq.com:443 。
关键加固：启用VPC Connector，所有出站流量（Egress）必须经过VPC，再经NAT Gateway或Private Google Access访问外部API。

**第三

亚马逊云科技技术品牌专区

更多推荐