agent-tracing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Tracing CLI Guide

Agent Tracing CLI 使用指南

@lobechat/agent-tracing

is a zero-config local dev tool that records agent execution snapshots to disk and provides a CLI to inspect them.

@lobechat/agent-tracing

是一款零配置本地开发工具，可将Agent执行快照记录到磁盘，并提供CLI工具用于检查这些快照。

How It Works

工作原理

NODE_ENV=development

AgentRuntimeService.executeStep()

automatically records each step to

.agent-tracing/

as partial snapshots. When the operation completes, the partial is finalized into a complete

ExecutionSnapshot

JSON file.

Data flow: executeStep loop -> build

StepPresentationData

-> write partial snapshot to disk -> on completion, finalize to

.agent-tracing/{timestamp}_{traceId}.json

Context engine capture: In

RuntimeExecutors.ts

, the

call_llm

executor emits a

context_engine_result

event after

serverMessagesEngine()

processes messages. This event carries the full

contextEngineInput

(DB messages, systemRole, model, knowledge, tools, userMemory, etc.) and the processed

output

messages (the final LLM payload).

在

NODE_ENV=development

环境下，

AgentRuntimeService.executeStep()

会自动将每个步骤作为部分快照记录到

.agent-tracing/

目录。当操作完成后，部分快照会被整理为完整的

ExecutionSnapshot

JSON 文件。

数据流：executeStep 循环 → 构建

StepPresentationData

→ 将部分快照写入磁盘 → 操作完成后，整理为

.agent-tracing/{timestamp}_{traceId}.json

文件

上下文引擎捕获：在

RuntimeExecutors.ts

中，

call_llm

执行器在

serverMessagesEngine()

处理完消息后，会触发

context_engine_result

事件。该事件携带完整的

contextEngineInput

（数据库消息、systemRole、模型、知识库、工具、用户记忆等）以及处理后的

output

消息（最终LLM负载）。

Package Location

包位置

packages/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 exports

packages/agent-tracing/
  src/
    types.ts          # ExecutionSnapshot, StepSnapshot, SnapshotSummary
    store/
      types.ts        # ISnapshotStore 接口
      file-store.ts   # FileSnapshotStore（.agent-tracing/*.json）
    recorder/
      index.ts        # appendStepToPartial(), finalizeSnapshot()
    viewer/
      index.ts        # 终端渲染：renderSnapshot, renderStepDetail, renderMessageDetail, renderSummaryTable, renderPayload, renderPayloadTools, renderMemory
    cli/
      index.ts        # CLI 入口（#!/usr/bin/env bun）
      inspect.ts      # 检查命令（默认）
      partial.ts      # 部分快照命令（列表、检查、清理）
    index.ts          # 桶导出

Data Storage

数据存储

Completed snapshots:

.agent-tracing/{ISO-timestamp}_{traceId-short}.json

Latest symlink:
```
.agent-tracing/latest.json
```

In-progress partials:

.agent-tracing/_partial/{operationId}.json

```
FileSnapshotStore
```
resolves from
```
process.cwd()
```
— run CLI from the repo root

已完成快照：

.agent-tracing/{ISO-timestamp}_{traceId-short}.json

最新快照软链接：
```
.agent-tracing/latest.json
```

进行中的部分快照：

.agent-tracing/_partial/{operationId}.json

```
FileSnapshotStore
```
基于
```
process.cwd()
```
路径解析 — 请在仓库根目录运行CLI

CLI Commands

CLI 命令

All commands run from the repo root:

bash

undefined

所有命令需在仓库根目录运行：

bash

undefined

View latest trace (tree overview,

inspect

is the default command)

查看最新追踪记录（树状概览，

inspect

是默认命令）

agent-tracing agent-tracing inspect agent-tracing inspect <traceId> agent-tracing inspect latest

List recent snapshots

列出近期快照

agent-tracing list agent-tracing list -l 20

Inspect specific step (-s is short for --step)

