> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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.

<View title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-python">
    Setup
  </h2>

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

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```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
        ```
      </CodeGroup>
    </Step>

    <Step title="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"
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-python">
    Auto-instrumentation
  </h2>

  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.

  <CodeGroup>
    ```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)
    ```
  </CodeGroup>

  <h2 id="manual-instrumentation-python">
    Manual instrumentation
  </h2>

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

  <CodeGroup>
    ```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)
    ```
  </CodeGroup>

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

  <h2 id="what-traced-python">
    What Braintrust traces
  </h2>

  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.

  <h2 id="tracing-resources-python">
    Tracing resources
  </h2>

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