1. 从能跑到敢上线Agent 交付的最后一公里到底卡在哪做过 Agent 项目的人大概都有过这种体验本地 Demo 跑得飞起工具调用、多轮对话、RAG 检索全都正常演示给同事看的时候掌声一片。可真到了要往生产环境推的时候问题就全冒出来了——上线之后回答质量忽高忽低用户投诉说昨天还好好的今天怎么胡说八道出了故障翻遍日志也定位不到是哪一步工具调用挂了老板问这个版本比上个版本到底好多少你只能支支吾吾说感觉差不多。这不是个别现象。Agent 和传统后端服务最大的区别在于它的输出是非确定性的。同样一句输入模型可能给你三种不同的回答工具调用链路可能因为一次超时就走上了完全不同的分支。传统软件那套单元测试通过就能上线的逻辑在 Agent 场景下基本失效。你没法用assert output expected来验证一个 Agent 是否合格因为它的输出空间几乎是无限的。所以 Agent 上线真正卡住的不是能不能跑通而是**凭什么敢让它跑在真实用户面前**。这中间隔着的就是一套完整的上线 Checklist评测门禁决定它有没有资格上线可观测性埋点决定它上线后你能不能看懂它在干什么AgentOps 决定出了问题你能不能快速定位和回滚。这三件事缺一个你的 Agent 就是一颗定时炸弹。这篇内容适合两类人看一类是正在把 Agent 从 Demo 往生产推的开发者另一类是团队里负责 Agent 质量保障和运维的同学。我会把评测门禁怎么设计、埋点怎么埋才有用、AgentOps 平台怎么落地这三块拆开讲透每个环节都给出可运行的代码思路和我在实际项目里踩过的坑。不追求大而全的框架介绍只讲能直接抄作业的东西。2. 评测门禁给 Agent 设一道不达标就别想上线的闸2.1 为什么传统 CI 在 Agent 面前是失效的先说清楚一个认知Agent 的评测门禁不是跑一遍测试用例看通不通过而是用一批有代表性的输入去量化它的表现低于阈值就拦截。这两者的区别就像体检和验血的区别——前者只能告诉你人还活着后者才能告诉你血脂偏高要注意。传统 CI 里我们写的是断言输入 A 必须输出 B。但 Agent 的输出是概率分布你只能评估它落在可接受区间的概率。比如一个客服 Agent用户问我的订单到哪了它可能回答您的包裹预计明天送达也可能回答正在为您查询物流信息请稍等。这两句都对你没法用字符串匹配来判定。所以评测门禁的核心不是对不对而是好不好而好是需要用指标来定义的。我在第一个 Agent 项目里就吃过这个亏。当时团队觉得人工测了几十轮都没问题直接上线结果第二天就出事了——用户问了一个稍微绕一点的问题Agent 开始反复调用同一个工具陷入死循环把接口配额跑光了。事后复盘才发现我们压根没测过异常输入下的行为。这就是没有评测门禁的代价你永远不知道你没测到的那部分有多危险。2.2 评测集怎么建三类样本缺一不可评测门禁的地基是评测集。很多人建评测集就是随手抓几十条正常问题这远远不够。一个能拦住问题的评测集至少要包含三类样本第一类是黄金样本Golden Set也就是最典型的正常输入用来验证 Agent 的基本能力没有退化。这部分样本要覆盖核心业务场景每条都要有明确的期望输出或期望行为。比如一个代码助手 Agent黄金样本就是给定一段有 bug 的代码期望它能指出问题并给出修复建议。第二类是边界样本Edge Cases专门测那些容易出问题的输入。空输入、超长输入、包含特殊字符的输入、语义模糊的输入、多意图混合的输入全都归到这一类。这类样本不要求 Agent 给出完美答案但要求它不能崩溃、不能死循环、不能输出有害内容。第三类是对抗样本Adversarial Set模拟恶意或诱导性输入。比如诱导 Agent 泄露系统提示词、诱导它执行危险操作、用 prompt injection 试图劫持它的行为。这类样本是安全底线一旦不通过直接一票否决。三类样本的比例我的经验是黄金样本占 60%边界样本占 30%对抗样本占 10%。黄金样本保证能力边界样本保证稳定对抗样本保证安全。缺了任何一类你的门禁都是有漏洞的。2.3 评测指标怎么选别只看准确率指标选错了门禁就是摆设。我见过太多团队只盯着准确率一个指标结果 Agent 准确率 95% 看着很漂亮上线后用户满意度却很低。原因是那 5% 的错误恰好都发生在高频场景上而且错误方式特别离谱。一个靠谱的 Agent 评测指标体系至少要覆盖四个维度维度核心指标说明效果任务完成率、答案相关性衡量 Agent 有没有真正解决问题效率平均响应时间、工具调用次数衡量它是不是绕远路稳定输出一致性、异常率衡量同样输入下表现是否可复现安全越狱拦截率、有害输出率衡量底线是否守住其中输出一致性这个指标特别容易被忽略但对 Agent 极其重要。具体做法是同一条输入跑 5 次看输出的语义相似度。如果 5 次回答南辕北辙说明这个 Agent 的行为极不稳定哪怕单次看都对上线后也会让用户困惑。我一般要求核心场景的一致性得分不低于 0.85低于这个值就要回去查是不是 prompt 写得太模糊或者温度参数设太高了。2.4 门禁阈值怎么定用数据说话别拍脑袋阈值定多少不能靠感觉。我的做法是先让当前版本跑一遍完整评测集拿到基线数据然后根据业务容忍度往上加一点作为门槛。比如当前任务完成率是 88%业务上能接受的最低是 85%那门禁就设在 85%同时设一个警告线在 88%低于警告线虽然不拦截但要提醒团队关注。这里有个关键细节门禁要区分硬门槛和软门槛。安全类指标是硬门槛不达标直接拦截没有商量余地。效果类指标是软门槛可以允许小幅波动但要记录趋势。如果连续三个版本的完成率都在缓慢下降哪怕每次都还在门槛之上也要拉响警报——这说明 Agent 在悄悄退化。下面是一段评测门禁的核心逻辑伪代码可以直接套用def evaluate_gate(agent, eval_set, thresholds): results {golden: [], edge: [], adversarial: []} for sample in eval_set: output agent.run(sample.input) score judge(output, sample.expected, sample.category) results[sample.category].append(score) # 硬门槛安全类一票否决 safety_score mean(results[adversarial]) if safety_score thresholds[safety_hard]: return {pass: False, reason: 安全指标未达标, score: safety_score} # 软门槛效果类允许波动但记录 golden_score mean(results[golden]) edge_score mean(results[edge]) warnings [] if golden_score thresholds[golden_warn]: warnings.append(f黄金样本得分 {golden_score} 低于警告线) passed (golden_score thresholds[golden_hard] and edge_score thresholds[edge_hard]) return {pass: passed, warnings: warnings, scores: {golden: golden_score, edge: edge_score}}2.5 用 LLM 当裁判省力但别全信评测里最麻烦的是怎么判断输出好不好。人工评太慢规则匹配太死。现在主流做法是用一个更强的模型当裁判LLM-as-a-Judge给它评分标准让它给 Agent 的输出打分。这招确实省力但有两个坑必须避开。第一个坑是裁判偏见裁判模型倾向于给看起来更详细的回答打高分哪怕这个回答其实是废话。解决办法是在评分标准里明确写简洁且准确优于冗长但模糊并且给几个打分示例few-shot来校准。第二个坑是裁判和被评模型同源如果你用同一个模型既当选手又当裁判它会倾向于给自己风格的输出打高分。我的做法是裁判模型尽量选不同厂商、不同规模的模型交叉验证。如果条件允许关键场景还是保留一部分人工抽检用人工结果去校准裁判的准确率。提示LLM 裁判的评分结果本身也要做一致性校验。同一条输出让裁判评 3 次如果分数波动超过 0.2说明评分标准写得太模糊需要回去改 prompt。3. 可观测性埋点让 Agent 的每一步都看得见3.1 Agent 的可观测性和传统服务差在哪传统服务的可观测性三件套是日志、指标、链路追踪。Agent 也需要这三样但内容完全不同。传统服务你关心的是接口响应时间错误率QPSAgent 你关心的是这一轮对话里模型想了什么调了哪些工具每一步花了多少 token为什么最后给出了这个答案。打个比方传统服务像一条流水线你监控的是每个工位的产出速度。Agent 像一个人在做决策你监控的是他的思考过程。前者看结果就行后者必须看过程因为结果对了不代表过程对——它可能是蒙对的下次就错了。所以 Agent 的可观测性埋点核心是把一次完整的 Agent 执行拆解成可追踪的步骤。一次典型的 Agent 执行包含接收输入、构造 prompt、调用模型、解析模型输出、决定是否调用工具、执行工具、把工具结果喂回模型、生成最终回答。每一个环节都要有埋点否则出了问题你只能看到输入 A 输出 B中间发生了什么完全是个黑盒。3.2 埋点埋什么五个必埋字段埋点不是越多越好埋一堆没用的字段只会拖慢性能、增加存储成本。我总结下来Agent 场景下有五个字段是必须埋的第一个是 trace_id贯穿一次完整执行的所有步骤。用户反馈问题时你拿着这个 id 就能把整条链路捞出来。这个 id 要能从入口一直透传到最底层中间任何一环断了都不行。第二个是 step_type标记当前是哪一步。是模型调用、工具调用、还是结果解析。有了这个字段你才能按步骤聚合分析比如工具调用平均耗时。第三个是 token 消耗包括输入 token 和输出 token。这个直接关系到成本也是排查为什么这个月账单暴涨的关键。我一般还会记录累计 token方便看单次对话的总消耗。第四个是 latency每一步的耗时。Agent 慢往往不是模型慢而是工具调用慢或者步骤太多。把每步耗时拆开瓶颈一目了然。第五个是 tool_call 详情包括调用了哪个工具、传了什么参数、返回了什么结果、成功还是失败。这是排查 Agent 行为异常最重要的信息。很多时候 Agent 答非所问就是因为某个工具返回了错误结果而模型基于错误结果继续推理。3.3 埋点怎么埋装饰器模式最省事埋点代码最忌讳散落在业务逻辑各处那样维护起来是灾难。我的做法是用装饰器或者中间件把埋点逻辑和业务逻辑解耦。下面是一个 Python 装饰器的示例import time import functools from contextvars import ContextVar trace_id_var ContextVar(trace_id, defaultNone) def traced(step_type): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): trace_id trace_id_var.get() start time.time() span { trace_id: trace_id, step_type: step_type, start_time: start, input: str(args)[:500], # 截断避免日志爆炸 } try: result func(*args, **kwargs) span[status] success span[output] str(result)[:500] return result except Exception as e: span[status] error span[error] str(e) raise finally: span[latency] time.time() - start emit_span(span) # 发送到可观测性后端 return wrapper return decorator # 使用 traced(model_call) def call_model(prompt): ... traced(tool_call) def call_tool(name, params): ...这样每个关键步骤只要加一个装饰器埋点就自动完成了。ContextVar保证 trace_id 在异步环境下也能正确透传不会串号。3.4 日志、指标、追踪三者怎么配合埋点数据收集上来之后要分三条线去用日志线记录详细的执行过程用于事后排查。日志要结构化JSON 格式方便检索。但要注意日志量Agent 的日志很容易爆炸我一般对输入输出做截断只保留前 500 字符完整内容存到对象存储日志里只放引用。指标线做聚合统计用于实时监控和告警。比如每分钟工具调用失败率P95 响应时间平均 token 消耗。这些指标要接到监控面板上设好告警阈值。工具调用失败率超过 5% 就该报警了说明下游服务可能出问题了。追踪线把一次执行的完整链路串起来用于分析单次问题。用户投诉这次回答不对你拿着 trace_id 就能看到完整的执行树模型第一次输出是什么、调了哪个工具、工具返回什么、模型第二次输出是什么。这条链路是排查 Agent 问题的命根子。三条线各司其职缺一不可。只有日志没有指标你没法及时发现趋势性问题只有指标没有追踪你定位不到具体是哪次执行出了问题。3.5 埋点里的隐私和成本陷阱埋点有两个大坑一个是隐私一个是成本。隐私方面Agent 的输入输出里很可能包含用户敏感信息。埋点的时候必须做脱敏手机号、身份证号、邮箱、地址这些都要打码。我的做法是在埋点层统一加一个脱敏函数所有要落库的文本先过一遍脱敏。别指望业务代码里每处都记得脱敏一定会漏。成本方面Agent 的埋点数据量比传统服务大得多因为每次执行都有多个步骤每个步骤都有输入输出。如果不做采样存储成本会失控。我的策略是错误和异常全量记录正常执行按 10% 采样。这样既保证了问题可追溯又控制了成本。采样的时候要保证同一个 trace_id 要么全采要么全不采不能采一半否则链路就断了。注意脱敏一定要在数据离开应用进程之前做不要指望存储层去脱敏。数据一旦落库泄露风险就已经产生了。4. AgentOps 落地把评测和埋点串成一套运维闭环4.1 AgentOps 到底解决什么问题前面讲的评测门禁和可观测性埋点如果各自为战价值会大打折扣。评测门禁只在发布时用一次埋点数据只在出事后翻一翻这就浪费了。AgentOps 的核心价值是把这两者串成一个持续运转的闭环线上埋点数据反哺评测集评测结果指导版本迭代迭代后的版本再经过门禁上线上线后继续收集数据。这个闭环听起来简单但真正落地需要解决几个工程问题数据怎么从线上回流到评测集、评测怎么自动化触发、版本怎么管理、出问题怎么快速回滚。下面逐个拆。4.2 线上数据回流让真实用户帮你建评测集最好的评测集不是拍脑袋想出来的而是从真实流量里挖出来的。具体做法是在埋点数据里标记那些表现异常的样本——比如用户追问了、用户点了差评、工具调用失败了、响应时间超长的——把这些样本捞出来人工审核后加入评测集。我一般会设几个回流规则用户连续追问超过 3 次的对话、工具调用报错的对话、响应时间超过 10 秒的对话、用户主动反馈不对的对话。这些样本天然就是 Agent 的薄弱环节把它们补进评测集下次发版就能拦住同类问题。回流的数据要经过清洗和标注才能进评测集。清洗是去掉重复和无效样本标注是给每条样本打上期望行为。这一步需要人工介入但量不大每天花半小时就能处理完。关键是形成习惯别让回流数据堆着没人管。4.3 版本管理与灰度别让新版本直接面对全量用户Agent 的版本管理比传统服务复杂因为一次发版可能同时改了 prompt、换了模型、调了工具。这三者任何一个变了Agent 的行为都可能大变。所以版本号要能追溯到具体改了什么。我的做法是给每次发版打一个配置指纹把 prompt 版本、模型版本、工具版本、参数配置全都哈希成一个字符串。这样线上出问题时你拿着指纹就能知道当时跑的是哪套配置能精确复现。灰度发布是必须的。新版本先放 5% 流量观察核心指标完成率、异常率、响应时间有没有异常。如果指标平稳再逐步放量到 20%、50%、100%。灰度期间要盯着埋点数据一旦发现异常率上升立即回滚。回滚要能做到秒级所以配置要支持热更新别搞成改配置要重新部署。4.4 告警设计别让告警淹没你AgentOps 的告警设计有个悖论告警太少会漏问题告警太多会让人麻木。我见过一个团队给 Agent 设了 50 多条告警规则结果每天响几百次最后所有人都把告警静音了真出大事也没人管。告警要分层。P0 告警是必须立即处理的比如安全指标跌破底线、服务完全不可用。这类告警走电话或即时通讯工具半夜也要叫人起来。P1 告警是当天要处理的比如工具调用失败率超过 10%、P95 响应时间翻倍。这类走工作群通知。P2 告警是记录备查的比如某个低频场景的完成率下降走日报汇总。告警阈值要动态调整。新版本刚上线时阈值可以放宽一点稳定运行一周后再收紧。别用一套固定阈值管所有版本那样要么误报要么漏报。4.5 成本监控AgentOps 里最容易被忽视的一环Agent 的成本是个隐形杀手。传统服务的成本主要是服务器相对固定。Agent 的成本和调用量、token 消耗直接挂钩一次失控的循环调用可能烧掉几百块。我见过一个项目因为 Agent 陷入死循环一晚上跑掉了几千块 token 费用。所以成本监控必须纳入 AgentOps。具体做法是按 trace_id 记录每次执行的 token 消耗按用户、按场景、按版本聚合。设一个单次执行的 token 上限超过就强制中断。再设一个日消耗告警超过预算的 80% 就提醒。成本数据还能反哺优化。如果发现某个场景的 token 消耗特别高说明这个场景的 prompt 可能太啰嗦或者工具调用次数太多有优化空间。把成本当成一个和效果同等重要的指标来管Agent 才能长期健康运行。5. 一套可运行的最小 AgentOps 骨架5.1 整体架构四个模块各管一摊讲了这么多原理最后给一套能跑起来的最小骨架。这套骨架不依赖任何商业平台用开源组件就能搭起来适合中小团队快速落地。整体分四个模块评测模块负责跑评测集和门禁判断埋点模块负责采集执行数据存储模块负责存评测结果和埋点数据看板模块负责展示和告警。四个模块通过一个统一的数据格式就是前面说的 span串起来。技术选型上评测模块用 Python 脚本加 LLM 裁判埋点模块用装饰器存储用关系型数据库加对象存储结构化数据入库大文本进对象存储看板用现成的可视化工具接数据库。这套组合的好处是轻量、可控、不绑定厂商。5.2 评测模块的可运行代码import json from statistics import mean class EvalGate: def __init__(self, agent, judge, thresholds): self.agent agent self.judge judge self.thresholds thresholds def run(self, eval_set_path): with open(eval_set_path) as f: eval_set json.load(f) scores {golden: [], edge: [], adversarial: []} failures [] for sample in eval_set: output self.agent.run(sample[input]) score self.judge.score( inputsample[input], outputoutput, expectedsample.get(expected), categorysample[category] ) scores[sample[category]].append(score) if score self.thresholds[single_fail]: failures.append({ input: sample[input], output: output, score: score }) report { golden: mean(scores[golden]), edge: mean(scores[edge]), adversarial: mean(scores[adversarial]), failures: failures } report[pass] self._judge_pass(report) return report def _judge_pass(self, report): if report[adversarial] self.thresholds[safety_hard]: return False if report[golden] self.thresholds[golden_hard]: return False if report[edge] self.thresholds[edge_hard]: return False return True这段代码的核心是_judge_pass方法它把硬门槛的判断逻辑集中在一处改阈值只改这里。failures列表记录了所有低分样本方便发版前人工复核。5.3 埋点模块的可运行代码import json import time import uuid from contextvars import ContextVar trace_id_var ContextVar(trace_id, defaultNone) spans_buffer [] def start_trace(): trace_id str(uuid.uuid4()) trace_id_var.set(trace_id) return trace_id def emit_span(span): spans_buffer.append(span) if len(spans_buffer) 100: flush_spans() def flush_spans(): if not spans_buffer: return # 实际项目中这里写入数据库或消息队列 with open(spans.jsonl, a) as f: for span in spans_buffer: f.write(json.dumps(span, ensure_asciiFalse) \n) spans_buffer.clear() def traced(step_type, capture_ioTrue): def decorator(func): def wrapper(*args, **kwargs): span { trace_id: trace_id_var.get(), step_type: step_type, timestamp: time.time(), } if capture_io: span[input] _safe_str(args, kwargs) start time.time() try: result func(*args, **kwargs) span[status] success if capture_io: span[output] _safe_str(result) return result except Exception as e: span[status] error span[error] str(e) raise finally: span[latency_ms] round((time.time() - start) * 1000, 2) emit_span(span) return wrapper return decorator def _safe_str(*args): text str(args) return text[:500] if len(text) 500 else text这套埋点代码的关键设计是缓冲批量写入。如果每产生一个 span 就写一次数据库性能会被拖垮。攒够 100 条批量写性能开销可以忽略不计。capture_io参数允许对高频步骤关闭输入输出捕获进一步降低开销。5.4 把评测和埋点接起来最后一步是让评测和埋点数据互通。具体做法是评测跑出来的低分样本自动写入一个待优化队列线上埋点里标记为异常的 trace自动抽取输入输出写入同一个队列。这个队列就是下一轮迭代的输入。def collect_improvement_candidates(eval_report, span_file): candidates [] # 从评测失败样本里收集 for failure in eval_report[failures]: candidates.append({ source: eval, input: failure[input], output: failure[output], score: failure[score] }) # 从线上异常 trace 里收集 with open(span_file) as f: for line in f: span json.loads(line) if span.get(status) error: candidates.append({ source: online, trace_id: span[trace_id], step_type: span[step_type], error: span.get(error) }) return candidates这个函数每周跑一次产出的候选样本交给团队做人工审核审核通过的补进评测集。这样评测集就会随着线上问题不断丰富门禁也会越来越严Agent 的质量就形成了一个正向循环。6. 上线前最后一遍自查那些我踩过的坑6.1 评测集里的样本别用生产真实数据这是个隐私红线。评测集里的样本如果是真实用户数据一旦评测代码或结果泄露就是数据事故。我的做法是评测集全部用脱敏后的数据或者干脆用合成数据。合成数据虽然不如真实数据刁钻但胜在安全可控。如果非要用真实数据必须经过严格的脱敏和审批流程。6.2 埋点别埋成性能瓶颈我见过一个项目埋点埋得太狠每个 token 都记一条日志结果 Agent 的响应时间从 2 秒涨到 8 秒用户全跑光了。埋点一定要做性能测试确保开启埋点后响应时间增幅不超过 10%。如果超过就要降采样或者异步化。异步化是基本操作埋点写入绝对不能阻塞主流程。6.3 门禁阈值别设太死阈值设太死会导致两个问题一是频繁误拦团队为了发版不断调低阈值最后门禁形同虚设二是团队为了过门禁去刷分专门针对评测集优化导致 Agent 在评测集上表现很好但真实场景拉胯。阈值要留合理波动空间同时评测集要定期更新防止被刷分。6.4 回滚方案要提前演练回滚不是嘴上说说要真的演练过。我建议每次发版前都做一次回滚演练确认回滚能在 1 分钟内完成且回滚后指标恢复正常。很多团队的回滚方案写在文档里真出事的时候发现根本跑不通那就晚了。6.5 别指望一套方案打天下Agent 的类型太多了对话型、任务型、多智能体型它们的评测重点和埋点重点都不一样。对话型重一致性任务型重完成率多智能体型重协作效率。这套骨架是个起点具体到你的场景指标和埋点字段都要按需调整。照搬照抄只能解决 60% 的问题剩下 40% 得靠你对业务的理解去补。我在实际项目里最大的体会是Agent 上线这件事技术只占一半另一半是流程和习惯。评测门禁要变成发版的固定动作埋点数据要有人定期看AgentOps 的告警要有人响应。工具搭得再好没人用也是白搭。所以别一上来就追求大而全的平台先把最小闭环跑起来让团队养成习惯再逐步完善。这套骨架我用了大半年从最初的几十行代码长到现在几千行但核心逻辑一直没变——评测拦住问题埋点看清问题AgentOps 闭环解决问题。