OpenAI Agents SDK

​

Setup

pnpm add braintrust @braintrust/openai-agents @openai/agents

npm install braintrust @braintrust/openai-agents @openai/agents

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

​

Auto-instrumentation

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

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

​

Manual instrumentation

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

​

What Braintrust traces

• Run spans (the root trace span, named after the workflow), with the run’s first input, final output, and trace group and metadata.
• Agent spans (named after each agent), with the agent’s tools, handoffs, and output type.
• Model spans (Generation and Response), with request input, response output, model and configuration details, token usage, and time to first token.
• Tool call spans (named after the function), with the tool’s input and output.
• Guardrail spans (named after the guardrail), with whether the guardrail triggered.
• Handoff spans (Handoff), with the source and destination agents.
• MCP tool-listing spans (MCP List Tools or List Tools (<server>)), with the server and the tools it exposes.
• Speech and transcription spans (Speech and Transcription) for voice agents, with their input, output, and model configuration, plus speech group spans (Speech Group) with their input.
• Custom spans (named by you), with any data you attach.
• Token usage metrics on model spans (prompt, completion, and total tokens), including cached token counts when the model reports them.
• Base64 image inputs and generated images as Braintrust attachments.
• Errors on any span that fails.
• Parent-child nesting when you run the agent inside an existing Braintrust span.

​

Resources

• OpenAI Agents JS docs
• Braintrust OpenAI Agents JS reference
• Trace LLM calls
• Advanced tracing
• Create experiments