Instructor

Setup

Install the Braintrust SDK and Instructor alongside your provider SDK:

pip install braintrust instructor openai

Set your API keys before you run your app:

.env

BRAINTRUST_API_KEY=<your-braintrust-api-key>
OPENAI_API_KEY=<your-openai-api-key>

Tracing Instructor requires instructor 1.11.0 or later and the Braintrust Python SDK v0.23.0 or later.

Auto-instrumentation

To trace Instructor without wrapping each client, call init_logger() and auto_instrument() once at startup. auto_instrument() patches Instructor’s create methods along with the underlying provider SDK, so each extraction appears as a task span with the provider’s LLM call nested beneath it.

import braintrust
import instructor
from openai import OpenAI
from pydantic import BaseModel

braintrust.init_logger(project="instructor-example")  # Replace with your project name
braintrust.auto_instrument()

class Person(BaseModel):
    name: str
    age: int

client = instructor.from_openai(OpenAI(), mode=instructor.Mode.RESPONSES_TOOLS)

person = client.responses.create(
    model="gpt-5-mini",
    input="Extract: John is 30 years old",
    response_model=Person,
)

Instrument only Instructor

To patch Instructor without enabling Braintrust’s other integrations, wrap the client with wrap_instructor() instead. See Manual instrumentation.

Manual instrumentation

To trace Instructor yourself, wrap the Instructor client with wrap_instructor(). Wrap the underlying provider client with wrap_openai() first so the provider’s LLM call is captured as a child of the Instructor span.

import instructor
from braintrust import init_logger, wrap_instructor, wrap_openai
from openai import OpenAI
from pydantic import BaseModel

init_logger(project="instructor-example")  # Replace with your project name

class Person(BaseModel):
    name: str
    age: int

# Wrap the provider client for the LLM span, then the Instructor client for the task span
client = wrap_instructor(
    instructor.from_openai(wrap_openai(OpenAI()), mode=instructor.Mode.RESPONSES_TOOLS)
)

person = client.responses.create(
    model="gpt-5-mini",
    input="Extract: John is 30 years old",
    response_model=Person,
)

What Braintrust traces

Braintrust captures:

Structured-output spans (instructor.create, instructor.create_with_completion, instructor.create_partial, and instructor.create_iterable), with the request messages, response model, and Instructor mode as input, and the extracted Pydantic model as output.
Extraction metadata, including the model, provider, response model, Instructor mode, and configured max retries.
Retry details, including the retry count and the Pydantic validation errors that triggered each retry.

Token usage stays on the provider’s LLM child span, so enable provider instrumentation (wrap_openai() or auto_instrument()) to see token counts alongside the extraction.

AI providers

SDKs

Developer tools

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources