Quickstart: Trace Your First Agent with AgentDbg

Install AgentDbg, instrument your first agent with @trace and the recording helpers, run it, and open the timeline UI—all in under 5 minutes.

This page walks you through installing AgentDbg, adding tracing to an agent function, running it, and opening the timeline viewer. You don’t need any API keys, cloud accounts, or configuration files to complete these steps.

1. Install AgentDbg

   AgentDbg requires Python 3.10 or later. Install it from PyPI:

   pip install agentdbg
   

   That’s the only dependency you need to get started. No sign-up required.

2. Instrument your agent

   Add @trace to your agent’s entry-point function, then call record_tool_call and record_llm_call inside it to record individual events. Here’s a minimal example:

   from agentdbg import trace, record_llm_call, record_tool_call
   
   @trace
   def run_agent():
       # Your existing agent logic goes here.
   
       record_tool_call(
           name="search_db",
           args={"query": "active users"},
           result={"count": 42},
       )
   
       record_llm_call(
           model="gpt-4",
           prompt="Summarize the search results.",
           response="There are 42 active users.",
           usage={"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20},
       )
   
   run_agent()
   

   The @trace decorator automatically records the run start and end, captures any unhandled exception as an error event, and writes everything to ~/.agentdbg/runs/ when the function returns.

3. Run your agent

   Run your script as you normally would:

   python your_agent.py
   

   When the run completes, AgentDbg writes two files under ~/.agentdbg/runs/<run_id>/:

   • run.json — run metadata (status, counts, timing)
   • events.jsonl — the full structured event stream

   Nothing is sent anywhere. The files are plain JSON you can inspect directly.

4. Open the timeline

   Open the browser-based timeline viewer:

   agentdbg view
   

   A browser tab opens at http://127.0.0.1:8712 showing the latest run. You’ll see:

   • Run summary panel — status (ok / error / running), duration, LLM call count, tool call count, error count, and loop warnings
   • Chronological event list — every recorded event in order
   • Expandable events — click any event to inspect its prompt, response, args, result, token usage, or error details
   • Filter chips — narrow the view to All, LLM, Tools, Errors, State, or Loops

   Leave the viewer running while you iterate. New runs appear in the sidebar automatically.

To see a complete example run with LLM calls, tool calls, state updates, a loop warning, and a simulated error—all without any API key—run the bundled demo agent:

python examples/demo/pure_python.py
agentdbg view

This is a good way to explore the full timeline UI before instrumenting your own agent.

What the UI shows after a run

After opening agentdbg view, the timeline for the example above would show:

• A RUN_START event with the run name and timestamp
• A TOOL_CALL event for search_db with the args and result expanded
• An LLM_CALL event for gpt-4 with the prompt, response, and token usage
• A RUN_END event with status ok and total duration

If your agent raises an exception, the @trace decorator catches it, records an ERROR event with the exception type, message, and stack trace, then records RUN_END with status=error before re-raising. You can jump directly to the first error using the button in the run summary panel.

Next steps

SDK: Tracing

Learn the full @trace and traced_run API, including how to name runs and handle context.

LangChain integration

Auto-record LLM and tool events from LangChain and LangGraph agents with a callback handler.

Guardrails

Stop runaway agents by setting limits on LLM calls, tool calls, events, and run duration.