> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deep Agents

> Trace Deep Agents workflows in Braintrust to debug agent plans, tool calls, and model calls. Uses the Braintrust LangChain integration with auto-instrumentation or manual callbacks.

[Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) is LangChain's agent harness for long-running agents with planning, filesystem access, subagents, memory, and tool use. Braintrust traces Deep Agents runs so you can inspect the agent workflow, tool calls, and model calls in one trace.

**Python**

## Setup

Install Deep Agents with Braintrust and the LangChain model package you use.

**1. Install packages**

```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv add braintrust deepagents langchain-openai
```

```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust deepagents langchain-openai
```

**2. Set environment variables**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
export BRAINTRUST_API_KEY="YOUR_BRAINTRUST_API_KEY"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

## Auto-instrumentation

To trace Deep Agents without wiring callbacks into each agent, call `braintrust.auto_instrument()` before importing Deep Agents or LangChain packages. Braintrust uses the LangChain integration because Deep Agents is built on LangChain and LangGraph.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import braintrust

braintrust.auto_instrument()
braintrust.init_logger(project="My Project")

from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI


def get_weather(city: str) -> str:
    """Return a short weather report for a city."""
    return f"The weather in {city} is sunny."


model = ChatOpenAI(model="gpt-5-mini")
agent = create_deep_agent(
    model=model,
    tools=[get_weather],
    system_prompt="You are a concise weather assistant.",
    name="weather-agent",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]}
)
print(result["messages"][-1].content)
```

## Manual instrumentation

To control which Deep Agents runs are traced, attach `BraintrustCallbackHandler` through the LangChain callback configuration.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from braintrust import init_logger
from braintrust.integrations.langchain import BraintrustCallbackHandler
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI


def get_weather(city: str) -> str:
    """Return a short weather report for a city."""
    return f"The weather in {city} is sunny."


logger = init_logger(project="My Project")
handler = BraintrustCallbackHandler(logger=logger)

model = ChatOpenAI(model="gpt-5-mini")
agent = create_deep_agent(
    model=model,
    tools=[get_weather],
    system_prompt="You are a concise weather assistant.",
    name="weather-agent",
).with_config({"callbacks": [handler]})

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]}
)
print(result["messages"][-1].content)
```

If you already use LangChain callbacks, add `handler` to the same `callbacks` list as your existing handlers.

## What Braintrust traces

Braintrust captures:

* Deep Agents run spans (`<agent name>`), with input messages, output messages, LangChain tags, and Deep Agents metadata such as `ls_integration`, `lc_agent_name`, and `lc_versions`
* Chat model spans (`<model class name>`), with input messages, invocation parameters, output, model name, and token usage when the model provider returns LangChain usage metadata
* Tool spans (`<tool name>`), with parsed tool inputs, outputs, metadata, and errors
* Streaming timing on model spans, with `time_to_first_token` when LangChain emits new-token callbacks
* Streaming timing on model spans, with `time_to_first_token` when LangChain emits new-token callbacks.

## Tracing resources

* [Deep Agents documentation](https://docs.langchain.com/oss/python/deepagents/overview)
* [Deep Agents API reference](https://reference.langchain.com/python/deepagents/)
* [LangChain integration](https://docs.braintrust.dev/integrations/sdk-integrations/langchain.md)
* [LangGraph integration](https://docs.braintrust.dev/integrations/agent-frameworks/langgraph.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.