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

# Auto-Instrument LangChain Agents with AgentDbg

> Use AgentDbgLangChainCallbackHandler to automatically capture every LLM and tool call from your LangChain or LangGraph agent into an AgentDbg trace.

AgentDbg's LangChain integration gives you full observability into your LangChain and LangGraph agents without manually wrapping each call. Add the callback handler once, and every LLM invocation and tool execution is automatically recorded to the active AgentDbg run—ready to inspect in the timeline viewer.

## What gets captured

The `AgentDbgLangChainCallbackHandler` hooks into LangChain's built-in callback system and records two event types:

* **LLM calls** — triggered by `on_llm_start` / `on_chat_model_start` → `on_llm_end`. Records model name, prompt, response text, and token usage.
* **Tool calls** — triggered by `on_tool_start` → `on_tool_end` / `on_tool_error`. Records tool name, input arguments, result, and error status.

LLM errors are recorded as `LLM_CALL` events with `status="error"`. Tool errors are recorded as `TOOL_CALL` events with `status="error"` and include the error message.

## Installation

Install AgentDbg with the LangChain extra:

```bash theme={null}
pip install "agentdbg[langchain]"
```

This installs `langchain-core` alongside AgentDbg. If you import the integration without `langchain-core` present, you get a clear `ImportError` with install instructions.

## Setting up the handler

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    pip install "agentdbg[langchain]"
    ```
  </Step>

  <Step title="Wrap your entrypoint with @trace">
    The handler requires an active AgentDbg run. Use the `@trace` decorator on the function that calls your chain:

    ```python theme={null}
    from agentdbg import trace
    from agentdbg.integrations import AgentDbgLangChainCallbackHandler

    @trace(name="my langchain agent")
    def run_agent():
        ...
    ```

    Alternatively, set `AGENTDBG_IMPLICIT_RUN=1` in your environment to start a run automatically without the decorator.
  </Step>

  <Step title="Create the handler">
    Inside your traced function, instantiate the handler:

    ```python theme={null}
    handler = AgentDbgLangChainCallbackHandler()
    config = {"callbacks": [handler]}
    ```
  </Step>

  <Step title="Pass the config to your chain">
    Pass `config` to any LangChain chain, LLM, or tool invocation:

    ```python theme={null}
    result = my_chain.invoke(input_data, config=config)
    ```
  </Step>
</Steps>

## Full example

This example uses a fake LLM so it runs without any API key or network calls:

```python theme={null}
from agentdbg import trace
from agentdbg.integrations import AgentDbgLangChainCallbackHandler

from langchain_core.language_models.fake import FakeListLLM
from langchain_core.tools import tool


@tool
def lookup(query: str) -> str:
    """Look up something (stub tool for demo)."""
    return f"result for: {query}"


@trace(name="langchain minimal example")
def run_agent():
    handler = AgentDbgLangChainCallbackHandler()
    config = {"callbacks": [handler]}

    llm = FakeListLLM(responses=["Traced LLM response."])
    result = lookup.invoke({"query": "demo"}, config=config)
    _ = llm.invoke("Summarize.", config=config)
    return result


if __name__ == "__main__":
    run_agent()
    print("Run complete. View with: agentdbg view")
```

Run it and open the timeline:

```bash theme={null}
uv run --extra langchain python examples/langchain/minimal.py
agentdbg view
```

## Guardrails with LangChain

All AgentDbg guardrails work with the callback handler. When a guardrail fires (for example, `stop_on_loop` detecting a repeated pattern), the handler immediately stops the run—bypassing LangChain's `except Exception` error handling and LangGraph's graph executor—so no further token-spending calls are made.

```python theme={null}
from agentdbg import AgentDbgLoopAbort, trace
from agentdbg.integrations import AgentDbgLangChainCallbackHandler


@trace(stop_on_loop=True, stop_on_loop_min_repetitions=3)
def run_agent():
    handler = AgentDbgLangChainCallbackHandler()
    return graph.invoke(state, config={"callbacks": [handler]})


try:
    run_agent()
except AgentDbgLoopAbort as exc:
    print(f"Stopped the loop: {exc}")
```

### Reusing the handler across runs

If you call your traced function multiple times with the same handler instance, call `handler.reset()` between runs to clear the abort state:

```python theme={null}
handler = AgentDbgLangChainCallbackHandler()

for input_data in dataset:
    handler.reset()
    run_agent_with_handler(handler, input_data)
```

### Checking for aborts after invoke

As a defensive fallback, the handler stores any guardrail exception on `handler.abort_exception`. Use `handler.raise_if_aborted()` to re-raise it if needed after an `invoke()` call returns:

```python theme={null}
result = my_chain.invoke(input_data, config={"callbacks": [handler]})
handler.raise_if_aborted()  # raises AgentDbgGuardrailExceeded if a guardrail fired
```

<Note>
  The handler requires an active AgentDbg run. Wrap your entrypoint with `@trace`, use `traced_run(...)`, or set `AGENTDBG_IMPLICIT_RUN=1` in your environment.
</Note>