Skip to Content

How do I trace an agent built with the OpenAI Agents SDK and deployed to a Docker container?

Rius traces an OpenAI Agents SDK agent in a Docker container: call init once at startup, wrap the run and tools with observe, and shut the client down when the container receives SIGTERM. Model calls arrive with tokens and cost, and your wrappers give the run and its tools their shape. Name the agent with the service name in init, and use underscores in the framework’s agent names.

How it works

The OpenAI Agents SDK drives the OpenAI client underneath, so the openai integration captures every model call as a generation with model, tokens, cost and time to first token. The framework’s agent loop, tool executions and handoffs run inside the framework, so you add observe wrappers to put that structure in the trace. See the OpenAI Agents SDK page for what lands where, and Integrations for the other frameworks.

Three points matter for this setup:

  • Where init goes. Call rius.init() once, at the top of your entrypoint module, before you build the agent or run it. With a default init(), every installed integration turns on automatically. Do not call it inside the function that handles each request.
  • When spans leave the process. Spans are queued in memory and exported in batches from a background thread. Python flushes pending spans at a normal interpreter exit, but docker stop sends SIGTERM, and Python’s default response ends the process without running that exit hook. The SDK installs no signal handlers, so you handle SIGTERM yourself, covered below.
  • What the agent is called. The agent is grouped under its service name, which you set in init. RIUS_AGENT_NAME overrides it, and it defaults to the service name.

Set it up

  1. Install the SDK with the OpenAI extra, alongside the framework. Add both to the dependencies your image installs. The extra installs only the instrumentation, so openai-agents and its OpenAI client must be present too.

    pip install "glassflow-rius[openai]" openai-agents
  2. Initialize at startup and wrap the entrypoint and tools. Give init a service_name that identifies the agent, and wrap the run with an AGENT span. Put @function_tool outermost and observe with the TOOL kind on the function body. Disable the framework’s own tracing if Rius should be the single telemetry path.

    import rius from agents import Agent, Runner, function_tool, set_tracing_disabled from rius import SpanKind client = rius.init(service_name="support-agent") # reads RIUS_API_KEY from the environment set_tracing_disabled(True) @function_tool @rius.observe(kind=SpanKind.TOOL) def account_status(email: str) -> str: """Fetch a customer's account standing by email.""" return lookup(email) support_agent = Agent( name="support_agent", instructions="Answer support questions; check accounts with the tool.", tools=[account_status], model="gpt-5-mini", ) @rius.observe(name="handle-ticket", kind=SpanKind.AGENT) def handle_ticket(ticket: str) -> str: result = Runner.run_sync(support_agent, ticket) return str(result.final_output)
  3. Name things deliberately. service_name is the name the agent appears under in Rius. The name on the root observe wrapper names the run’s top span. Name the framework’s Agent with underscores, such as support_agent: a hyphen is rewritten in the generated handoff tool name and the framework warns on every run.

  4. Choose a flush strategy by how your process ends:

    • A long-running server or worker: batches export continuously. Shut the client down on SIGTERM with a handler like the one below, or in your server’s shutdown hook if it already handles the signal, such as a FastAPI lifespan under uvicorn. Start the app in exec form (CMD ["python", "app.py"]) so it is PID 1 and receives the signal. Docker waits 10 seconds before SIGKILL; raise that with --stop-timeout or stop_grace_period in Compose if needed.
    • A CLI or batch job that runs and exits: call client.flush() before it ends, because a short process can finish before the first scheduled export.
    • Never flush inside a request handler. It blocks until the export completes. Flush at process boundaries only.
    import signal import sys def on_sigterm(signum, frame): client.shutdown() # drain queued spans, send the stopped heartbeat sys.exit(0) signal.signal(signal.SIGTERM, on_sigterm)

    Pass RIUS_API_KEY to the container from your secret store, for example with docker run -e RIUS_API_KEY, never baked into the image.

  5. Call client.shutdown() when your process stops on purpose. It sends the final stopped heartbeat, which is how Rius tells a clean exit from a crash. An unhandled SIGTERM or a SIGKILL sends no stopped ping, and the instance reports gone. Details are on the Reliability page.

  6. Scope each run with rius.session(), reusing your conversation or ticket id, so every turn of one conversation groups together.

What you get

  • A root AGENT span for each run, LLM generations with model, tokens and cost, and TOOL spans named after your functions.
  • Costs as list-price estimates in US dollars, which Rius computes from the model and token counts. You never send a cost value.
  • The agent under the name you set in init, with instances shown in the Agents view while the process sends heartbeats and has an API key.
  • A clear record of a clean stop versus a crash, when you call shutdown().
  • Sessions that group the turns of one conversation.

To check the setup, run one request that calls a tool, then open the trace in the console. The root AGENT span, the LLM generations and your named TOOL spans should all be there. Streamed runs carry token counts only when usage is enabled on the underlying OpenAI client.

When something else fits

  • A handoff produces no span of its own. If handoff boundaries matter to you, add an observe wrapper per agent entry, or use the framework’s RunHooks to open spans at agent boundaries.
  • For a Lambda-style runtime rather than a long-lived process, flush at the end of every invocation and turn the heartbeat off. The Reliability page covers it.

Still stuck? Get help

Last updated on