Agent 开发调试工具链单步执行、变量观察与调用栈追踪Agent 出错了你只知道结果不对——没有单步执行和变量观察调试 Agent 就像盲修电路。一、场景痛点你的 Agent 执行了 5 个步骤后输出结果结果明显不对。你查了日志只有每个步骤的名称和状态——步骤 3 失败。但步骤 3 调用了哪个工具、传了什么参数、返回了什么错误日志里全没有。你只能猜测问题在哪然后加更多 print 语句重新跑一遍——这和传统调试的区别是Agent 的每次执行消耗 token花钱调试一次就是一笔费用。更糟的是多步骤 Agent 的依赖链步骤 3 的输入来自步骤 2 的输出步骤 2 的输出来自步骤 1。如果步骤 1 的输出格式有偏差比如返回了一个带空格的 JSON步骤 2 解析时静默失败步骤 3 用了步骤 2 的错误默认值最终结果不对——但错误源头在步骤 1不是步骤 3。核心矛盾Agent 调试需要调用栈追踪——知道每个步骤的输入从哪来、输出到哪去、中间变量是什么。但 Agent 的日志通常只记录做了什么不记录为什么这样做。二、底层机制与原理剖析2.1 Agent 调试的三层工具2.2 调用栈追踪的数据结构每次 Agent 执行产生一个调用栈记录step_id步骤标识parent_step_id上游步骤标识输入来源tool_name调用的工具名称input_snapshot输入变量的完整快照output_snapshot输出变量的完整快照error_detail错误详情如果有duration_ms步骤耗时token_usagetoken 消耗调用栈追踪的核心能力从任何失败步骤追溯到第一个引入偏差的步骤。偏差定义实际输出与期望输出的差异超过阈值。三、生产级代码实现3.1 调用栈追踪器// agent-debugger.ts —— Agent 调试工具链核心 import { EventEmitter } from events; import { v4 as uuidv4 } from uuid; export interface StepRecord { stepId: string; parentStepId: string | null; toolName: string; inputSnapshot: Recordstring, unknown; outputSnapshot: Recordstring, unknown | null; errorDetail: string | null; durationMs: number; tokenUsage: { input: number; output: number } | null; timestamp: string; status: success | failure | skipped; } export interface Breakpoint { stepName: string; // 在哪个步骤暂停 condition?: string; // 暂停条件比如 input.params.id null action: pause | inspect | modify; modifiedValues?: Recordstring, unknown; // 暂停时手动修改的变量值 } export class AgentDebugger extends EventEmitter { private callStack: StepRecord[] []; private breakpoints: Mapstring, Breakpoint new Map(); private pausedAt: string | null null; private contextStore: Mapstring, Recordstring, unknown new Map(); /** 记录步骤执行构建调用栈 */ recordStep(record: StepRecord): void { this.callStack.push(record); // 存储步骤输出的上下文后续步骤的输入来源 if (record.outputSnapshot) { this.contextStore.set(record.stepId, record.outputSnapshot); } // 发布调试事件外部工具可以订阅做可视化 this.emit(step:recorded, record); } /** 获取完整调用栈按时间顺序排列 */ getCallStack(): StepRecord[] { return [...this.callStack]; } /** 回溯错误源头从失败步骤追溯到第一个出错的步骤 */ tracebackError(failedStepId: string): StepRecord[] { const failedStep this.callStack.find((r) r.stepId failedStepId); if (!failedStep) return []; // 从失败步骤的 parent 开始逐级回溯 // 检查每个步骤的输出是否有偏差 const errorChain: StepRecord[] [failedStep]; let currentParentId failedStep.parentStepId; while (currentParentId) { const parentStep this.callStack.find((r) r.stepId currentParentId); if (!parentStep) break; // 检查 parent 的输出是否有问题 // 如果 parent 的输出包含 null 值或格式不匹配标记为偏差 if (this.hasDeviation(parentStep)) { errorChain.unshift(parentStep); } currentParentId parentStep.parentStepId; } return errorChain; } /** 检查步骤输出是否有偏差 */ private hasDeviation(step: StepRecord): boolean { if (!step.outputSnapshot) return true; // 无输出 偏差 if (step.errorDetail) return true; // 有错误 偏差 // 检查输出中的 null 值关键变量不应该为 null const criticalFields [result, data, response]; for (const field of criticalFields) { if (step.outputSnapshot[field] null || step.outputSnapshot[field] undefined) { return true; } } return false; } /** 设置断点在指定步骤暂停执行 */ setBreakpoint(stepName: string, breakpoint: Breakpoint): void { this.breakpoints.set(stepName, breakpoint); } /** 检查是否需要在当前步骤暂停 */ shouldPause(stepName: string, inputContext: Recordstring, unknown): boolean { const bp this.breakpoints.get(stepName); if (!bp) return false; // 检查暂停条件条件表达式评估 if (bp.condition) { try { // 安全评估只支持简单的属性访问和比较 const expr bp.condition; // 替换变量名为实际值 const evaluated this.evaluateCondition(expr, inputContext); return evaluated true; } catch { return true; // 条件解析失败时默认暂停保守策略 } } return true; // 无条件断点总是暂停 } /** 在断点处修改变量值验证修复假设 */ applyBreakpointModification( stepName: string, currentContext: Recordstring, unknown ): Recordstring, unknown { const bp this.breakpoints.get(stepName); if (!bp || !bp.modifiedValues) return currentContext; // 合并修改值覆盖当前上下文中的指定字段 // 修改只在当前执行中生效不影响后续执行 return { ...currentContext, ...bp.modifiedValues }; } /** 生成调试报告人类可读的调用栈摘要 */ generateDebugReport(): string { const lines: string[] []; lines.push( Agent Debug Report ); lines.push(Total steps: ${this.callStack.length}); lines.push(Failed steps: ${this.callStack.filter((r) r.status failure).length}); lines.push(); for (const step of this.callStack) { const statusIcon step.status success ? ✅ : step.status failure ? ❌ : ⏭; lines.push(${statusIcon} Step: ${step.stepId} (${step.toolName})); lines.push( Parent: ${step.parentStepId ?? root}); lines.push( Duration: ${step.durationMs}ms); if (step.inputSnapshot) { // 输入摘要只展示关键字段不展示完整数据 const inputKeys Object.keys(step.inputSnapshot); lines.push( Input keys: ${inputKeys.join(, )}); // 检查 null 值输入中的 null 可能是问题源头 const nullKeys inputKeys.filter( (k) step.inputSnapshot[k] null || step.inputSnapshot[k] undefined ); if (nullKeys.length 0) { lines.push( ⚠️ Null input keys: ${nullKeys.join(, )}); } } if (step.errorDetail) { lines.push( Error: ${step.errorDetail}); } lines.push(); } // 错误链追踪 const failedSteps this.callStack.filter((r) r.status failure); if (failedSteps.length 0) { lines.push( Error Traceback ); for (const failed of failedSteps) { const chain this.tracebackError(failed.stepId); lines.push(Error at: ${failed.stepId}); lines.push(Traceback chain: ${chain.map((s) s.stepId).join( → )}); lines.push(); } } return lines.join(\n); } /** 条件表达式评估简化版 */ private evaluateCondition(expr: string, context: Recordstring, unknown): boolean { // 只支持简单的 key value 和 key ! value 表达式 const eqMatch expr.match(/^(\w)\s*\s*(.)$/); const neqMatch expr.match(/^(\w)\s*!\s*(.)$/); if (eqMatch) { const key eqMatch[1]; const expectedValue eqMatch[2].replace(/[]/g, ); const actualValue String(context[key] ?? ); return actualValue expectedValue; } if (neqMatch) { const key neqMatch[1]; const expectedValue neqMatch[2].replace(/[]/g, ); const actualValue String(context[key] ?? ); return actualValue ! expectedValue; } // null 检查key null / key ! null const nullMatch expr.match(/^(\w)\s*(|!)\s*null$/); if (nullMatch) { const key nullMatch[1]; const operator nullMatch[2]; const isNull context[key] null || context[key] undefined; return operator ? isNull : !isNull; } return false; } }3.2 带调试能力的 Agent 执行引擎// debuggable-agent.ts —— 支持单步调试的 Agent 执行引擎 export class DebuggableAgentExecutor { private debugger: AgentDebugger; private steps: Mapstring, StepHandler new Map(); constructor(debugger: AgentDebugger) { this.debugger debugger; } /** 执行 Agent 链路支持断点暂停 */ async executeWithDebug( initialInput: Recordstring, unknown, stepOrder: string[] ): Promise{ result: Recordstring, unknown; debugReport: string } { let currentContext initialInput; let parentStepId: string | null null; for (const stepName of stepOrder) { const handler this.steps.get(stepName); if (!handler) continue; // 检查断点是否需要在当前步骤暂停 if (this.debugger.shouldPause(stepName, currentContext)) { // 暂停等待调试器指令继续执行或修改变量 // 在 CLI 环境中暂停 等待用户输入 // 在 UI 环境中暂停 高亮当前步骤等待点击 this.debugger.emit(step:paused, { stepName, context: currentContext }); // 应用断点修改用户可能在暂停时修改了变量值 currentContext this.debugger.applyBreakpointModification(stepName, currentContext); } const stepId uuidv4(); const startTime Date.now(); // 记录输入快照步骤执行前的完整上下文 const inputSnapshot { ...currentContext }; try { const output await handler.handle(currentContext); const durationMs Date.now() - startTime; // 记录步骤成功 this.debugger.recordStep({ stepId, parentStepId, toolName: stepName, inputSnapshot, outputSnapshot: output, errorDetail: null, durationMs, tokenUsage: handler.getTokenUsage?.() ?? null, timestamp: new Date().toISOString(), status: success, }); // 更新上下文步骤输出作为下一步的输入 currentContext { ...currentContext, ...output }; parentStepId stepId; } catch (err) { const durationMs Date.now() - startTime; // 记录步骤失败 this.debugger.recordStep({ stepId, parentStepId, toolName: stepName, inputSnapshot, outputSnapshot: null, errorDetail: err instanceof Error ? err.message : String(err), durationMs, tokenUsage: null, timestamp: new Date().toISOString(), status: failure, }); // 失败后中断链路不再执行后续步骤 break; } } // 生成调试报告 const debugReport this.debugger.generateDebugReport(); return { result: currentContext, debugReport }; } }四、边界分析与架构权衡4.1 调试开销每个步骤记录输入输出快照会增加内存占用和存储量。一个 5 步骤的 Agent每步的快照约 10KB总共 50KB——可接受。但 20 步骤的 Agent每步快照 50KB包含大型 JSON 结果总快照 1MB。对策快照截断策略——超过 5KB 的输出只保留摘要key 列表 前 200 字符。完整数据存到对象存储快照只存引用路径。4.2 单步执行的交互成本CLI 环境中的断点暂停需要用户手动输入继续或修改变量。UI 环境中需要可视化界面展示步骤状态和变量值。如果团队没有调试 UI单步执行的实际使用频率很低。4.3 适用边界与禁用场景适用多步骤 Agent≥5 步、步骤间有数据依赖、错误频率较高需要反复调试禁用单步骤 Agent调用栈只有一个步骤、实时交互 Agent暂停等待不可接受、生产环境调试工具只在开发环境启用4.4 与 LangSmith 的对比LangSmith 是 LangChain 的调试平台提供了步骤追踪、输入输出记录、时间线可视化。功能比本文的自建调试器更完整但它是 SaaS 服务数据存到 LangSmith 的服务器——如果你的 Agent 数据有隐私要求不能用 LangSmith。五、结语Agent 调试需要三层工具调用栈追踪记录每个步骤的输入来源和输出去向、变量观察快照每个步骤的中间值、单步执行在指定步骤暂停检查状态。调用栈追踪的核心能力是回溯错误源头——从失败步骤逐级追溯到第一个引入偏差的步骤。断点机制支持条件暂停比如输入参数为 null 时暂停和变量修改暂停时手动修改值验证假设。调试只在开发环境启用生产环境关闭断点和快照记录。快照数据做截断处理大结果只保留摘要。
