Deep Agents

Setup

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

Install packages

uv add braintrust deepagents langchain-openai

pip install braintrust deepagents langchain-openai

Set environment variables

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.

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.

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.

AI providers

SDKs

Developer tools

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Tracing resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Tracing resources

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Tracing resources