智能体执行追踪_agent-tracing

发布时间:2026/11/19 22:48:39
智能体执行追踪_agent-tracing 以下为本文档的中文说明agent-tracing智能体追踪是LobeHub开发的一款零配置本地开发工具用于记录和检查AI智能体的执行快照。它通过CLI命令行界面提供对智能体每一步执行的细粒度洞察。在开发模式下AgentRuntimeService.executeStep()方法会自动将每一步执行记录为部分快照partial snapshots存储在.agent-tracing目录中当操作完成时这些部分快照会被合并为一个完整的ExecutionSnapshot JSON文件。该技能的数据流设计精巧执行步骤循环构建StepPresentationData写入部分快照到磁盘完成时最终化为时间戳加追踪ID命名的JSON文件。它会同时捕获上下文引擎数据包括agentDocuments、systemRole等重型负载这些数据通过旁路通道传递不进入Redis状态管道从而避免性能瓶颈。CLI提供了丰富的查看命令inspect查看追踪概览list列出所有快照并支持按步骤查看消息(-m)、工具调用(-t)、原始事件(-e)、运行时上下文(-c)等。开发者还可以使用–payload(-p)查看上下文引擎输入概览使用–memory(-M)查看注入的用户记忆。该技能特别适合调试复杂的多步骤AI智能体系统帮助开发者理解LLM的输入输出、工具调用流程和上下文引擎的工作方式。它提供了从原始数据到格式化输出的完整调试链路是智能体应用开发中不可或缺的诊断工具。Agent Tracing CLI Guidelobechat/agent-tracingis a zero-config local dev tool that records agent execution snapshots to disk and provides a CLI to inspect them.How It WorksInNODE_ENVdevelopment,AgentRuntimeService.executeStep()automatically records each step to.agent-tracing/as partial snapshots. When the operation completes, the partial is finalized into a completeExecutionSnapshotJSON file.Data flow: executeStep loop - buildStepPresentationData- write partial snapshot to disk - on completion, finalize to.agent-tracing/{timestamp}_{traceId}.jsonContext engine capture: InRuntimeExecutors.ts, thecall_llmexecutor callsctx.tracingContextEngine(input, output)afterserverMessagesEngine()processes messages.AgentRuntimeService.executeStepbuffers the call per step and forwards it toOperationTraceRecorder.appendStepas the typedcontextEnginefield. CE flows through this side channel rather than theeventsarray so its heavy payload (agentDocuments, systemRole, …) never enters the Redis state pipeline (LOBE-9110).Package Locationpackages/agent-tracing/ src/ types.ts # ExecutionSnapshot, StepSnapshot, SnapshotSummary store/ types.ts # ISnapshotStore interface file-store.ts # FileSnapshotStore (.agent-tracing/*.json) recorder/ index.ts # appendStepToPartial(), finalizeSnapshot() viewer/ index.ts # Terminal rendering: renderSnapshot, renderStepDetail, renderMessageDetail, renderSummaryTable, renderPayload, renderPayloadTools, renderMemory cli/ index.ts # CLI entry point (#!/usr/bin/env bun) inspect.ts # Inspect command (default) partial.ts # Partial snapshot commands (list, inspect, clean) index.ts # Barrel exportsData StorageCompleted snapshots:.agent-tracing/{ISO-timestamp}_{traceId-short}.jsonLatest symlink:.agent-tracing/latest.jsonIn-progress partials:.agent-tracing/_partial/{operationId}.jsonFileSnapshotStoreresolves fromprocess.cwd()—run CLI from the repo rootCLI CommandsAll commands run from therepo root:# View latest trace (tree overview, inspect is the default command)agent-tracing agent-tracing inspect agent-tracing inspecttraceIdagent-tracing inspect latest# List recent snapshotsagent-tracing list agent-tracing list-l20# Inspect specific step (-s is short for --step)agent-tracing inspecttraceId-s0# View messages (-m is short for --messages)agent-tracing inspecttraceId-s0-m# View full content of a specific message (by index shown in -m output)agent-tracing inspecttraceId-s0--msg2agent-tracing inspecttraceId-s0--msg-input1# View tool call/result details (-t is short for --tools)agent-tracing inspecttraceId-s1-t# View raw events (-e is short for --events)agent-tracing inspecttraceId-s0-e# View runtime context (-c is short for --context)agent-tracing inspecttraceId-s0-c# View context engine input overview (-p is short for --payload)agent-tracing inspecttraceId-pagent-tracing inspecttraceId-s0-p# View available tools in payload (-T is short for --payload-tools)agent-tracing inspecttraceId-Tagent-tracing inspecttraceId-s0-T# View user memory (-M is short for --memory)agent-tracing inspecttraceId-Magent-tracing inspecttraceId-s0-M# Raw JSON output (-j is short for --json)agent-tracing inspecttraceId-jagent-tracing inspecttraceId-s0-j# List in-progress partial snapshotsagent-tracing partial list# Inspect a partial (use inspect directly — all flags work with partial IDs)agent-tracing inspectpartialOperationIdagent-tracing inspectpartialOperationId-Tagent-tracing inspectpartialOperationId-p# Clean up stale partial snapshotsagent-tracing partial cleanInspect Flag Reference| Flag | Short | Description| Default Step || ----------------- | ----- | ------------------------------------------------------------------------------------------------- | ------------ ||--step n|-s| Target a specific step | — ||--messages|-m| Messages context (CE input → params → LLM payload) | — ||--tools|-t| Tool calls results (what agent invoked) | — ||--events|-e| Raw events (llm_start, llm_result, etc.) | — ||--context|-c| Runtime context payload (raw) | — ||--system-role|-r| Full system role content | 0 ||--env| | Environment context | 0 ||--payload|-p| Context engine input overview (model, knowledge, tools summary, memory summary, platform context) | 0 ||--payload-tools|-T| Available tools detail (plugin manifests LLM function definitions) | 0 ||--memory|-M| Full user memory (persona, identity, contexts, preferences, experiences) | 0 ||--diff n|-d| Diff against step N (use with-ror--env) | — ||--msg n| | Full content of message N from Final LLM Payload | — ||--msg-input n| | Full content of message N from Context Engine Input | — ||--json|-j| Output as JSON (combinable with any flag above) | — |Flags marked “Default Step: 0” auto-select step 0 if--stepis not provided. All flags supportlatestor omitted traceId.Typical Debug Workflow# 1. Trigger an agent operation in the dev UI# 2. See the overviewagent-tracing inspect# 3. List all traces, get traceIdagent-tracing list# 4. Quick overview of what was fed into context engineagent-tracing inspect-p# 5. Inspect a specific steps messages to see what was sent to the LLMagent-tracing inspect TRACE_ID-s0-m# 6. Drill into a truncated message for full contentagent-tracing inspect TRACE_ID-s0--msg2# 7. Check available tools vs actual tool callsagent-tracing inspect-T# available toolsagent-tracing inspect-s1-t# actual tool calls results# 8. Inspect user memory injected into the conversationagent-tracing inspect-M# 9. Diff system role between steps (multi-step agents)agent-tracing inspect TRACE_ID-r-d2Key TypesinterfaceExecutionSnapshot{traceId:string;operationId:string;model?:string;provider?:string;startedAt:number;completedAt?:number;completionReason?:|done|error|interrupted|max_steps|cost_limit|waiting_for_human;totalSteps:number;totalTokens:number;totalCost:number;error?:{type:string;message:string};steps:StepSnapshot[];}interfaceStepSnapshot{stepIndex:number;stepType:call_llm|call_tool;executionTimeMs:number;content?:string;// LLM outputreasoning?:string;// Reasoning/thinkinginputTokens?:number;outputTokens?:number;toolsCalling?:Array{apiName:string;identifier:string;arguments?:string};toolsResult?:Array{apiName:string;identifier:string;isSuccess?:boolean;output?:string;};messages?:any[];// DB messagesbefore step context?:{phase:string;payload?:unknown;stepContext?:unknown};events?:Array{type:string;[key:string]:unknown};contextEngine?:{input?:unknown;// contextEngineInput minus messages toolsConfig (reconstructible from baseline)output?:unknown;// processed messages array (final LLM payload)};}–messages Output StructureWhen using--messages, the output shows three sections (if context engine data is available):Context Engine Input— DB messages passed to the engine, with[0],[1], … indices. Use--msg-input Nto view full content.Context Engine Params— systemRole, model, provider, knowledge, tools, userMemory, etc.Final LLM Payload— Processed messages after context engine (system date injection, user memory, history truncation, etc.), with[0],[1], … indices. Use--msg Nto view full content.Integration PointsRecording:apps/server/src/services/agentRuntime/AgentRuntimeService.ts— in theexecuteStep()method, after buildingstepPresentationData, writes partial snapshot in dev modeContext engine capture:apps/server/src/modules/AgentRuntime/RuntimeExecutors.ts— incall_llmexecutor, afterserverMessagesEngine()returns, callsctx.tracingContextEngine(input, output).AgentRuntimeService.executeStepbuffers it per step and passes it totraceRecorder.appendStepas the typedcontextEnginefield (kept off theeventsarray to stay out of Redis state).Store:FileSnapshotStorereads/writes to.agent-tracing/relative toprocess.cwd()3d:[“,,,L40”,null,{“content”:“$41”,“frontMatter”:{“name”:“agent-tracing”,“description”:“Agent tracing CLI for execution snapshots. Use for agent-tracing, traces, snapshots, LLM call inspection, context engine data, agent step analysis, or execution debugging.”,“user-invocable”:false}}]3e:[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[[”,“div”,null,{“className”:“flex items-center justify-between border-b border-border bg-muted/30 px-4 py-2.5”,“children”:[[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[”,“span”,null,{“className”:“truncate text-xs font-medium text-muted-foreground”,“children”:“同仓库更多 Skills”}]}],[“KaTeX parse error: Expected EOF, got } at position 88: …ldren:同仓库}]]}̲],[”,“div”,null,{“className”:“p-4 sm:p-5”,“children”:[[“,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[,h2,null,{id:related-skills-heading,className:text-2xl font-semibold tracking-normal text-foreground,children:同仓库更多 Skills}],[,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[”,“div”,null,{“className”:“mt-4 grid gap-3 sm:grid-cols-2”,“children”:[“L42,L42,L42,L43”,“L44,L44,L44,L45”,“L46,L46,L46,L47”]}]]}]]}]48:I[206516,[“/_next/static/chunks/051aanbhrv4br.js”,“/_next/static/chunks/0mizr60h7ayzt.js”,“/_next/static/chunks/0v9lm1dmbdoo-.js”,“/_next/static/chunks/0rxr1j1j3j-.r.js”,“/_next/static/chunks/02ftybezfvqjd.js”,“/_next/static/chunks/0.v9ksvnnj8ia.js”,“/_next/static/chunks/0bn6id96nx3k.js,“/_next/static/chunks/13ybnhn37c.tc.js”,“/_next/static/chunks/0_fnrdtruz8uf.js”,“/_next/static/chunks/0r6l15utt1mwb.js”,“/_next/static/chunks/0dm9a5into854.js”,/_next/static/chunks/07k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]

关于本文作者

来自尧图内容编辑团队

尧图内容编辑团队 内容团队

尧图内容编辑团队

本文由尧图网络内容编辑团队执笔。团队由资深项目经理、前端工程师与设计师组成,所有内容均来自亲手交付的真实项目,先讲清问题、再给出可落地的解法。尧图深耕北京网站建设十年,服务过京华建材集团、智造科技等各行业客户,把一线经验沉淀为可复用的行业观察。

  • 十年建站经验,覆盖建材、制造、服务、文创等
  • 项目经理把关选题与事实准确性
  • 工程师与设计师联合撰写专业细节
  • 统一编辑规范,保证文风与排版一致
  • 每月复盘转化数据,迭代选题方向

延伸阅读

相关资讯与近期热门内容

深度阅读推荐

建站决策前值得细读的三篇

网站改版的5个关键决策
2024-08-12

网站改版的5个关键决策

什么时候该改版、改到什么程度、如何避免流量掉光,京华建材集团改版复盘给出答案。

获取专属建站方案

看完文章,把您的行业与预算告诉我们,免费获取一份量身定制的官网建设方案与报价。

立即免费咨询