企业官网建设流程全解析

你负责的Agent又在半夜偷偷跑偏了吧？Prompt被改了一句，输出格式全乱；多智能体协作时，某个子Agent静默失败，结果整个链路返回了看似正常、实则南辕北辙的数据。这类问题我这两年见得太多了。所以当我开始做“Agent Canary”这个项目时，核心目标就一句话：给智能体系统装一只煤矿里的金丝雀，在矿难发生之前，让异常先被闻到。

Agent Canary本质是一个面向AI Agent系统的主动巡检与风险预警探针。它不监控服务器CPU，也不采集GPU利用率，它专门盯着“行为”本身——你的Agent在做什么、回没回答、回答得对不对、有没有偏离任务轨道。它适合正在把Agent从demo推向生产的团队，也适合那些已经上了多Agent架构、但总感觉哪里会突然崩一下的开发者。

1. Agent Canary在解决什么问题

1.1 大模型应用最大的不可控因素

传统软件出bug是有边界的，报错、崩溃、堆栈信息都摆在那。但Agent不一样，它可能不报错，它只是以一种非常有逻辑的方式，做了完全错误的事。

我在实际运维中遇到过这样的情况：一个负责生成周报的Agent，某个版本上线后开始频繁把“本周完成”写成“上周完成”，整个系统没有任何异常告警，因为接口200、响应时间正常、Token消耗正常。直到业务方发现周报数据全错了，才定位到是Prompt里一个时间变量被上游传错值。这类问题用常规监控根本发现不了，因为链路是通的，只是行为偏了。

Agent Canary的思路就是不再盯着“服务健康”，而是盯“任务质量”。它用一套独立于业务链路的旁路机制，定期向Agent投放一批已知答案的探测任务，然后把实际输出和预期结果做比对，得出一个“行为健康分”。分数掉到阈值以下，马上告警。

1.2 传统监控工具为什么管不住Agent

先说结论：不是工具不行，是监控维度对不上。Prometheus、Grafana、ELK这些解决的是“系统层面”的可观测性，它们能告诉你CPU打满了、内存溢出了、日志报错了，但它们回答不了“这个回答靠不靠谱”。

到了Agent场景，我们需要监控的关键指标变成了：

• 任务完成率：发出100个任务，真正按预期完成的占比是多少
• 语义偏差率：Agent的回复在意思上是否偏离了用户意图
• 工具调用正确性：Agent调用搜索、数据库、API时，参数是否传对、结果是否被正确使用
• 幻觉触发频率：Agent是否在编造不存在的功能或数据
• 链路一致性：多Agent协作时，上游输出和下游输入衔接是否正确

这些指标没有现成的exporter可以采集，没有现成的告警规则可以套用。Agent Canary做的事情，就是把这些“软指标”变成一套可度量的、可预警的体系。

1.3 这个项目适合谁

我自己把它定位在“生产环境Agent链路调优与风险兜底”这个场景。具体来说，适合三类人：

第一类是正在跑RAG、Agent类线上服务的后端工程师，模型层基本稳定了，但总是被“诡辩论”式的错误输出困扰；第二类是算法工程师，想量化评估Prompt模板变更前后Agent行为是否有回归；第三类是对接客户交付的解决方案团队，需要在交付前对Agent做一轮系统性的健壮性测试。

做这个项目之前，建议你手头至少有一个已经跑通核心链路的Agent服务。不需要多复杂，哪怕是一个接入大模型API、带工具调用能力的单Agent都可以。因为Agent Canary的作用是“体检”，不是“手术”，你得先有一个能跑的服务，才谈得上监控它。

2. Agent Canary的整体架构与设计思路

2.1 旁路探针：不侵入业务逻辑

我设计Agent Canary时，最先定下的一条原则就是：不侵入正在运行的Agent业务代码。这跟传统监控里的“旁路采集”是一个道理，你不能为了监控而修改核心链路的逻辑，不然监控本身就成了一次上线风险。

所以Agent Canary是独立部署的一套服务，它通过两种方式跟目标Agent对接。

第一种是API调用方式，适用于你的Agent暴露了HTTP接口或SDK入口。Canary定时发送一批构造好的测试请求，这些请求会走一遍真实链路，最终返回Agent的回答。第二种是事件订阅方式，适用于消息队列场景，比如Agent从Kafka、RocketMQ消费消息，Canary把一个带特殊标记的测试事件投递到队列头部，然后监听处理结果。

