Skip to main content
To use an agent for automatic setup, see the Quickstart.

​
Sign up

If you don’t have a Braintrust account, sign up for free at braintrust.dev.

​
Install the SDK

Add the Braintrust SDK to your project using your preferred package manager: 
pip install braintrust

​
Set an API key

On the Settings > API keys page, create an API key. Then, set it as an environment variable:
.env
BRAINTRUST_API_KEY="your-api-key"
The SDK picks up your API key automatically. When you’re done testing locally, remember to set it in production.
Never put your API key in version control.

​
Configure tracing

There are two ways to instrument your app:
  • Auto-instrumentation (recommended): Call auto_instrument() to patch supported AI libraries at startup, tracing your LLM calls without changing each call site.
  • Manual instrumentation: Initialize Braintrust yourself and wrap specific provider clients. Use this approach if you need precise control or if your provider isn’t supported by auto-instrumentation.
1

Initialize the logger

Call init_logger() once, as soon as possible on application startup. The SDK reads BRAINTRUST_API_KEY from the environment configured above.
import braintrust

logger = braintrust.init_logger(project="My Project")
2

Enable automatic instrumentation

Call auto_instrument() after init_logger() and before creating any AI provider clients. If your app imports provider classes directly, such as from openai import OpenAI, call auto_instrument() before those imports when possible.
braintrust.auto_instrument()
You can disable specific integrations by passing False for that integration:
braintrust.auto_instrument(openai=False)
For supported integrations, see Trace LLM calls.
3

Run your app

Start your Python application normally:
python app.py
Then make an AI call. For example:
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5-mini",
    input=[{"role": "user", "content": "Hello!"}],
)

​
Log application spans

Braintrust traces your LLM calls automatically, but not the code around them. Decorate any function with @traced to record it as a span: Braintrust captures the function’s arguments as the span’s input and its return value as the output, and nests any traced LLM calls made inside it underneath. This surfaces your application’s structure in the trace, not just isolated model calls. 
from braintrust import traced

@traced
def classify_text(text: str) -> str:
    # Your logic here, including any LLM calls, is captured under this span
    return "positive"

classify_text("Great result")

​
Flush before exit

For scripts and jobs, call flush() before the process exits so buffered events are sent to Braintrust. 
logger.flush()

​
Next steps

Learn more about using the SDK to observe, evaluate, and improve your AI application:
  • Instrument — trace LLM calls and application logic
  • Observe — search and analyze production traces
  • Annotate — label traces and build datasets
  • Evaluate — measure quality and catch regressions
  • Deploy — ship to production with the AI gateway