1. 项目概述构建能自我修复的AI智能体如果你正在尝试用AI智能体比如OpenCode、Cursor这类工具来帮你写代码那你一定遇到过这个场景智能体生成的代码跑不起来控制台里一堆红字错误然后你不得不像个翻译官一样把错误日志复制粘贴回去告诉它“这里错了改一下”。这个“写代码-报错-人工介入-再改”的循环始终没有真正闭合。智能体负责“写”而“调试”这个更烧脑的活儿依然牢牢攥在你手里。这个问题的核心在于智能体在运行时是“盲”的。它看不到自己执行时产生的痕迹——那些API调用、数据库查询、函数执行路径和抛出的异常。它只能根据你给的错误信息通常还是经过你筛选和转述的去猜测问题所在。这就像让一个医生在不看任何检查报告、只凭病人模糊的口述下诊断效率和准确性可想而知。那么有没有可能让智能体自己“看”到这些运行时信息自己诊断并修复问题呢答案是肯定的。这篇教程要分享的就是如何构建一个能“自我修复”的AI智能体。它不再是那个写完代码就撒手不管的“甩手掌柜”而是一个能主动运行测试、查询自己的运行轨迹、分析失败根因并最终修复Bug的“全栈工程师”。整个过程无需你阅读一行日志或手动给出修复提示。我们将通过一个具体的Demo来实现一个存在多处Bug的“文本转SQL”应用。当测试失败时我们的智能体会通过一个名为MCP的协议从云端观测平台查询自己刚刚产生的运行轨迹精准定位问题比如调错了API、读错了响应字段、表名对不上然后自动修复代码直到所有测试通过。整个技术栈的核心是三个开源工具Monocle用于自动埋点采集轨迹、Okahu Cloud用于存储和通过MCP协议暴露轨迹数据、以及支持MCP的OpenCode智能体。无论你是AI应用开发者、平台工程师还是对智能体自治能力感兴趣的探索者这套方案都能为你打开一扇新的大门让你看到下一代软件开发和运维的雏形。2. 核心思路与技术选型解析要实现智能体的自我修复关键在于打通“代码执行”与“运行时可观测性”之间的壁垒。传统的调试依赖于开发者在本地打断点、看日志但这套模式对智能体不适用。我们需要一套能让智能体以编程方式“感知”自身状态的基础设施。2.1 为什么是“轨迹”而不是“日志”首先我们要区分“日志”和“轨迹”。日志是离散的、文本化的记录需要人类去阅读理解。而轨迹是结构化的、带有上下文关联的调用链数据。一个典型的轨迹会记录一次LLM调用的输入输出和耗时、一次数据库查询的语句和结果、一次工具调用的参数和返回值以及这些操作之间的父子关系。对于智能体来说结构化的轨迹数据远比非结构化的日志文本更有价值。它可以直接被解析成JSON智能体可以像查询数据库一样精确地询问“最近一次名为generate_sql的工作流中哪个LLM调用失败了错误信息是什么” 这为基于证据的推理奠定了基础。2.2 技术栈深度拆解Monocle Okahu MCP我们的方案建立在两个核心组件之上它们分别解决了“数据采集”和“数据消费”的问题。Monocle零配置的自动埋点库它的价值主张极其简单一行代码开启全链路追踪。对于使用流行LLM SDK如OpenAI、LangChain、LlamaIndex的应用Monocle能自动注入埋点捕获每一次调用生成符合OpenTelemetry标准的轨迹数据。这意味着你不需要在智能体生成的每一段代码里手动添加打点逻辑——事实上你也做不到因为代码是动态生成的。Monocle的自动注入机制使得“可观测性”成为基础设施的一部分而非事后添加的负担。from monocle_apptrace import setup_monocle_telemetry # 这一行之后所有支持的SDK调用都会被自动追踪 setup_monocle_telemetry(workflow_nametext_to_sql_analyst)Okahu MCP为智能体设计的观测平台Okahu是一个云端的AI应用可观测性平台可以接收并存储来自Monocle的轨迹数据。但它的关键创新在于对MCP的支持。MCP是一个新兴的开放协议旨在为AI智能体提供标准化的数据源访问接口。你可以把它理解为智能体世界的“API网关”或“驱动程序”。传统的观测平台提供的是给人看的Dashboard充满了图表和可点击的界面。智能体无法与这些界面交互。Okahu通过MCP将同样的轨迹数据以结构化的JSON API形式暴露出来。智能体只需要像调用一个普通函数一样请求/okahu:get_latest_traces就能获取到分析问题所需的一切信息。这实现了从“Human-in-the-loop”到“Agent-in-the-loop”的范式转变。2.3 方案优势与设计考量选择这个组合主要基于以下几点考量对生成式代码友好Monocle的自动埋点不依赖预定义的代码结构完美适配智能体动态生成代码的特性。闭环反馈MCP协议提供了低延迟、程序化的数据访问通道使得“执行-观测-决策-修复”这个循环可以在秒级内完成。证据驱动避免幻觉我们为智能体设定了一条核心规则“无轨迹不修复”。智能体必须依据从MCP获取的具体错误轨迹来制定修复方案而不能基于训练数据中的普遍知识进行猜测。这极大地减少了智能体“一本正经地胡说八道”提出错误修复方案的风险。轻量集成整个方案对现有代码的侵入性极低。主要配置集中在环境变量和智能体的提示词工程上业务逻辑代码几乎不受影响。3. 环境搭建与核心组件配置理论讲完了我们动手把环境搭起来。这个Demo的所有代码都是开源的你可以完全复现。请确保你的系统已安装Python 3.10或更高版本。3.1 前期准备与依赖安装首先克隆项目仓库并创建独立的Python虚拟环境这是一个好习惯可以避免包依赖冲突。git clone https://github.com/Arindam200/awesome-ai-apps cd awesome-ai-apps/mcp_ai_agents/telemetry-mcp-okahu python3 -m venv venv source venv/bin/activate # Windows系统请使用 venv\Scripts\activate接下来安装核心的Python依赖包。这些包涵盖了轨迹采集、测试验证、AI模型调用和Web服务。pip install monocle_apptrace monocle_test_tools openai fastapi pytest python-dotenvmonocle_apptrace: 核心的自动埋点库。monocle_test_tools: 基于轨迹的测试验证框架它能验证“是否产生了正确的轨迹”而不仅仅是“代码是否运行”。openai: 调用GPT-4o等模型的官方SDK。fastapipytest: 用于构建Demo应用和运行测试。python-dotenv: 管理环境变量。3.2 密钥配置与数据初始化这个Demo需要两个关键的API密钥OpenAI API Key用于调用GPT-4o模型生成SQL。Okahu API Key用于将轨迹数据发送到Okahu云端并通过MCP查询。在项目根目录下创建一个名为.env的文件填入你的密钥# .env 文件内容 OPENAI_API_KEYsk-your-openai-key-here OPENAI_MODELgpt-4o OKAHU_API_KEYyour-okahu-key-here MONOCLE_EXPORTERokahu关键配置解析MONOCLE_EXPORTERokahu这一行至关重要。它指示Monocle库将采集到的轨迹数据直接发送到Okahu Cloud而不是输出到本地控制台。在我们的Demo中我们会故意屏蔽所有本地日志输出从而强制智能体必须通过查询Okahu MCP来获取调试信息模拟生产环境下的真实场景。最后运行数据库初始化脚本创建一个包含users和orders表的SQLite数据库这是我们文本转SQL应用将要查询的对象。python setup_db.py3.3 理解预设的Bug与测试套件为了演示的确定性和可重复性Demo中预置了一个存在三个故意引入Bug的analyst.py文件。这三个Bug涵盖了从API使用错误到业务逻辑错误的典型场景Bug编号问题描述在轨迹中会看到什么Bug #1使用了已废弃的client.completions.create()方法而不是正确的client.chat.completions.create()。API错误NotFoundError: /v1/completions not found for gpt-4oBug #2试图访问响应对象的.text属性但OpenAI SDK返回的聊天完成对象正确的属性是.message.content。属性错误AttributeError指示.text不存在。Bug #3给LLM的提示词中描述数据库有customers和products表但实际数据库是users和orders表。SQL执行错误no such table: customers配套的测试文件test_analyst.py不仅测试代码功能更关键的是使用MonocleValidator进行轨迹验证。这意味着即使代码能跑通但如果LLM没有被正确调用例如因为Bug #1导致没有生成预期的轨迹跨度测试也会失败。这实现了对AI应用“黑盒”内部行为的“白盒”验证。你可以随时运行python reset_demo.py将代码重置到最初的Bug状态方便反复实验。4. 自我修复智能体的实战演练环境就绪Bug就位现在让我们启动智能体观看它如何像一位老练的工程师一样独立完成“测试-诊断-修复”的闭环。4.1 配置智能体赋予其“侦探”的规则我们使用OpenCode智能体并通过一个自定义的Agent模式analyst_v3来赋予它特定的行为规则。这个配置文件通常位于.opencode/agents/analyst_v3.md是智能体行为的“宪法”其中最关键的部分是自我修复规则和约束条件。核心规则摘要测试先行首先运行测试套件客观记录所有失败。等待数据等待5秒确保轨迹数据已被Okahu Cloud接收和处理。证据查询通过Okahu MCP工具查询指定工作流text_to_sql_analyst_v3的最新轨迹。这是唯一允许的调试信息源。基于证据修复分析轨迹JSON定位错误根本原因并实施修复。版本存档每次修复前将当前代码存档到versions/目录下保留修改历史。记录溯源记录用于诊断的轨迹ID建立“问题-证据-修复”的可追溯链路。循环迭代重复步骤1-6直到所有测试通过。黄金约束“无猜测”原则如果无法从MCP获取到相关轨迹则立即停止并报告失败绝不允许在无证据的情况下猜测性修复。这条约束是防止智能体“幻觉”的防火墙。它强制智能体的每一个决策都必须有来自自身运行时产生的数据作为支撑从而保证修复动作的准确性和可靠性。4.2 触发自治循环从失败到成功的全自动旅程现在我们向配置好的analyst_v3智能体发出指令。这个提示词精心设计了任务步骤和边界analyst_v3 修复这个存在Bug的文本转SQL代码库。analyst.py、test_analyst.py和main.py文件已存在但包含错误。 1. 运行测试执行 pytest test_analyst.py -v 查看失败情况。 2. 分析轨迹等待5秒然后使用workflow_nametext_to_sql_analyst_v3查询Okahu MCP。 3. 修复循环 - 将当前analyst.py存档至versions/analyst_vN.py - 基于轨迹分析修复Bug - 记录用于诊断的每个轨迹ID - 再次运行测试 - 重复直至所有测试通过 4. 最终报告输出一个总结表格列出所有已修复的问题及其关联的轨迹ID。 规则不创建调试文件。仅通过Okahu MCP轨迹进行调试。始终调用MCP工具从轨迹获取日志不要使用终端里的本地日志。发出指令后你将看到一场完全自主的“外科手术”第一轮智能体运行测试发现3处失败。它等待5秒后查询MCP获得第一条错误轨迹清晰地显示NotFoundError: /v1/completions not found for gpt-4o。它立刻明白是API方法用错了于是将completions.create()改为chat.completions.create()存档代码为analyst_v1.py然后重新运行测试。第二轮测试显示仍有2处失败。智能体再次查询MCP看到新的轨迹中出现了AttributeError指出.text属性不存在。它检查OpenAI SDK文档或依靠其内部知识将其修正为.message.content存档为analyst_v2.py。第三轮还剩1处失败。再次查询MCP错误信息指向数据库层面no such table: customers。智能体对比轨迹中的SQL语句和提示词发现提示词中的表名customers/products与实际数据库users/orders不匹配。它更新提示词中的表名存档为analyst_v3.py。终局所有测试通过。智能体生成一份清晰的修复报告。整个过程中你没有阅读任何错误日志没有分析任何堆栈跟踪也没有给出任何一条具体的修复提示。智能体独自完成了所有工作。4.3 结果审查可审计的修复报告智能体最终输出的报告不是一句简单的“搞定”而是一份具备可审计性的工单修复序号问题描述诊断所用的轨迹ID1错误的OpenAI API调用方式trace_a1b2c3d4...2错误的响应对象属性访问trace_e5f6g7h8...3提示词与数据库Schema不匹配trace_i9j0k1l2...这份报告的价值在于可追溯任何一个人都可以拿着轨迹ID去Okahu平台搜索对应的原始轨迹亲眼看到导致修复的那个具体错误。可验证versions/目录下保存了每一次迭代的代码版本你可以逐行对比理解智能体的修改逻辑。可信任因为遵守了“无猜测”原则你知道每一个修复都有确凿的运行时证据支持而非随机尝试。至此人的角色发生了根本性转变从“调试操作员”变成了“系统监督员”。你负责设定规则、配置环境、触发任务和审计结果而将重复性、模式化的调试工作交给了自治系统。5. 关键要点与避坑指南通过这个完整的Demo我们不仅实现了一个技术原型更验证了几个对未来AI工程化至关重要的理念。以下是我在实践和复现过程中总结的核心要点和常见问题。5.1 成功构建自治系统的五大支柱自动埋点非可选而是必选项永远不要指望智能体或匆忙的开发者会在生成的代码里手动添加埋点。可观测性必须像电力一样成为即插即用的基础设施。Monocle这类零配置、自动注入的库是实现智能体自治的先决条件。在选择工具时务必确认其是否支持你使用的LLM SDK和框架。MCP是智能体的“感官接口”数据存在那里和智能体能消费这些数据是两回事。观测平台必须提供机器可读的API而不仅仅是人机交互界面。MCP协议正在成为这个领域的事实标准。在评估观测平台时除了看面板功能一定要考察其是否提供或计划提供MCP兼容的接口。用“无证据不行动”规则锁死幻觉这是最重要的设计原则。必须在智能体的行为准则中明确写入禁止在缺乏运行时遥测数据的情况下进行修复。可以通过在提示词中强调或是在Agent配置中作为硬性规则来实现。这能确保系统的输出是可靠和可解释的。测试要验证行为而不仅是输出对于AI应用传统的单元测试给定输入断言输出是不够的。因为输出具有非确定性。我们需要像Monocle Test Tools这样的“轨迹测试”它能验证“是否以正确的方式调用了LLM”、“是否触发了预期的工具”。这相当于对AI的“思考过程”进行断言能捕捉到更多深层Bug。人的角色升级从执行者到架构师当智能体接管了编码和调试人的核心价值就上移了。你需要更专注于设计智能体的行动规范和约束提示词工程、构建稳健的反馈循环测试与验证体系、以及配置和维护整个自治基础设施如MCP服务器、轨迹存储。这要求开发者具备更强的系统思维和架构能力。5.2 实操中常见的坑与解决方案问题1智能体无法连接到Okahu MCP服务器。排查首先检查.env文件中的OKAHU_API_KEY是否正确以及网络连接。最关键的一步是运行opencode mcp auth okahu完成MCP服务器的认证。这个命令会打开浏览器引导你完成OAuth授权流程。没有有效的认证后续的MCP查询都会失败。技巧可以将认证命令和密钥检查写入一个setup.sh脚本确保任何复现Demo的人都不会遗漏这一步。问题2运行测试后智能体查询MCP返回空数据或过时数据。原因轨迹数据从产生、导出、上传到云端可查询有数秒的延迟。如果智能体在测试结束后立即查询可能查不到。解决这就是为什么规则中明确要求“等待5秒”。这个等待时间需要根据你的网络延迟和Okahu的数据处理速度进行调整。在生产环境中可以考虑让智能体轮询MCP接口直到查询到非空数据为止实现更稳健的等待。问题3智能体试图安装不在允许列表中的依赖包。预防在Agent配置中明确列出allowed_packages。例如只允许安装monocle_apptrace, openai等必要包。对于Demo我们禁用了网络安装所有依赖都已预装。在生产中这能防止智能体引入不安全或不必要的依赖。处理如果遇到ModuleNotFoundError智能体应首先检查是否在允许列表中如果是则安装否则应抛出清晰错误而不是自行尝试安装未知包。问题4轨迹数据过于庞大智能体无法有效处理。优化在通过MCP查询时充分利用过滤参数。例如只查询最近5分钟、特定工作流名称、且状态为错误的轨迹。Okahu MCP API通常支持workflow_name,status,start_time,end_time等过滤器。让智能体学习构造精准的查询避免下载海量无关数据。问题5重置Demo后智能体似乎“记住”了之前的修复。原理这通常不是智能体“记忆”而是因为代码文件被重置了但智能体工作区或上下文里可能还残留着之前的对话历史。解决最干净的方式是开启一个新的智能体会话Session或者在使用OpenCode时确保提示词中包含了“忽略之前所有上下文仅基于当前文件状态操作”的指令。对于追求绝对可重复性的演示重启智能体进程是最可靠的方法。构建自我修复的智能体并非一蹴而就它需要你将可观测性提升到架构层面来考虑。这个Demo提供了一个完整的起点和经过验证的模式。接下来你可以尝试将其应用到更复杂的场景例如修复前端UI错误、优化数据库查询、甚至是根据性能轨迹进行代码重构。当你的智能体学会“自查自纠”时你就真正意义上解放了生产力迈向了一个人机协作的新阶段。
构建能自我修复的AI智能体：基于MCP协议与运行时轨迹的自动化调试实践
1. 项目概述构建能自我修复的AI智能体如果你正在尝试用AI智能体比如OpenCode、Cursor这类工具来帮你写代码那你一定遇到过这个场景智能体生成的代码跑不起来控制台里一堆红字错误然后你不得不像个翻译官一样把错误日志复制粘贴回去告诉它“这里错了改一下”。这个“写代码-报错-人工介入-再改”的循环始终没有真正闭合。智能体负责“写”而“调试”这个更烧脑的活儿依然牢牢攥在你手里。这个问题的核心在于智能体在运行时是“盲”的。它看不到自己执行时产生的痕迹——那些API调用、数据库查询、函数执行路径和抛出的异常。它只能根据你给的错误信息通常还是经过你筛选和转述的去猜测问题所在。这就像让一个医生在不看任何检查报告、只凭病人模糊的口述下诊断效率和准确性可想而知。那么有没有可能让智能体自己“看”到这些运行时信息自己诊断并修复问题呢答案是肯定的。这篇教程要分享的就是如何构建一个能“自我修复”的AI智能体。它不再是那个写完代码就撒手不管的“甩手掌柜”而是一个能主动运行测试、查询自己的运行轨迹、分析失败根因并最终修复Bug的“全栈工程师”。整个过程无需你阅读一行日志或手动给出修复提示。我们将通过一个具体的Demo来实现一个存在多处Bug的“文本转SQL”应用。当测试失败时我们的智能体会通过一个名为MCP的协议从云端观测平台查询自己刚刚产生的运行轨迹精准定位问题比如调错了API、读错了响应字段、表名对不上然后自动修复代码直到所有测试通过。整个技术栈的核心是三个开源工具Monocle用于自动埋点采集轨迹、Okahu Cloud用于存储和通过MCP协议暴露轨迹数据、以及支持MCP的OpenCode智能体。无论你是AI应用开发者、平台工程师还是对智能体自治能力感兴趣的探索者这套方案都能为你打开一扇新的大门让你看到下一代软件开发和运维的雏形。2. 核心思路与技术选型解析要实现智能体的自我修复关键在于打通“代码执行”与“运行时可观测性”之间的壁垒。传统的调试依赖于开发者在本地打断点、看日志但这套模式对智能体不适用。我们需要一套能让智能体以编程方式“感知”自身状态的基础设施。2.1 为什么是“轨迹”而不是“日志”首先我们要区分“日志”和“轨迹”。日志是离散的、文本化的记录需要人类去阅读理解。而轨迹是结构化的、带有上下文关联的调用链数据。一个典型的轨迹会记录一次LLM调用的输入输出和耗时、一次数据库查询的语句和结果、一次工具调用的参数和返回值以及这些操作之间的父子关系。对于智能体来说结构化的轨迹数据远比非结构化的日志文本更有价值。它可以直接被解析成JSON智能体可以像查询数据库一样精确地询问“最近一次名为generate_sql的工作流中哪个LLM调用失败了错误信息是什么” 这为基于证据的推理奠定了基础。2.2 技术栈深度拆解Monocle Okahu MCP我们的方案建立在两个核心组件之上它们分别解决了“数据采集”和“数据消费”的问题。Monocle零配置的自动埋点库它的价值主张极其简单一行代码开启全链路追踪。对于使用流行LLM SDK如OpenAI、LangChain、LlamaIndex的应用Monocle能自动注入埋点捕获每一次调用生成符合OpenTelemetry标准的轨迹数据。这意味着你不需要在智能体生成的每一段代码里手动添加打点逻辑——事实上你也做不到因为代码是动态生成的。Monocle的自动注入机制使得“可观测性”成为基础设施的一部分而非事后添加的负担。from monocle_apptrace import setup_monocle_telemetry # 这一行之后所有支持的SDK调用都会被自动追踪 setup_monocle_telemetry(workflow_nametext_to_sql_analyst)Okahu MCP为智能体设计的观测平台Okahu是一个云端的AI应用可观测性平台可以接收并存储来自Monocle的轨迹数据。但它的关键创新在于对MCP的支持。MCP是一个新兴的开放协议旨在为AI智能体提供标准化的数据源访问接口。你可以把它理解为智能体世界的“API网关”或“驱动程序”。传统的观测平台提供的是给人看的Dashboard充满了图表和可点击的界面。智能体无法与这些界面交互。Okahu通过MCP将同样的轨迹数据以结构化的JSON API形式暴露出来。智能体只需要像调用一个普通函数一样请求/okahu:get_latest_traces就能获取到分析问题所需的一切信息。这实现了从“Human-in-the-loop”到“Agent-in-the-loop”的范式转变。2.3 方案优势与设计考量选择这个组合主要基于以下几点考量对生成式代码友好Monocle的自动埋点不依赖预定义的代码结构完美适配智能体动态生成代码的特性。闭环反馈MCP协议提供了低延迟、程序化的数据访问通道使得“执行-观测-决策-修复”这个循环可以在秒级内完成。证据驱动避免幻觉我们为智能体设定了一条核心规则“无轨迹不修复”。智能体必须依据从MCP获取的具体错误轨迹来制定修复方案而不能基于训练数据中的普遍知识进行猜测。这极大地减少了智能体“一本正经地胡说八道”提出错误修复方案的风险。轻量集成整个方案对现有代码的侵入性极低。主要配置集中在环境变量和智能体的提示词工程上业务逻辑代码几乎不受影响。3. 环境搭建与核心组件配置理论讲完了我们动手把环境搭起来。这个Demo的所有代码都是开源的你可以完全复现。请确保你的系统已安装Python 3.10或更高版本。3.1 前期准备与依赖安装首先克隆项目仓库并创建独立的Python虚拟环境这是一个好习惯可以避免包依赖冲突。git clone https://github.com/Arindam200/awesome-ai-apps cd awesome-ai-apps/mcp_ai_agents/telemetry-mcp-okahu python3 -m venv venv source venv/bin/activate # Windows系统请使用 venv\Scripts\activate接下来安装核心的Python依赖包。这些包涵盖了轨迹采集、测试验证、AI模型调用和Web服务。pip install monocle_apptrace monocle_test_tools openai fastapi pytest python-dotenvmonocle_apptrace: 核心的自动埋点库。monocle_test_tools: 基于轨迹的测试验证框架它能验证“是否产生了正确的轨迹”而不仅仅是“代码是否运行”。openai: 调用GPT-4o等模型的官方SDK。fastapipytest: 用于构建Demo应用和运行测试。python-dotenv: 管理环境变量。3.2 密钥配置与数据初始化这个Demo需要两个关键的API密钥OpenAI API Key用于调用GPT-4o模型生成SQL。Okahu API Key用于将轨迹数据发送到Okahu云端并通过MCP查询。在项目根目录下创建一个名为.env的文件填入你的密钥# .env 文件内容 OPENAI_API_KEYsk-your-openai-key-here OPENAI_MODELgpt-4o OKAHU_API_KEYyour-okahu-key-here MONOCLE_EXPORTERokahu关键配置解析MONOCLE_EXPORTERokahu这一行至关重要。它指示Monocle库将采集到的轨迹数据直接发送到Okahu Cloud而不是输出到本地控制台。在我们的Demo中我们会故意屏蔽所有本地日志输出从而强制智能体必须通过查询Okahu MCP来获取调试信息模拟生产环境下的真实场景。最后运行数据库初始化脚本创建一个包含users和orders表的SQLite数据库这是我们文本转SQL应用将要查询的对象。python setup_db.py3.3 理解预设的Bug与测试套件为了演示的确定性和可重复性Demo中预置了一个存在三个故意引入Bug的analyst.py文件。这三个Bug涵盖了从API使用错误到业务逻辑错误的典型场景Bug编号问题描述在轨迹中会看到什么Bug #1使用了已废弃的client.completions.create()方法而不是正确的client.chat.completions.create()。API错误NotFoundError: /v1/completions not found for gpt-4oBug #2试图访问响应对象的.text属性但OpenAI SDK返回的聊天完成对象正确的属性是.message.content。属性错误AttributeError指示.text不存在。Bug #3给LLM的提示词中描述数据库有customers和products表但实际数据库是users和orders表。SQL执行错误no such table: customers配套的测试文件test_analyst.py不仅测试代码功能更关键的是使用MonocleValidator进行轨迹验证。这意味着即使代码能跑通但如果LLM没有被正确调用例如因为Bug #1导致没有生成预期的轨迹跨度测试也会失败。这实现了对AI应用“黑盒”内部行为的“白盒”验证。你可以随时运行python reset_demo.py将代码重置到最初的Bug状态方便反复实验。4. 自我修复智能体的实战演练环境就绪Bug就位现在让我们启动智能体观看它如何像一位老练的工程师一样独立完成“测试-诊断-修复”的闭环。4.1 配置智能体赋予其“侦探”的规则我们使用OpenCode智能体并通过一个自定义的Agent模式analyst_v3来赋予它特定的行为规则。这个配置文件通常位于.opencode/agents/analyst_v3.md是智能体行为的“宪法”其中最关键的部分是自我修复规则和约束条件。核心规则摘要测试先行首先运行测试套件客观记录所有失败。等待数据等待5秒确保轨迹数据已被Okahu Cloud接收和处理。证据查询通过Okahu MCP工具查询指定工作流text_to_sql_analyst_v3的最新轨迹。这是唯一允许的调试信息源。基于证据修复分析轨迹JSON定位错误根本原因并实施修复。版本存档每次修复前将当前代码存档到versions/目录下保留修改历史。记录溯源记录用于诊断的轨迹ID建立“问题-证据-修复”的可追溯链路。循环迭代重复步骤1-6直到所有测试通过。黄金约束“无猜测”原则如果无法从MCP获取到相关轨迹则立即停止并报告失败绝不允许在无证据的情况下猜测性修复。这条约束是防止智能体“幻觉”的防火墙。它强制智能体的每一个决策都必须有来自自身运行时产生的数据作为支撑从而保证修复动作的准确性和可靠性。4.2 触发自治循环从失败到成功的全自动旅程现在我们向配置好的analyst_v3智能体发出指令。这个提示词精心设计了任务步骤和边界analyst_v3 修复这个存在Bug的文本转SQL代码库。analyst.py、test_analyst.py和main.py文件已存在但包含错误。 1. 运行测试执行 pytest test_analyst.py -v 查看失败情况。 2. 分析轨迹等待5秒然后使用workflow_nametext_to_sql_analyst_v3查询Okahu MCP。 3. 修复循环 - 将当前analyst.py存档至versions/analyst_vN.py - 基于轨迹分析修复Bug - 记录用于诊断的每个轨迹ID - 再次运行测试 - 重复直至所有测试通过 4. 最终报告输出一个总结表格列出所有已修复的问题及其关联的轨迹ID。 规则不创建调试文件。仅通过Okahu MCP轨迹进行调试。始终调用MCP工具从轨迹获取日志不要使用终端里的本地日志。发出指令后你将看到一场完全自主的“外科手术”第一轮智能体运行测试发现3处失败。它等待5秒后查询MCP获得第一条错误轨迹清晰地显示NotFoundError: /v1/completions not found for gpt-4o。它立刻明白是API方法用错了于是将completions.create()改为chat.completions.create()存档代码为analyst_v1.py然后重新运行测试。第二轮测试显示仍有2处失败。智能体再次查询MCP看到新的轨迹中出现了AttributeError指出.text属性不存在。它检查OpenAI SDK文档或依靠其内部知识将其修正为.message.content存档为analyst_v2.py。第三轮还剩1处失败。再次查询MCP错误信息指向数据库层面no such table: customers。智能体对比轨迹中的SQL语句和提示词发现提示词中的表名customers/products与实际数据库users/orders不匹配。它更新提示词中的表名存档为analyst_v3.py。终局所有测试通过。智能体生成一份清晰的修复报告。整个过程中你没有阅读任何错误日志没有分析任何堆栈跟踪也没有给出任何一条具体的修复提示。智能体独自完成了所有工作。4.3 结果审查可审计的修复报告智能体最终输出的报告不是一句简单的“搞定”而是一份具备可审计性的工单修复序号问题描述诊断所用的轨迹ID1错误的OpenAI API调用方式trace_a1b2c3d4...2错误的响应对象属性访问trace_e5f6g7h8...3提示词与数据库Schema不匹配trace_i9j0k1l2...这份报告的价值在于可追溯任何一个人都可以拿着轨迹ID去Okahu平台搜索对应的原始轨迹亲眼看到导致修复的那个具体错误。可验证versions/目录下保存了每一次迭代的代码版本你可以逐行对比理解智能体的修改逻辑。可信任因为遵守了“无猜测”原则你知道每一个修复都有确凿的运行时证据支持而非随机尝试。至此人的角色发生了根本性转变从“调试操作员”变成了“系统监督员”。你负责设定规则、配置环境、触发任务和审计结果而将重复性、模式化的调试工作交给了自治系统。5. 关键要点与避坑指南通过这个完整的Demo我们不仅实现了一个技术原型更验证了几个对未来AI工程化至关重要的理念。以下是我在实践和复现过程中总结的核心要点和常见问题。5.1 成功构建自治系统的五大支柱自动埋点非可选而是必选项永远不要指望智能体或匆忙的开发者会在生成的代码里手动添加埋点。可观测性必须像电力一样成为即插即用的基础设施。Monocle这类零配置、自动注入的库是实现智能体自治的先决条件。在选择工具时务必确认其是否支持你使用的LLM SDK和框架。MCP是智能体的“感官接口”数据存在那里和智能体能消费这些数据是两回事。观测平台必须提供机器可读的API而不仅仅是人机交互界面。MCP协议正在成为这个领域的事实标准。在评估观测平台时除了看面板功能一定要考察其是否提供或计划提供MCP兼容的接口。用“无证据不行动”规则锁死幻觉这是最重要的设计原则。必须在智能体的行为准则中明确写入禁止在缺乏运行时遥测数据的情况下进行修复。可以通过在提示词中强调或是在Agent配置中作为硬性规则来实现。这能确保系统的输出是可靠和可解释的。测试要验证行为而不仅是输出对于AI应用传统的单元测试给定输入断言输出是不够的。因为输出具有非确定性。我们需要像Monocle Test Tools这样的“轨迹测试”它能验证“是否以正确的方式调用了LLM”、“是否触发了预期的工具”。这相当于对AI的“思考过程”进行断言能捕捉到更多深层Bug。人的角色升级从执行者到架构师当智能体接管了编码和调试人的核心价值就上移了。你需要更专注于设计智能体的行动规范和约束提示词工程、构建稳健的反馈循环测试与验证体系、以及配置和维护整个自治基础设施如MCP服务器、轨迹存储。这要求开发者具备更强的系统思维和架构能力。5.2 实操中常见的坑与解决方案问题1智能体无法连接到Okahu MCP服务器。排查首先检查.env文件中的OKAHU_API_KEY是否正确以及网络连接。最关键的一步是运行opencode mcp auth okahu完成MCP服务器的认证。这个命令会打开浏览器引导你完成OAuth授权流程。没有有效的认证后续的MCP查询都会失败。技巧可以将认证命令和密钥检查写入一个setup.sh脚本确保任何复现Demo的人都不会遗漏这一步。问题2运行测试后智能体查询MCP返回空数据或过时数据。原因轨迹数据从产生、导出、上传到云端可查询有数秒的延迟。如果智能体在测试结束后立即查询可能查不到。解决这就是为什么规则中明确要求“等待5秒”。这个等待时间需要根据你的网络延迟和Okahu的数据处理速度进行调整。在生产环境中可以考虑让智能体轮询MCP接口直到查询到非空数据为止实现更稳健的等待。问题3智能体试图安装不在允许列表中的依赖包。预防在Agent配置中明确列出allowed_packages。例如只允许安装monocle_apptrace, openai等必要包。对于Demo我们禁用了网络安装所有依赖都已预装。在生产中这能防止智能体引入不安全或不必要的依赖。处理如果遇到ModuleNotFoundError智能体应首先检查是否在允许列表中如果是则安装否则应抛出清晰错误而不是自行尝试安装未知包。问题4轨迹数据过于庞大智能体无法有效处理。优化在通过MCP查询时充分利用过滤参数。例如只查询最近5分钟、特定工作流名称、且状态为错误的轨迹。Okahu MCP API通常支持workflow_name,status,start_time,end_time等过滤器。让智能体学习构造精准的查询避免下载海量无关数据。问题5重置Demo后智能体似乎“记住”了之前的修复。原理这通常不是智能体“记忆”而是因为代码文件被重置了但智能体工作区或上下文里可能还残留着之前的对话历史。解决最干净的方式是开启一个新的智能体会话Session或者在使用OpenCode时确保提示词中包含了“忽略之前所有上下文仅基于当前文件状态操作”的指令。对于追求绝对可重复性的演示重启智能体进程是最可靠的方法。构建自我修复的智能体并非一蹴而就它需要你将可观测性提升到架构层面来考虑。这个Demo提供了一个完整的起点和经过验证的模式。接下来你可以尝试将其应用到更复杂的场景例如修复前端UI错误、优化数据库查询、甚至是根据性能轨迹进行代码重构。当你的智能体学会“自查自纠”时你就真正意义上解放了生产力迈向了一个人机协作的新阶段。