这两种方式下，Agent完全感知不到监控系统的存在，它只是照常处理进来的请求。Canary就在旁边静静地看着，记录每一次投递和返回。

2.2 三个核心引擎

整个系统跑起来之后，内部是三个引擎在配合工作。

第一个是任务编排引擎。它负责管理所有探测任务的生命周期。每一轮巡检开始前，它会从任务池里拉取一组测试用例，按配置的并发度、时间间隔、优先级排列好，然后逐个投递出去。这个引擎还处理重试：如果目标Agent超时了，或者返回格式不符合规范，编排引擎会按策略重新投递，并记录重试次数。

第二个是评估引擎，这是Agent Canary最核心的部分。它接收Agent的原始输出，从三个维度做评估。事实性评估处理的是“回答是否忠于输入上下文”，方式是抽取输出中的关键信息点，和输入上下文里的实体、数值、逻辑做一致性校验；规则性评估处理的是“是否遵守了约束条件”，比如Prompt里要求“仅返回JSON”结果却给了散文，这类硬性约束用规则匹配就能识别；语义相似度评估处理的是“意思是否对了”，用向量模型把预期答案和实际输出各自编码，然后算余弦相似度。

第三个是动态阈值引擎。我一开始用的是固定阈值，比如相似度低于0.8就告警。跑了一段时间发现，不同任务类型的波动范围差异极大，固定阈值要么太灵敏疯狂误报，要么太迟钝漏掉真问题。后来改成滚动窗口自适应：每个任务维护最近N次评分的滑动窗口，实时计算均值和一个合理的标准差区间，超出波动区间的结果才会触发告警。

2.3 为什么不用全链路追踪

有朋友问过我，这跟方案A、方案B这类追踪工具有什么区别。说一个我自己的体会。

链路追踪的强项是把一次请求的完整调用链串起来。它记录了“Agent调了哪个工具、工具返回了什么、最后怎么拼装成回答”。这在排查性能瓶颈和工具调用故障时很有效。但它的视角是时域的，回答完就结束了，没有人去判断“刚才这次回答里提到的那个数据是不是真的存在于知识库中”。

Agent Canary的视角是质量域的，它关注的核心问题是：这次任务的质量是否发生了劣化。链路追踪回答“这次调用干了什么”，Canary回答“这次干得对不对”。两者不是替代关系，是互补关系。生产环境我建议两个都上，链路追踪用于故障排查，Agent Canary用于质量兜底。

3. 核心实现细节：从探针到告警

3.1 探针数据的采集约定

不管是API调用还是事件订阅，所有进入Agent Canary的原始响应都会先被标准化成统一的格式。这个格式我定义为一个Event结构：

{ "task_id": "可以唯一定位一次探测任务", "trace_id": "关联到链路追踪系统的ID", "agent_id": "被监控Agent的唯一标识", "input_context": "传给Agent的上下文原文", "expected_behavior": "期望的行为描述或参考输出", "actual_output": "Agent实际返回的原始内容", "latency_ms": "从投递到返回的耗时", "tool_calls": ["Agent这一轮调用过的工具列表"], "created_at": "时间戳" }

这个标准化过程非常重要。因为不同Agent的返回格式五花八门，有的是标准JSON，有的是Markdown文本，有的是一大段带聊天记录的HTML。如果不统一格式，后面的评估引擎就没法一套逻辑处理所有数据。

采集端还有一个细节：原始输出必须留底。我在评估阶段只读取副本，原始输出会被原封不动归档到本地存储。这样做的原因是，告警触发后你需要复盘，而复盘时看到的应该是Agent当时的完整回答，不是评估引擎处理后的摘要。

3.2 尝试性实现：多维度结果比对

评估引擎的工作方式，简单来说是“多维比对——加权打分——判定健康状态”。这里我以一个真实场景为例：我用Canary监控一个“法律条款问答Agent”，它在收到用户问题后会先检索知识库再做回答。

我给它配置的探测任务是：发送10个预置问题，比如“劳动合同到期不续签，公司需要提前30天通知吗”，然后根据知识库中整理好的标准答案做比对。

事实性维度我用基于实体匹配的核对逻辑：

def check_factual_consistency(actual_output, input_context): # 从输入上下文中提取关键实体和数值，检查输出中是否保持了一致 critical_entities = extract_entities(input_context) missing_entities = [] for entity in critical_entities: # 期望输出中必须保留上下文里的核心实体，不允许做替换 if entity not in actual_output: missing_entities.append(entity) return { "missing_entities": missing_entities, "facts_consistency_score": max(0, 1 - len(missing_entities) / len(critical_entities)) }

这里要特别注意一个细节：实体匹配用的是精确匹配还是语义匹配，需要根据场景定。法律条款场景里，法条编号、金额数字必须精确，一个都不能错，所以用精确匹配；但像“把客户反馈总结成三条建议”这类任务，客户的原话可以被适当改写，这时就得用基于向量的语义匹配。

规则性维度用来判定硬性约束。比如我配置了“回答必须以‘根据现行规定’开头”，那评估引擎就直接查前缀，不满足就判0分。这类规则是最容易误报的源头，因为Agent偶尔会自作主张换个说法，因此我在实现时给规则性维度设计了“警告”和“不合格”两档，只有不合格才触发告警，警告只记录不打扰。

语义相似度维度用向量模型来实现。我选了中文场景下效果比较稳定的bge-m3，把参考回答和实际输出分别编码成向量，然后算余弦相似度，归一化到0-100分。不同任务类型我会给相似度设置不同权重。

3.3 告警触发的核心逻辑

告警不是评分低就立刻发，我设计了两层递进机制。

第一层是单次评分触发。当一条探测任务的综合得分低于该任务的绝对下限阈值时，直接进入告警队列。这比较好理解：如果语义相似度只有0.3，说明Agent这次回答跟预期完全对不上，这种情况等不得，必须立刻知道。

第二层是趋势异常触发。单个任务的单次评分可能因为偶然波动掉分，但它在正常范围内。所以我维护了一个波动基线：把最近20次评分作为一个滑动窗口，计算出均值和标准差。当节点触发了“连续多轮低于均值减一倍标准差”时，才认为系统出现了趋势性的行为退化。

这个设计帮我避过了一个大坑：有一次Agent因为上游模型升级，回答风格变了，但信息其实是准确的，语义相似度每轮都掉到0.55左右，按绝对阈值早就炸了，但趋势异常检测看到的是连续20轮都在这个区间，没有显著下滑，所以没有告警。后来我人工复盘确认，这个分数波动确实只是风格偏移，不是质量问题。

告警消息本身会带着完整的证据链：哪条任务、输入是什么、预期是什么、实际回答是什么、每个评分维度的得分是多少、和最近N轮的平均分数偏差多大。这样告警发到群里，值班的人不用再翻日志，一眼就能判断问题严重性。

3.4 回放与自动回归

告警只是第一步，没有回放能力的监控系统等于白做。Agent Canary实现了一个关键机制：当一条探测任务触发告警时，系统会自动把这条任务的完整上下文存入一个“回放队列”，队列里的任务可以被一键重新投递给Agent。

这个回放功能在很多场景下救过我的命。最典型的一个例子是：Agent上线新Prompt模板后，有一类任务从“偶尔说错”变成“稳定说错”。第一次告警触发时，我把任务回放了三次，三次都出现同样的错误，确认不是偶发，是Prompts配置问题。如果没有回放机制，我可能要去反复猜测是网络抖动还是模型随机性。

这个能力还能延伸成“回归测试集”。我把历史上所有触发过告警的探测任务收集起来，打上“历史问题”标签。每次Agent更新Prompt、更换模型版本、调整工具参数后，都先跑一遍回归集，确保之前修过的问题没有复发。这套机制在生产环境中的价值，甚至比告警本身更大。因为Agent的迭代频率很高，每次升级都是一次潜在的行为回归风险。

4. 实操过程：从零搭建一套Agent Canary

4.1 基础环境规划

我用的是轻量级架构。中间件依赖极简，核心服务本身只是一个Python 3.11的FastAPI应用，评估引擎独立成worker，用Redis做事件缓冲和队列，任务库和告警历史放在了PostgreSQL里。

整个部署拓扑非常直白：

• canary-api：对外接收Agent返回结果，做数据标准化和归档
• canary-scheduler：定时从任务池拉取探测任务并投递
• canary-evaluator：消费评估事件，运行多维评分逻辑
• canary-alert：接收评估结果，执行阈值判定，发送告警到钉钉/飞书

如果Agent数量少于10个、峰值QPS在50以内，一台4核8G的云主机就完全够用。我自己初期就是在这么一台机器上跑的，评估worker和API服务部署在一起，数据库用云厂商的托管PostgreSQL，Redis用了2G的轻量实例。

