OpenAI Agents SDK - Braintrust

The OpenAI Agents SDK is OpenAI’s framework for building agentic workflows. Braintrust instruments OpenAI Agents runs so you can inspect agent spans, tool calls, guardrails, nested model calls, and final outputs as a single trace in Braintrust.

TypeScript
Python

Setup

Install packages

# pnpm
pnpm add braintrust @braintrust/openai-agents @openai/agents
# npm
npm install braintrust @braintrust/openai-agents @openai/agents

Set environment variables

.env

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

Manual instrumentation

To instrument OpenAI Agents SDK runs, add Braintrust’s OpenAIAgentsTraceProcessor.

import { initLogger } from "braintrust";
import { OpenAIAgentsTraceProcessor } from "@braintrust/openai-agents";
import { Agent, addTraceProcessor, run } from "@openai/agents";

const logger = initLogger({
  projectName: "openai-agents-example", // Replace with your project name
  apiKey: process.env.BRAINTRUST_API_KEY,
});

addTraceProcessor(new OpenAIAgentsTraceProcessor({ logger }));

async function main() {
  const agent = new Agent({
    name: "Assistant",
    model: "gpt-5-mini",
    instructions: "You answer in one sentence.",
  });

  const result = await run(agent, "What is the capital of France?");
  console.log(result.finalOutput);
}

main().catch(console.error);

If you omit logger, the processor uses the current Braintrust span, experiment, or logger when one is active.

Examples

Braintrust captures:

A root task span for each agent run
Child spans for tool calls, guardrails, handoffs, and nested model work
Inputs and outputs for agent and tool spans
Token metrics on LLM spans when the SDK exposes usage data
Parent-child relationships when you run the agent inside an existing Braintrust span

You can also use OpenAI Agents SDK tasks inside Braintrust experiments. For evaluation patterns, see Create experiments.

Resources

Setup

Install packages

# uv
uv add braintrust openai-agents
# pip
pip install braintrust openai-agents

Set environment variables

.env

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

Braintrust’s OpenAI Agents integration requires openai-agents>=0.0.19.

Auto-instrumentation

To automatically trace OpenAI Agents SDK runs alongside Braintrust’s other Python integrations, call braintrust.auto_instrument().

import asyncio
import os

import braintrust

braintrust.auto_instrument()
braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="openai-agents-example",  # Replace with your project name
)

from agents import Agent, Runner


async def main():
    agent = Agent(
        name="Assistant",
        model="gpt-5-mini",
        instructions="You answer in one sentence.",
    )

    result = await Runner.run(agent, "What is the capital of France?")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

To instrument only the OpenAI Agents SDK without enabling Braintrust’s other integrations, use setup_openai_agents() instead of braintrust.auto_instrument().

import asyncio

from agents import Agent, Runner
from braintrust.integrations.openai_agents import setup_openai_agents

setup_openai_agents(project_name="openai-agents-example")


async def main():
    agent = Agent(
        name="Assistant",
        model="gpt-5-mini",
        instructions="You answer in one sentence.",
    )

    result = await Runner.run(agent, "What is the capital of France?")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

Manual instrumentation

If you need direct control over trace processor registration, add BraintrustTracingProcessor yourself.

import asyncio

from agents import Agent, Runner, set_trace_processors
from braintrust import init_logger
from braintrust.integrations.openai_agents import BraintrustTracingProcessor

logger = init_logger(project="openai-agents-example")
set_trace_processors([BraintrustTracingProcessor(logger)])


async def main():
    agent = Agent(
        name="Assistant",
        model="gpt-5-mini",
        instructions="You answer in one sentence.",
    )

    result = await Runner.run(agent, "What is the capital of France?")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

Examples

Braintrust captures:

A root task span for each agent run
Turn spans for each agent loop iteration
Child spans for tool calls, guardrails, handoffs, and nested model work
Inputs and outputs for agent and tool spans
Token metrics on LLM spans, including cached_tokens when the model returns cached token usage
Parent-child relationships when you run the agent inside an existing Braintrust span

You can also use OpenAI Agents SDK tasks inside Braintrust experiments. For evaluation patterns, see Create experiments.

​Setup

​Manual instrumentation

​Examples

​Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​Examples

​Resources

Setup

Manual instrumentation

Examples

Resources

Setup

Auto-instrumentation

Manual instrumentation

Examples

Resources