Skip to Content

How do I see retries and fallbacks in an agent built with the OpenAI Agents SDK?

Rius shows retries and fallbacks in an OpenAI Agents SDK trace as errored spans, a collapsed retry row and a recovered badge on runs that finish clean. The openai integration records every model call on its own. Wrap your entrypoint and tool bodies with observe so the run and each tool attempt appear as spans. Retries and fallbacks are read from those spans, so you send no retry flag.

How it works

  • Model calls arrive on their own. The framework drives the OpenAI client underneath, so the openai integration records each call as a generation with model, tokens and cost. A fallback to a different model shows as another generation, and its Model section lists the requested and response model. The OpenAI client underneath also retries a failed request on its own (max_retries, 2 by default). Those attempts happen inside one call, so they show as one generation, not as a retry row.
  • Run structure needs observe. The agent loop, tool executions and handoffs run inside the framework, and auto-instrumentation only sees the client calls that come out of it. Your observe wrapper on the entrypoint gives the root span, and a wrapper on each tool body gives the tool spans.
  • Status comes from the spans. A trace is failed when at least one span carries an error status. If the root span finishes without an error of its own, the trace is badged recovered: child spans errored, the agent retried or fell back, and the run completed clean. The errors are still counted.
  • A failing tool usually does not fail the run. By default the framework catches an exception from a function tool and sends an error message back to the model, so the TOOL span is errored and the run can still finish clean.
  • Retry chains collapse into one row. Back-to-back calls of the same tool or step with the same input become one row, such as fetch_article · 3 attempts · recovered, when every attempt but the last failed. Expand the row to see each attempt. Repeated calls that all succeeded stay separate rows.
  • Handoffs have no span. A handoff to another agent shows only as consecutive generations that belong to different agents. All Responses API generations are named Response, so the span name does not say which agent spoke.

The OpenAI Agents SDK page lists what lands where and the blind spots in full.

Set it up

  1. Install the integration and the framework. The full setup is on the OpenAI Agents SDK page.
pip install "glassflow-rius[openai]" openai-agents
  1. Initialize Rius, wrap the entrypoint as an AGENT span and each tool body as a TOOL span. Put @function_tool outermost and observe on the function body, so the framework still reads the signature for its tool schema.
import rius from agents import Agent, Runner, function_tool, set_tracing_disabled from rius import SpanKind rius.init(api_key="ri_...", service_name="my-agent") set_tracing_disabled(True) def lookup(email: str) -> str: return "active" # stand-in for your account lookup @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) print(handle_ticket("Is the account for ana@example.com active?"))
  1. Keep the TOOL kind on every tool you trace yourself. A bare observe makes a CHAIN span, which the Tool kind in the All kinds menu and the Tool Loop alert never see.
  2. If your own code retries a tool, put observe on the function that makes one attempt, so each attempt is its own span and the attempts can collapse into a retry row.
  3. If handoff boundaries matter, add an observe wrapper per agent entry, or use the framework’s RunHooks to open spans at agent boundaries. Use underscores in agent names, because hyphens are rewritten in the generated handoff tool name.
  4. Run one request that fails once and then succeeds. Open it in Traces and check the root AGENT span, the LLM generations and your named TOOL spans.

What you get

  • A recovered badge on runs where steps failed but the run finished clean, so a retried run does not read as a plain failure. Filter the trace list by failed and look for the badge.
  • One retry row per chain, with the attempt count and the recovered state, instead of a wall of identical spans. See Exploring traces for the waterfall and the Map view, where the errors lens shows where failures sit.
  • Failed spans highlighted along the path from the root to the error, with the exception and traceback in the detail panel. In the tree, ]e and [e jump to the next or previous failed span.
  • On the Spans tab, a filter by kind (choose Tool) or by status, to list every failed tool call across runs.
  • Each generation with its model, tokens and cost, so a fallback model shows what it cost. Costs are list-price estimates in US dollars.
  • Compare runs, to put a run that retried next to a clean run of the same agent and see which steps were added or dropped.

For how to keep watching production runs, see Monitor AI agents in production.

When something else fits

  • If your agent is built on another framework or client library, the Integrations page lists what each one records on its own and what needs an observe wrapper.
  • If you need to know which agent spoke at a handoff, the generation names will not tell you. Wrap each agent entry in observe so the boundary has a span.

Still stuck? Get help

Last updated on