OpenAI Agents SDK

Automatically capture agent runs, tool executions, and handoff transitions within the OpenAI Agents SDK (Python, TypeScript).

Install

Python
TypeScript

pip install traceroot openai-agents

npm install @traceroot-ai/traceroot @openai/agents zod

Set up

Python
TypeScript

import traceroot
from traceroot import Integration

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

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:

Python
TypeScript

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

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:

In the TraceRoot UI: Navigate to Tracing > Traces in TraceRoot Cloud. 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.
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.

Python

Run the Python example

TypeScript

Run the TypeScript example

Next steps

Python SDK Reference

Explore the full Python SDK reference and instrumentation options.

TypeScript SDK Reference

Explore the full TypeScript SDK reference and configuration options.

Overview

Native

Frameworks

Model Providers

Internal Model Providers

Install

Set up

Usage

Verify

What gets captured

Limitations

Run the example

Python

TypeScript

Next steps

Python SDK Reference

TypeScript SDK Reference

​Install

​Set up

​Usage

​Verify

​What gets captured

​Limitations

​Run the example

Python

TypeScript

​Next steps

Python SDK Reference

TypeScript SDK Reference

Install

Set up

Usage

Verify

What gets captured

Limitations

Run the example

Next steps