> ## 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 with Braintrust

If you are a coding agent, prefer the Braintrust [`bt` CLI](/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 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.

<Tabs>
  <Tab title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <h2 id="setup-typescript">
      Setup
    </h2>

    <Steps>
      <Step title="Install packages">
        <CodeGroup>
          ```bash TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          # pnpm
          pnpm add braintrust @braintrust/openai-agents @openai/agents
          # npm
          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](/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 title="trace-agents.ts" 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="examples-typescript">
      Examples
    </h2>

    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](/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](/sdks/typescript/related/openai-agents/latest)
    * [Trace LLM calls](/instrument/trace-llm-calls)
    * [Advanced tracing](/instrument/advanced-tracing)
    * [Create experiments](/evaluate/run-evaluations)
  </Tab>

  <Tab title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <h2 id="setup-python">
      Setup
    </h2>

    <Steps>
      <Step title="Install packages">
        <CodeGroup>
          ```bash Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          # uv
          uv add braintrust openai-agents
          # pip
          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 title="trace-agents.py" 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 title="trace-agents-openai-agents-only.py" 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 title="trace-agents-processor.py" 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="examples-python">
      Examples
    </h2>

    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](/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](/sdks/python/versions/latest)
    * [Trace LLM calls](/instrument/trace-llm-calls)
    * [Advanced tracing](/instrument/advanced-tracing)
    * [Create experiments](/evaluate/run-evaluations)
  </Tab>
</Tabs>