检查特定步骤（-s 是 --step 的缩写）

agent-tracing inspect <traceId> -s 0

View messages (-m is short for --messages)

查看消息（-m 是 --messages 的缩写）

agent-tracing inspect <traceId> -s 0 -m

View full content of a specific message (by index shown in -m output)

查看特定消息的完整内容（使用 -m 输出中的索引）

agent-tracing inspect <traceId> -s 0 --msg 2 agent-tracing inspect <traceId> -s 0 --msg-input 1

View tool call/result details (-t is short for --tools)

查看工具调用/结果详情（-t 是 --tools 的缩写）

agent-tracing inspect <traceId> -s 1 -t

View raw events (-e is short for --events)

查看原始事件（-e 是 --events 的缩写）

agent-tracing inspect <traceId> -s 0 -e

View runtime context (-c is short for --context)

查看运行时上下文（-c 是 --context 的缩写）

agent-tracing inspect <traceId> -s 0 -c

View context engine input overview (-p is short for --payload)

查看上下文引擎输入概览（-p 是 --payload 的缩写）

agent-tracing inspect <traceId> -p agent-tracing inspect <traceId> -s 0 -p

View available tools in payload (-T is short for --payload-tools)

查看负载中的可用工具（-T 是 --payload-tools 的缩写）

agent-tracing inspect <traceId> -T agent-tracing inspect <traceId> -s 0 -T

View user memory (-M is short for --memory)

查看用户记忆（-M 是 --memory 的缩写）

agent-tracing inspect <traceId> -M agent-tracing inspect <traceId> -s 0 -M

Raw JSON output (-j is short for --json)

输出原始JSON格式（-j 是 --json 的缩写）

agent-tracing inspect <traceId> -j agent-tracing inspect <traceId> -s 0 -j

List in-progress partial snapshots

列出进行中的部分快照

agent-tracing partial list

Inspect a partial (use

inspect

directly — all flags work with partial IDs)

检查部分快照（直接使用

inspect

命令 — 所有参数均适用于部分快照ID）

agent-tracing inspect <partialOperationId> agent-tracing inspect <partialOperationId> -T agent-tracing inspect <partialOperationId> -p

Clean up stale partial snapshots

清理过期的部分快照

agent-tracing partial clean

undefined

agent-tracing partial clean

undefined