生产环境规模上来了再加机器就来得及，这个项目最忌讳一开始就把架构搞得太大，需求都还没跑顺，先花大量时间搭分布式，得不偿失。

4.2 探测任务池的配置

核心配置都在任务池里定义。每个任务包含一段上下文、一份预期结果、一组评估参数和调度策略。

{ "task_id": "legal-qa-009", "name": "劳动合同到期续签问题", "input_prompt": "公司在劳动合同到期前需要提前多少天通知员工是否续签？", "input_context": "根据《劳动合同法》相关规定，劳动合同期满前，用人单位应当提前30日将终止或者续订劳动合同的意向以书面形式通知劳动者。", "expected_output": "公司需要在劳动合同到期前30天书面通知员工是否续签", "evaluation_weights": { "semantic": 0.5, "factual": 0.3, "rule": 0.2 }, "semantic_min_threshold": 75, "factual_critical_entities": ["30日", "书面", "劳动合同"], "rule_keywords": ["提前", "30"], "schedule": {"cron": "*/10 * * * * *"}, "active": true }

配置里对权重和阈值，我的经验是：语义权重不要设置成1.0，不然会被模型风格带偏；事实性权重在知识问答类任务里至少要给到0.3以上。如果任务只是开放性讨论题，没有标准事实答案，那事实性维度的权重可以直接砍掉，只保留语义和规则。

调度频率根据目的不同差异很大。日常巡检我用每10分钟一轮，一轮投放10-20个任务。上线新Prompt模板或新模型时，我会临时把频率调到每分钟一轮，并且只跑回归任务集。一轮任务全跑完大约需要几十秒到两三分钟，取决于Agent响应速度。

4.3 评估引擎的初始化与调参

评估引擎启动时，会先从PostgreSQL里加载所有生效的任务配置，构建好每个任务的评估模板。语义相似度的向量模型在启动时加载到内存，bge-m3中文模型大约占2G左右显存，没有GPU也可以用CPU跑，速度会慢一些，评估一条任务多出几百毫秒延迟，在可接受范围内。

这里有个容易被忽视的初始化步骤：正式上线前，先用每个任务的历史正常输出跑50-80条数据，算出该任务的基准分数分布。这个分布是后续计算滑动窗口阈值、告警基线的基础。

我踩过一个坑：任务配置里忘了设置基准，导致动态阈值引擎在没有任何历史数据时只能按默认阈值工作。默认阈值设得太保守，每天告警几十条，全是无效噪音，值班同事一度看到告警就屏蔽了。后来我把所有任务都补了基准数据，才把误报率压下来。所以，告警要宁可少而精，不要多而滥，滥告警会毁掉整套监控体系的信用。

4.4 Agent端的对接方式

对接过程比我想象中简单。如果Agent有自己的API网关层，那只需要在网关层加一个过滤器，识别出Canary投递的请求（通过请求头里的x-canary-task-id），命中后把请求体复制一份投递到Canary API，同时把后续响应也复制一份一起发送过去，正常业务请求不受任何影响。

如果是SDK模式集成的Agent，canary-scheduler会直接以客户端身份调用Agent的接口，Agent代码完全不需要改动，只要提供接口地址和鉴权信息即可。

对第一种方式，我在网关层的过滤器实现最简单版本大概是这样的：

@app.middleware("http") async def canary_ingest(request: Request, call_next): task_id = request.headers.get("x-canary-task-id") if task_id: request_body = await request.body() # 异步把请求体发送给canary服务，不阻塞主链路 asyncio.create_task( forward_to_canary(task_id, request_body) ) response = await call_next(request) if task_id: response_body = b"" async for chunk in response.body_iterator: response_body += chunk asyncio.create_task( forward_response_to_canary(task_id, response_body) ) # 需要重新构造带body的response，因为body_iterator只能消费一次 return Response(content=response_body, status_code=response.status_code) return response

这里有个很关键的性能注意点：在中间件里读取响应体不能直接阻塞主线程。上面代码把所有转发操作都做成了异步任务，不阻塞业务响应，但如果你完全照抄，需要确保你的ASGI服务器是支持asyncio.create_task的（Uvicorn是支持的）。并且要注意FastAPI的Response里的body被读取后不能再次迭代，上面的代码里做了Response重建，这是必须的。

我在试验中发现，如果在这里做同步转发，Agent的P99延迟会从600ms直接飙到1.2s以上，因为响应体在内存里被完整拷贝了一份。改成异步后就几乎没有可见开销了。

