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>

Auto-instrumentation

To trace OpenAI Agents SDK runs without modifying your application code, initialize Braintrust normally, then run your app with Braintrust’s import hook. The hook wires Braintrust’s trace processor into the OpenAI Agents SDK automatically, so you don’t need to install @braintrust/openai-agents or register a processor yourself. Requires @openai/agents v0.0.14 or later.

Initialize Braintrust and run an agent

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

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

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

Run with the import hook

node --import braintrust/hook.mjs trace-agents-auto.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

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

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

​Auto-instrumentation

​Manual instrumentation

​Examples

​Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​Examples

​Resources

Setup

Auto-instrumentation

Manual instrumentation

Examples

Resources

Setup

Auto-instrumentation

Manual instrumentation

Examples

Resources