> ## 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.

# AgentDbg: Local-First Step-Through Debugger for AI Agents

> AgentDbg captures structured execution traces for AI agents and shows them in a visual timeline—no cloud, no accounts, no telemetry.

AgentDbg is a local-first step-through debugger for AI agents. Add `@trace` to your agent function, run it, then open the timeline UI to see exactly what happened: every LLM call, tool call, state update, error, and loop warning—all on your machine, with no data ever leaving.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="bolt" href="/docs/quickstart">
    Install AgentDbg and trace your first agent run in under 5 minutes.
  </Card>

  <Card title="SDK Reference" icon="code" href="/docs/sdk/tracing">
    Explore `@trace`, `traced_run`, and all recording functions.
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/integrations/langchain">
    Auto-instrument LangChain, OpenAI Agents SDK, and CrewAI agents.
  </Card>

  <Card title="Guardrails" icon="shield" href="/docs/sdk/guardrails">
    Stop runaway agents with built-in loop detection and usage limits.
  </Card>
</CardGroup>

## What AgentDbg does

When you wrap your agent with `@trace`, AgentDbg automatically records every event and writes it to a structured local file. Run `agentdbg view` to open a live timeline in your browser showing every step—inputs, outputs, timing, and failure evidence.

<CardGroup cols={2}>
  <Card title="Timeline Viewer" icon="timeline" href="/docs/reference/viewer">
    Inspect runs with filter chips, expandable events, and live refresh.
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/docs/reference/cli">
    Use `agentdbg list`, `view`, and `export` to manage your runs.
  </Card>

  <Card title="Configuration" icon="gear" href="/docs/configuration/overview">
    Control data directory, redaction, guardrails, and loop detection.
  </Card>

  <Card title="Trace Format" icon="file-lines" href="/docs/reference/trace-format">
    Understand the run.json and events.jsonl storage layout.
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="Install">
    ```bash theme={null}
    pip install agentdbg
    ```
  </Step>

  <Step title="Instrument your agent">
    ```python theme={null}
    from agentdbg import trace, record_llm_call, record_tool_call

    @trace
    def run_agent():
        record_tool_call(name="search", args={"q": "users"}, result={"count": 42})
        record_llm_call(model="gpt-4", prompt="Summarize results", response="42 users.")
    ```
  </Step>

  <Step title="Open the timeline">
    ```bash theme={null}
    agentdbg view
    ```

    A browser tab opens at `http://127.0.0.1:8712` showing the full run timeline.
  </Step>
</Steps>

<Note>
  AgentDbg is a **development-time** tool. All data is stored as plain files on your machine under `~/.agentdbg/runs/`. No data is sent to any server.
</Note>