Skip to content
SideSeat

OpenAI Agents SDK

OpenAI Agents SDK is OpenAI’s framework for building AI agents. SideSeat captures full agent-level traces including tool calls, handoffs, and LLM calls.

Prerequisites

Section titled “Prerequisites”
  • SideSeat running locally (sideseat)
  • Python 3.9+
  • OpenAI API credentials configured

Quick Start

Section titled “Quick Start”

  1. Start SideSeat

    Terminal window
    npx sideseat

  2. Install dependencies

    Terminal window
    pip install openai-agents "sideseat[openai-agents]"

  3. Add telemetry

    from sideseat import SideSeat, Frameworks
    from agents import Agent, Runner
    

    SideSeat(framework=Frameworks.OpenAIAgents)
    

    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant."
    )
    

    result = Runner.run_sync(agent, "Hello!")
    print(result.final_output)

  4. View runs

    Open http://localhost:5388 to see your runs.

Without SideSeat SDK

Section titled “Without SideSeat SDK”

Use logfire to instrument the OpenAI Agents SDK via its official hook:

  1. Start SideSeat

    Terminal window
    npx sideseat

  2. Set the endpoint

    Terminal window
    export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5388/otel/default

  3. Install dependencies

    Terminal window
    pip install openai-agents "logfire>=4.29.0" opentelemetry-exporter-otlp

  4. Add telemetry

    import logfire
    from opentelemetry import trace
    from opentelemetry.sdk.trace.export import BatchSpanProcessor
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
    

    logfire.configure(send_to_logfire=False, console=False)
    logfire.instrument_openai_agents()
    

    provider = trace.get_tracer_provider()
    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

  5. View runs

    Open http://localhost:5388 to see your runs.

Tools

Section titled “Tools”

Define tools using the @function_tool decorator:

from agents import Agent, Runner, function_tool


@function_tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Sunny in {city}"


agent = Agent(
    name="WeatherAssistant",
    instructions="Use get_weather to provide forecasts.",
    tools=[get_weather]
)


result = Runner.run_sync(agent, "What's the weather in Paris?")

SideSeat shows:

  • Parent span for the agent run
  • Child spans for each OpenAI call
  • Child spans for each tool execution

Session Tracking

Section titled “Session Tracking”

Add session context with manual spans:

from opentelemetry import trace


tracer = trace.get_tracer(__name__)


with tracer.start_as_current_span(
    "openai_agents.session",
    attributes={
        "session.id": "session-123",
        "user.id": "user-456"
    }
):
    result = Runner.run_sync(agent, "Hello!")

Extracted Attributes

Section titled “Extracted Attributes”
AttributeDescription
gen_ai.systemopenai
gen_ai.request.modelOpenAI model ID
gen_ai.usage.input_tokensInput token count
gen_ai.usage.output_tokensOutput token count
logfire.span_typeSpan type (present when using SideSeat SDK)

Async Usage

Section titled “Async Usage”

The SDK supports async execution:

import asyncio
from agents import Agent, Runner


agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)


async def main():
    result = await Runner.run(agent, "Hello!")
    print(result.final_output)


asyncio.run(main())

Next Steps

Section titled “Next Steps”