> ## Documentation Index
> Fetch the complete documentation index at: https://refinehq.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
AgentDbg requires Python 3.10 or later. Install it from PyPI:
```bash theme={null}
pip install agentdbg
```
That's the only dependency you need to get started. No sign-up required.
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:
```python theme={null}
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.
Run your script as you normally would:
```bash theme={null}
python your_agent.py
```
When the run completes, AgentDbg writes two files under `~/.agentdbg/runs//`:
* `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.
Open the browser-based timeline viewer:
```bash theme={null}
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:
```bash theme={null}
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
Learn the full `@trace` and `traced_run` API, including how to name runs and handle context.
Auto-record LLM and tool events from LangChain and LangGraph agents with a callback handler.
Stop runaway agents by setting limits on LLM calls, tool calls, events, and run duration.