5. 常见问题与排障实录

ACanary这套思路做下来，前前后后也遇到过不少问题。我把高频的几个问题整理成一个速查表，对应排查方向也写上，直接照着做就能解决掉一大半问题。

5.1 一个典型误报问题的完整复盘

我详细复盘一个误报案例，这可能比任何说明书都有价值。

某一轮巡检，Canary连续发送了15条“查询订单状态”的探测任务。Agent正常返回了JSON格式结果，但其中12条被语义相似度维度判了不及格。告警直接轰炸了整个值班群。

我去看具体评分，发现每条任务的相似度都只有0.35左右，但事实性维度得分是100，规则性维度得分也正常。问题变得很清晰：语义向量模型对“query详情页接口返回字段顺序变化”非常敏感。Agent调整了JSON字段的返回顺序，导致向量编码出现偏移。

但用户能感知到的业务结果完全没变。

这里我学到的教训是：语义相似度维度不适合用于结构化输出场景。JSON字段顺序、键名表达、Markdown格式层级这类表层形式变化，在向量空间里会被放大，产生大量误报。正确的做法是，对这类结构化输出任务，把语义权重降下来，甚至直接关闭语义评估，改用JSON Schema校验和字段值比对来评估。

现在我建任务的时候会先做一次分类：输出是自由文本的，语义相似度权重设0.5-0.7；输出是结构化数据的，语义权重设0或0.1，重点靠事实性和规则性维度判断。

5.2 动态阈值收敛慢的问题

还有一次，新接入一个Agent，Canary跑了一整个星期，一直处于“只记录不告警”的状态，我想观察它的基线到底怎么样。结果发现它的行为波动大到每周一个样，周一和周五的同一任务得分能差30分。

后来分析原因，发现这个Agent的上游是每周五发布新版本的RAG召回模型，每次更新后召回风格变化，导致输出措辞跟着变，语义向量就飘了。动态阈值引擎在这种场景下一直在跟随学习新分布，所以始终没办法收敛出一个稳定基线。

我的改造方案是：在动态阈值引擎里加入“版本感知”。把每次Agent发版的信息登记到配置文件里，Canary从某个时间点开始重建滑动窗口，不把新旧版本的评分混在一起算。这个改造上线后，基线明显稳定了，误报也少了很多。如果你接入的Agent本身发版频繁，强烈建议把这个版本登记机制考虑进去，否则阈值引擎会在模型升级后的几天内持续处于混乱状态。

6. Agent Canary的后续扩展方向

到了现在这个阶段，Agent Canary已经能稳定地帮我盯住单Agent和固定链路的多Agent系统。但Agent本身演化得很快，这套东西也得跟着扩展。

第一个明确的方向是把评估维度和不同Agent类型做更深的绑定。比如代码生成类Agent，重点看生成的代码能不能跑、测试通过率多少，这跟通用问答Agent完全不是一套逻辑。工具型Agent，像负责调用外部API那种，重点看参数组合合法性和返回结果解析正确率。这些评估逻辑应当沉淀为独立的插件模块，按Agent类型加载。

第二个方向是引入人机协同的标注流程。目前评估引擎里的“预期输出”还是靠人工维护的静态数据，维护成本不低。后续可以让线上真实任务里那些被人工标记为“好/坏”的输出反哺到标注集里，做增量训练和阈值修正。这是一个从规则引擎进化为学习型评估器的一个长期路线。

第三个方向是支持多Agent链路的传导分析。现在每个Agent各自有独立的巡检任务，但它们之间的衔接错误没有专门手段去捕捉。我打算在任务编排器里增加“链式探测”能力：构造一段贯穿多个Agent的复合任务，因为链路中最上游一个Agent返回来一个小偏差后，逐级传导到最终输出的偏差可能被放大，占比也很难预测。Canary如果能捕捉到这种放大效应，对多Agent系统的整体质量评估就有参考价值了。

从我个人的使用体会来说，Agent Canary这个项目最大的价值不是某一次成功拦截了故障，而是它逼着我把自己对“Agent运行是否正常”这件事的理解，从“说不清的感觉”变成了“可以量化、可以復盘、可以回归的指标体系”。这个思维转变，比任何工具都重要。建议你搭好框架之后，先用两周时间把各类任务的历史行为数据跑出来，哪怕暂时不接告警，光看那些评分分布曲线，你都会对自己负责的Agent系统有个全新的认识。