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

# OpenAI Agents SDK

> Auto-instrument OpenAI Agents SDK agents, tools, and multi-turn conversations

Automatically capture agent runs, tool executions, and handoff transitions within the OpenAI Agents SDK ([Python](https://github.com/openai/openai-agents-python), [TypeScript](https://github.com/openai/openai-agents-js)).

## Setup

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import traceroot
    from traceroot import Integration

    traceroot.initialize(integrations=[Integration.OPENAI_AGENTS])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import * as agents from '@openai/agents';
    import { TraceRoot } from '@traceroot-ai/traceroot';

    TraceRoot.initialize({
      instrumentModules: { openaiAgents: agents },
    });
    ```
  </Tab>
</Tabs>

## Usage

Once initialized, all agent runs and tool calls are captured automatically:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import asyncio
    import traceroot
    from traceroot import Integration
    from agents import Agent, Runner, function_tool

    traceroot.initialize(integrations=[Integration.OPENAI_AGENTS])


    @function_tool
    def get_weather(city: str) -> str:
        """Get current weather for a city."""
        return f"The weather in {city} is 72°F and sunny."


    agent = Agent(
        name="Weather Assistant",
        instructions="You are a helpful weather assistant.",
        model="gpt-4o-mini",
        tools=[get_weather],
    )


    async def main():
        # The entire agent run is automatically traced
        result = await Runner.run(agent, "What's the weather in Tokyo?")
        print(result.final_output)


    if __name__ == "__main__":
        asyncio.run(main())
        traceroot.flush()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import * as agents from '@openai/agents';
    import { Agent, run, tool } from '@openai/agents';
    import { TraceRoot } from '@traceroot-ai/traceroot';
    import { z } from 'zod';

    TraceRoot.initialize({
      instrumentModules: { openaiAgents: agents },
    });

    const getWeather = tool({
      name: 'get_weather',
      description: 'Get current weather for a city.',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => `The weather in ${city} is 72°F and sunny.`,
    });

    const agent = new Agent({
      name: 'Weather Assistant',
      instructions: 'You are a helpful weather assistant.',
      model: 'gpt-4o-mini',
      tools: [getWeather],
    });

    async function main() {
      // The entire agent run is automatically traced
      const result = await run(agent, "What's the weather in Tokyo?");
      console.log(result.finalOutput);
      await TraceRoot.shutdown();
    }

    main().catch(console.error);
    ```
  </Tab>
</Tabs>

## What Gets Captured

| Attribute     | Description                                       |
| ------------- | ------------------------------------------------- |
| Agent runs    | Each `Runner.run()` / `run()` invocation          |
| Agent steps   | Individual turns within the agent loop            |
| Tool calls    | Each tool invocation with name, input, and output |
| Handoffs      | Multi-agent transitions and handoff decisions     |
| LLM calls     | Raw completion requests to OpenAI                 |
| Tokens & Cost | Aggregated token usage and pricing                |
| Latency       | Duration per agent run and per span               |

## Run the example

Clone the repo and run a complete agent end-to-end.

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="https://github.com/traceroot-ai/traceroot/tree/main/examples/python/openai-agents-sdk">
    Run the Python example
  </Card>

  <Card title="TypeScript" icon="js" href="https://github.com/traceroot-ai/traceroot/tree/main/examples/typescript/openai-agents">
    Run the TypeScript example
  </Card>
</CardGroup>