Agent 跑出错误结果，你怎么排查？先解决“黑盒“问题
「Regnexe 实战系列」第 9 篇共 10 篇对应仓库ExampleReadme09ObservabilityTest。上一篇08. 说停就停说续就续。排查 Agent 问题最痛苦的地方写普通业务代码出了 bug 看堆栈、看日志基本能定位。Agent 系统不一样——一次任务背后是搜了哪些能力、规划选了哪几个、工具传了什么参数、模型回了什么、要不要继续一整条链路任何一环出问题最终表现可能只是答案不对但具体卡在哪一步黑盒模式下根本无从下手。Regnexe 这套 harness 的解法是Search → Plan → Execute → Reflect 每一步加上 Execute 内部的每一次工具调用全部对外发事件你接一个监听器就能看到完整链路——毕竟 harness 的职责就是驱动并暴露整个执行过程不暴露事件流等于只做了一半。默认方案ConsoleEventListener本系列从第一篇就在用其实前 8 篇的每个代码示例里都已经在用它了RegnexeAgentagentregnexeAgentBuilder.withTool(weatherTool).withEventListener(newConsoleEventListener()).build();跑起来直接看到完整链路[Agent Start ] R0 Goal: Check todays weather in Beijing. Is it good for running? | maxRounds: 3 [Search Result ] R1 Found 1 capabilities: get_weather [Plan Result ] R1 Selected: [get_weather] | Strategy: RETURN_LAST | ... [TOOL Call ] R1 get_weather {city: Beijing} [TOOL Result ] R1 get_weather - Beijing: sunny, 22 C, excellent air quality. [Execute Result] R1 SUCCESS | Beijing: sunny, 22 C, excellent air quality. [Reflect Result] R1 FINISH — weather data obtained, goal fully answered. [Agent Done ] R1 Status: FINISHED | Rounds: 1调试阶段这就够用——Search 有没有找对能力、Plan 选的对不对、工具参数对不对、Reflect 判断逻辑合不合理一行行都能对上。进阶用法按需打开 Token 和原始 LLM 输出默认情况下Token 消耗和模型原始响应文本是被过滤掉的——大部分调试场景不需要这么细。但排查为什么这一步选错了有时候就得看模型当时到底想了什么newConsoleEventListener(true,true);// showTokenEventstrue, showLlmEventstrue打开之后控制台会多出TOKEN_USAGE、CAPABILITY_TOKEN_USAGE、TASK_TOKEN_SUMMARY以及PLAN_LLM_RESPONDED/REFLECT_LLM_RESPONDED这类原始模型响应。前者用来做成本核算后者用来排查模型这一步到底是怎么推理的。生产环境换成 Slf4jEventListener一行代码的事println在本地调试很方便丢进生产环境就是灾难——日志不进统一采集系统没法跟其他业务日志关联检索。Regnexe 提供了一个格式完全一致、只是输出通道不同的版本regnexeAgentBuilder.withEventListener(newSlf4jEventListener())...事件文本跟ConsoleEventListener一字不差区别只是走 SLF4J——这意味着它自动汇入你应用现有的日志管道文件、JSON、ELK随便接跟其他业务日志混排检索不再是一条独立的println输出流。调试用 Console上线换 Slf4j业务代码一行不用改这是 Regnexe 一贯的设计风格——前几篇的Marketplace、ConversationStorage、TaskStore都是这个套路。事件分类一览外层循环*_STARTED / *_COMPLETED 成对出现 AGENT / SEARCH / PLAN / EXECUTION / REFLECTION 内层循环Execute 阶段内部的工具调用 TOOL_CALLED / TOOL_RESULT / LLM_RESPONDED 按阶段区分的模型响应钩子 PLAN_LLM_RESPONDED / REFLECT_LLM_RESPONDED / SKILL_LLM_RESPONDED / AGENT_LLM_RESPONDED Token 用量 TOKEN_USAGE / CAPABILITY_TOKEN_USAGE / TASK_TOKEN_SUMMARY想写自己的监听器继承一个抽象类就行ConsoleEventListener和Slf4jEventListener都继承自AbstractEventListener这个基类把按类型过滤和格式化文本都做好了你只需要关心onEventpublicclassMyDashboardListenerextendsAbstractEventListener{publicMyDashboardListener(){super(false,false);// 不要 Token 和原始 LLM 事件}OverridepublicvoidonEvent(AgentEventevent){websocket.push(format(event));// 推到前端实时展示}}接前端做Agent 正在搜索能力…正在调用天气工具…任务完成这种实时进度展示或者接监控系统做异常告警都是这一个扩展点的事。小结可观测性不是锦上添花的功能是 Agent 从 Demo 走向生产前必须补上的一课——没有事件流出了问题只能靠猜有了事件流每一步选择、每一次调用、每一个判断都摆在台面上。系列回顾到这里「Regnexe 实战系列」10 篇全部更新完毕从 00. 开篇 的 Search→Plan→Execute→Reflect 闭环讲起依次拆解了withTool快速接入、Skill / Sub-Agent 两种子能力、Plugin注解打包、四种插件加载方式、可替换的 Marketplace、三层记忆模型、暂停恢复到这一篇的可观测性——9 个示例全部来自仓库里真实可跑的ExampleReadme01~09Test照着敲一遍就能跑通。一句话总结这套 harnessSearch 收窄能力范围Plan 把目标拆成步骤Execute 真正执行多种类型的能力Reflect 检查结果是不是真的做完了——四步闭环 可插拔的市场/记忆/可观测性这就是 Regnexe 想做的事。如果这个系列帮你省了几次踩坑欢迎去仓库点个 ⭐有问题也欢迎在 issue 里交流https://github.com/flower-trees/regnexe-agent 上一篇08. 说停就停说续就续 系列开篇00. 别再给 LLM 写 if-else 了 项目地址https://github.com/flower-trees/regnexe-agent
