> ## 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)).

## Install

> [tab] Python
>
> ```bash theme={null}
> pip install traceroot openai-agents
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> npm install @traceroot-ai/traceroot @openai/agents zod
> ```

## Set up

> [tab] Python
>
> ```python theme={null}
> import traceroot
> from traceroot import Integration
>
> traceroot.initialize(integrations=[Integration.OPENAI_AGENTS])
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import * as agents from '@openai/agents';
> import { TraceRoot } from '@traceroot-ai/traceroot';
>
> TraceRoot.initialize({
>   instrumentModules: { openaiAgents: agents },
> });
> ```

## Usage

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

> [tab] 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] 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);
> ```

## Verify

Run your code and confirm the trace arrives:

1. **In the traceroot UI**: Navigate to **Tracing > Traces** in [traceroot Cloud](https://app.traceroot.ai). You should see a trace whose root span is the agent run's workflow name — `Agent workflow` unless you set your own, and `demo_session` in the shipped examples, which wrap the run with `observe`.
2. **Via the CLI**: Run `traceroot traces list` to inspect your recent traces from the terminal.

## 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; cost when the model ID matches traceroot's pricing table |
| Latency | Duration per agent run and per span |

## Limitations

None known.

## Run the example

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

> [card] [Python](https://github.com/traceroot-ai/traceroot/tree/main/examples/python/openai-agents-sdk)
>
> Run the Python example

> [card] [TypeScript](https://github.com/traceroot-ai/traceroot/tree/main/examples/typescript/openai-agents)
>
> Run the TypeScript example

## Next steps

> [card] [Python SDK Reference](https://traceroot.ai/docs/tracing/python-sdk.md)
>
> Explore the full Python SDK reference and instrumentation options.

> [card] [TypeScript SDK Reference](https://traceroot.ai/docs/tracing/typescript-sdk.md)
>
> Explore the full TypeScript SDK reference and configuration options.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.