> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Trace OpenAI Agents SDK runs in Braintrust to debug agents, evaluate models, and monitor production

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

The [OpenAI Agents SDK](https://openai.com/index/introducing-the-openai-agents-sdk/) is OpenAI's framework for building agentic workflows. Braintrust traces each agent run as a single trace, so you can inspect the whole workflow, including tool calls, guardrails, handoffs, and nested model calls.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  Trace OpenAI Agents SDK runs from your TypeScript application.

  <h2 id="setup-typescript">
    Setup
  </h2>

  Install the Braintrust and OpenAI Agents SDKs, then set your API keys.

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        pnpm add braintrust @braintrust/openai-agents @openai/agents
        ```

        ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        npm install braintrust @braintrust/openai-agents @openai/agents
        ```
      </CodeGroup>
    </Step>

    <Step title="Set environment variables">
      ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      BRAINTRUST_API_KEY=<your-braintrust-api-key>
      OPENAI_API_KEY=<your-openai-api-key>
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-typescript">
    Auto-instrumentation
  </h2>

  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.

  <Steps>
    <Step title="Initialize Braintrust and run an agent">
      <CodeGroup>
        ```javascript title="trace-agents-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        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);
        ```
      </CodeGroup>
    </Step>

    <Step title="Run with the import hook">
      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      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.

      <Note>
        If you're using a bundler, see [Trace LLM calls](/docs/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
      </Note>
    </Step>
  </Steps>

  <h2 id="manual-instrumentation-typescript">
    Manual instrumentation
  </h2>

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

  <CodeGroup>
    ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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);
    ```
  </CodeGroup>

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

  <h2 id="what-traced-typescript">
    What Braintrust traces
  </h2>

  Braintrust captures:

  * 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.

  You can also use OpenAI Agents SDK tasks inside Braintrust experiments. For evaluation patterns, see [Create experiments](/docs/evaluate/run-evaluations).

  <h2 id="resources-typescript">
    Resources
  </h2>

  * [OpenAI Agents JS docs](https://openai.github.io/openai-agents-js/)
  * [Braintrust OpenAI Agents JS reference](/docs/sdks/typescript/related/openai-agents/latest)
  * [Trace LLM calls](/docs/instrument/trace-llm-calls)
  * [Advanced tracing](/docs/instrument/advanced-tracing)
  * [Create experiments](/docs/evaluate/run-evaluations)
</View>

<View title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  Trace OpenAI Agents SDK runs from your Python application.

  <h2 id="setup-python">
    Setup
  </h2>

  Install the Braintrust and OpenAI Agents SDKs, then set your API keys.

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        uv add braintrust openai-agents
        ```

        ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        pip install braintrust openai-agents
        ```
      </CodeGroup>
    </Step>

    <Step title="Set environment variables">
      ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      BRAINTRUST_API_KEY=<your-braintrust-api-key>
      OPENAI_API_KEY=<your-openai-api-key>
      ```
    </Step>
  </Steps>

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

  <h2 id="auto-instrumentation-python">
    Auto-instrumentation
  </h2>

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

  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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())
    ```
  </CodeGroup>

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

  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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())
    ```
  </CodeGroup>

  <h2 id="manual-instrumentation-python">
    Manual instrumentation
  </h2>

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

  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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())
    ```
  </CodeGroup>

  <h2 id="what-traced-python">
    What Braintrust traces
  </h2>

  Braintrust captures:

  * 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.
  * Turn spans (`Turn <n> (<agent>)`) for each iteration of the agent loop, when your `openai-agents` version emits them.
  * 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 and reasoning token breakdowns when the model reports them.
  * Errors on any span that fails.
  * Parent-child nesting 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](/docs/evaluate/run-evaluations).

  <h2 id="resources-python">
    Resources
  </h2>

  * [OpenAI Agents SDK docs](https://openai.com/index/introducing-the-openai-agents-sdk/)
  * [Braintrust Python SDK reference](/docs/sdks/python/versions/latest)
  * [Trace LLM calls](/docs/instrument/trace-llm-calls)
  * [Advanced tracing](/docs/instrument/advanced-tracing)
  * [Create experiments](/docs/evaluate/run-evaluations)
</View>