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

# Install and instrument

> Install the Python SDK, set an API key, and configure tracing by hand.

<Note>To use an agent for automatic setup, see the [Quickstart](/sdks/python/quickstart).</Note>

## Sign up

If you don't have a Braintrust account, sign up for free at [braintrust.dev](https://www.braintrust.dev/signup).

## Install the SDK

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

<CodeGroup>
  ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  pip install braintrust
  ```

  ```bash poetry theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  poetry add braintrust
  ```

  ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  uv add braintrust
  ```
</CodeGroup>

## Set an API key

On the **<Icon icon="settings-2" /> Settings** > [**<Icon icon="key-square" /> API keys**](https://www.braintrust.dev/app/~/configuration/org/api-keys) page,
create an API key. Then, set it as an environment variable:

```bash .env theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

<Warning>
  Never put your API key in version control.
</Warning>

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

<Tabs defaultTabIndex={0} sync={false} className="tabs-border">
  <Tab title="Auto-instrumentation">
    <Steps>
      <Step title="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.

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

        logger = braintrust.init_logger(project="My Project")
        ```
      </Step>

      <Step title="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.

        ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        braintrust.auto_instrument()
        ```

        You can disable specific integrations by passing `False` for that integration:

        ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        braintrust.auto_instrument(openai=False)
        ```

        For supported integrations, see [Trace LLM calls](/instrument/trace-llm-calls#python).
      </Step>

      <Step title="Run your app">
        Start your Python application normally:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        python app.py
        ```

        Then make an AI call. For example:

        ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        from openai import OpenAI

        client = OpenAI()
        response = client.responses.create(
            model="gpt-5-mini",
            input=[{"role": "user", "content": "Hello!"}],
        )
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual instrumentation">
    Initialize the logger, then wrap your provider client. The example below uses OpenAI; for other providers, see [Python SDK integrations](/sdks/python/sdk-integrations).

    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import braintrust
    from braintrust import wrap_openai
    from openai import OpenAI

    braintrust.init_logger(project="My Project")

    # Wrap the client to trace all calls
    client = wrap_openai(OpenAI())
    response = client.responses.create(
        model="gpt-5-mini",
        input="What is the capital of France?",
    )
    ```

    To capture your own application logic alongside traced LLM calls, see [Log application spans](#log-application-spans).
  </Tab>
</Tabs>

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

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
logger.flush()
```

## Next steps

Learn more about using the SDK to observe, evaluate, and improve your AI application:

* [Instrument](/instrument) — trace LLM calls and application logic
* [Observe](/observe) — search and analyze production traces
* [Annotate](/annotate) — label traces and build datasets
* [Evaluate](/evaluate) — measure quality and catch regressions
* [Deploy](/deploy) — ship to production with the AI gateway