Inspect 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 `-r` or `--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

--step

is not provided. All flags support

latest

or omitted traceId.

参数	缩写	描述	默认步骤
`--step <n>`	`-s`	定位到特定步骤	—
`--messages`	`-m`	消息上下文（上下文引擎输入 → 参数 → LLM负载）	—
`--tools`	`-t`	工具调用与结果（Agent调用的内容）	—
`--events`	`-e`	原始事件（llm_start、llm_result等）	—
`--context`	`-c`	运行时上下文与负载（原始格式）	—
`--system-role`	`-r`	完整system role内容	0
`--env`		环境上下文	0
`--payload`	`-p`	上下文引擎输入概览（模型、知识库、工具摘要、记忆摘要、平台上下文）	0
`--payload-tools`	`-T`	可用工具详情（插件清单 + LLM函数定义）	0
`--memory`	`-M`	完整用户记忆（角色设定、身份信息、上下文、偏好设置、过往经历）	0
`--diff <n>`	`-d`	与第N步进行对比（需配合 `-r` 或 `--env` 使用）	—
`--msg <n>`		查看最终LLM负载中第N条消息的完整内容	—
`--msg-input <n>`		查看上下文引擎输入中第N条消息的完整内容	—
`--json`	`-j`	以JSON格式输出（可与上述任意参数组合使用）	—

标记为“默认步骤：0”的参数，若未指定

--step

，则默认选择第0步。所有参数均支持使用

latest

或省略traceId。

Typical Debug Workflow

典型调试流程

bash

undefined

bash

undefined

1. Trigger an agent operation in the dev UI

1. 在开发UI中触发Agent操作

2. See the overview

2. 查看概览

agent-tracing inspect

3. List all traces, get traceId

3. 列出所有追踪记录，获取traceId

agent-tracing list

4. Quick overview of what was fed into context engine

4. 快速查看上下文引擎输入概览

agent-tracing inspect -p

5. Inspect a specific step's messages to see what was sent to the LLM

5. 检查特定步骤的消息，查看发送给LLM的内容

agent-tracing inspect TRACE_ID -s 0 -m

6. Drill into a truncated message for full content

6. 查看截断消息的完整内容

agent-tracing inspect TRACE_ID -s 0 --msg 2

7. Check available tools vs actual tool calls

7. 对比可用工具与实际调用的工具

agent-tracing inspect -T # available tools agent-tracing inspect -s 1 -t # actual tool calls & results

agent-tracing inspect -T # 可用工具 agent-tracing inspect -s 1 -t # 实际工具调用与结果

8. Inspect user memory injected into the conversation

8. 检查注入对话的用户记忆

agent-tracing inspect -M

9. Diff system role between steps (multi-step agents)

9. 对比多步骤Agent中不同步骤的system role

agent-tracing inspect TRACE_ID -r -d 2

undefined

agent-tracing inspect TRACE_ID -r -d 2

undefined

Key Types

关键类型定义

typescript

interface ExecutionSnapshot {
  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[];
}

interface StepSnapshot {
  stepIndex: number;
  stepType: 'call_llm' | 'call_tool';
  executionTimeMs: number;
  content?: string; // LLM output
  reasoning?: string; // Reasoning/thinking
  inputTokens?: number;
  outputTokens?: number;
  toolsCalling?: Array<{ apiName: string; identifier: string; arguments?: string }>;
  toolsResult?: Array<{
    apiName: string;
    identifier: string;
    isSuccess?: boolean;
    output?: string;
  }>;
  messages?: any[]; // DB messages before step
  context?: { phase: string; payload?: unknown; stepContext?: unknown };
  events?: Array<{ type: string; [key: string]: unknown }>;
  // context_engine_result event contains:
  //   input: full contextEngineInput (messages, systemRole, model, knowledge, tools, userMemory, ...)
  //   output: processed messages array (final LLM payload)
}

typescript

interface ExecutionSnapshot {
  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[];
}

interface StepSnapshot {
  stepIndex: number;
  stepType: 'call_llm' | 'call_tool';
  executionTimeMs: number;
  content?: string; // LLM输出
  reasoning?: string; // 推理/思考过程
  inputTokens?: number;
  outputTokens?: number;
  toolsCalling?: Array<{ apiName: string; identifier: string; arguments?: string }>;
  toolsResult?: Array<{
    apiName: string;
    identifier: string;
    isSuccess?: boolean;
    output?: string;
  }>;
  messages?: any[]; // 步骤执行前的数据库消息
  context?: { phase: string; payload?: unknown; stepContext?: unknown };
  events?: Array<{ type: string; [key: string]: unknown }>;
  // context_engine_result 事件包含：
  //   input: 完整contextEngineInput（消息、systemRole、模型、知识库、工具、用户记忆等）
  //   output: 处理后的消息数组（最终LLM负载）
}

--messages Output Structure

--messages 输出结构

When 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 N
```
to 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 N
```
to view full content.

使用

--messages

参数时，输出会包含三个部分（若上下文引擎数据可用）：

上下文引擎输入 — 传入引擎的数据库消息，带有
```
[0]
```
、
```
[1]
```
……索引。使用
```
--msg-input N
```
可查看完整内容。
上下文引擎参数 — systemRole、模型、供应商、知识库、工具、用户记忆等。
最终LLM负载 — 上下文引擎处理后的消息（包含系统日期注入、用户记忆、历史截断等），带有
```
[0]
```
、
```
[1]
```
……索引。使用
```
--msg N
```
可查看完整内容。

Integration Points

集成点

Recording:

src/server/services/agentRuntime/AgentRuntimeService.ts

— in the

executeStep()

method, after building

stepPresentationData

, writes partial snapshot in dev mode

Context engine event:

src/server/modules/AgentRuntime/RuntimeExecutors.ts

— in

call_llm

executor, after

serverMessagesEngine()

returns, emits

context_engine_result

event

Store:

FileSnapshotStore

reads/writes to

.agent-tracing/

relative to

process.cwd()

记录功能：

src/server/services/agentRuntime/AgentRuntimeService.ts

— 在

executeStep()

方法中，构建完

stepPresentationData

后，在开发模式下写入部分快照

上下文引擎事件：

src/server/modules/AgentRuntime/RuntimeExecutors.ts

— 在

call_llm

执行器中，

serverMessagesEngine()

返回后，触发

context_engine_result

事件

存储：

FileSnapshotStore

读取/写入相对

process.cwd()

路径的

.agent-tracing/

agent-tracing

Original

Translation

Agent Tracing CLI Guide

Agent Tracing CLI 使用指南

How It Works

工作原理

Package Location

包位置

Data Storage

数据存储

CLI Commands

CLI 命令

View latest trace (tree overview, inspect is the default command)

查看最新追踪记录（树状概览，inspect 是默认命令）

List recent snapshots

列出近期快照

Inspect specific step (-s is short for --step)

检查特定步骤（-s 是 --step 的缩写）

View messages (-m is short for --messages)

查看消息（-m 是 --messages 的缩写）

View full content of a specific message (by index shown in -m output)

查看特定消息的完整内容（使用 -m 输出中的索引）

View tool call/result details (-t is short for --tools)

查看工具调用/结果详情（-t 是 --tools 的缩写）

View raw events (-e is short for --events)

查看原始事件（-e 是 --events 的缩写）

View runtime context (-c is short for --context)

查看运行时上下文（-c 是 --context 的缩写）

View context engine input overview (-p is short for --payload)

查看上下文引擎输入概览（-p 是 --payload 的缩写）

View available tools in payload (-T is short for --payload-tools)

查看负载中的可用工具（-T 是 --payload-tools 的缩写）

View user memory (-M is short for --memory)

查看用户记忆（-M 是 --memory 的缩写）

Raw JSON output (-j is short for --json)

输出原始JSON格式（-j 是 --json 的缩写）

List in-progress partial snapshots

列出进行中的部分快照

Inspect a partial (use inspect directly — all flags work with partial IDs)

检查部分快照（直接使用 inspect 命令 — 所有参数均适用于部分快照ID）

Clean up stale partial snapshots

清理过期的部分快照

Inspect Flag Reference

检查命令参数参考

Typical Debug Workflow

典型调试流程

1. Trigger an agent operation in the dev UI

1. 在开发UI中触发Agent操作

2. See the overview

2. 查看概览

3. List all traces, get traceId

3. 列出所有追踪记录，获取traceId

4. Quick overview of what was fed into context engine

4. 快速查看上下文引擎输入概览

5. Inspect a specific step's messages to see what was sent to the LLM

5. 检查特定步骤的消息，查看发送给LLM的内容

6. Drill into a truncated message for full content

6. 查看截断消息的完整内容

7. Check available tools vs actual tool calls

7. 对比可用工具与实际调用的工具

8. Inspect user memory injected into the conversation

8. 检查注入对话的用户记忆

9. Diff system role between steps (multi-step agents)

9. 对比多步骤Agent中不同步骤的system role

Key Types

关键类型定义

--messages Output Structure

--messages 输出结构

Integration Points

集成点

View latest trace (tree overview,
`inspect`
is the default command)

查看最新追踪记录（树状概览，
`inspect`
是默认命令）

Inspect a partial (use
`inspect`
directly — all flags work with partial IDs)

检查部分快照（直接使用
`inspect`
命令 — 所有参数均适用于部分快照ID）