OpenAI Agents SDK

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.

Setup

Install Braintrust and the OpenAI Agents SDK:

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

Set your API keys before you run your app:

.env

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

Instrument OpenAI Agents SDK

TypeScript
Python

Use Braintrust’s trace processor with @openai/agents to add instrumentation.

Trace Processor

trace-agents.ts

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.TypeScript Resources:

Use braintrust.auto_instrument() when you want OpenAI Agents SDK tracing alongside Braintrust’s other Python integrations.Braintrust’s OpenAI Agents integration requires openai-agents>=0.0.19.

Automatic Instrumentation

trace-agents.py

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())

If you only want to patch OpenAI Agents SDK, use setup_openai_agents() instead of braintrust.auto_instrument().

trace-agents-openai-agents-only.py

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())

Trace Processor

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

trace-agents-processor.py

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())

Python resources:

Examples

In Braintrust, each OpenAI Agents run appears as a root task span with child spans for the agent’s internal steps.

Braintrust captures:

A root 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.

AI providers

SDKs

Developer tools

Setup

Instrument OpenAI Agents SDK

Trace Processor

Automatic Instrumentation

Trace Processor

Examples

Resources

AI providers

SDKs

Developer tools

​Setup

​Instrument OpenAI Agents SDK

​Trace Processor

​Automatic Instrumentation

​Trace Processor

​Examples

​Resources

Setup

Instrument OpenAI Agents SDK

Trace Processor

Automatic Instrumentation

Trace Processor

Examples

Resources