agent-tracing

Agent tracing is a specialized development utility designed for LobeHub agent developers to gain deep visibility into the agent's internal reasoning and execution lifecycle. By automatically capturing execution snapshots during development, it allows engineers to inspect how an agent progresses through its decision-making steps, including raw LLM interactions, tool invocations, and context engine states. It is an essential tool for identifying bottlenecks, verifying prompt engineering efficacy, and debugging complex function-calling chains in a local environment.

• Automatically captures and serializes execution steps and snapshots to the .agent-tracing directory in development mode.

• Provides a robust terminal interface to inspect individual steps, LLM payloads, tool calls, and context engine inputs.

• Supports granular inspection of messages, system roles, user memory, and raw execution events.

• Includes utilities for listing recent traces, cleaning stale partial snapshots, and diffing runtime contexts.

• Facilitates deep dives into the payload structure, including model definitions, knowledge base summaries, and tool function definitions.

• To use, ensure your agent application is running in NODE_ENV=development; the tool will automatically record interaction data to .agent-tracing.

• Execute commands from the repository root to allow the CLI to resolve the snapshot store paths correctly.

• Use the inspect command to target specific trace IDs or the latest snapshot; leverage flags like -s (step), -m (messages), -t (tools), and -c (context) to filter output.

• The tool is strictly for local debugging purposes and does not support production environments due to its file-based storage mechanism.

• Always clean up partial snapshots using the partial clean command to maintain disk storage efficiency during iterative development.