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
openaiintegration 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. Yourobservewrapper 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
failedwhen 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
TOOLspan 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
- Install the integration and the framework. The full setup is on the OpenAI Agents SDK page.
pip install "glassflow-rius[openai]" openai-agents- Initialize Rius, wrap the entrypoint as an
AGENTspan and each tool body as aTOOLspan. Put@function_tooloutermost andobserveon 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?"))- Keep the
TOOLkind on every tool you trace yourself. A bareobservemakes aCHAINspan, which the Tool kind in the All kinds menu and the Tool Loop alert never see. - If your own code retries a tool, put
observeon the function that makes one attempt, so each attempt is its own span and the attempts can collapse into a retry row. - If handoff boundaries matter, add an
observewrapper per agent entry, or use the framework’sRunHooksto open spans at agent boundaries. Use underscores in agent names, because hyphens are rewritten in the generated handoff tool name. - Run one request that fails once and then succeeds. Open it in Traces and check the root
AGENTspan, theLLMgenerations and your namedTOOLspans.
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
failedand 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,
]eand[ejump 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
observewrapper. - If you need to know which agent spoke at a handoff, the generation names will not tell you. Wrap each agent entry in
observeso the boundary has a span.
Related
Last updated on