Skip to Content

How do I see retries and fallbacks in an agent built with Pydantic AI?

Rius records each Pydantic AI run as an invoke_agent root, each model request as a chat span with tokens and cost, and each tool call as an execute_tool span. A retry or fallback decision made in your own code gets a span of its own when you wrap each attempt with rius.observe. Failed attempts are highlighted in the trace, and a run that recovers is badged recovered.

How it works

What the integration records on its own. rius.init() installs the global OpenTelemetry tracer provider, and Agent.instrument_all(True) makes Pydantic AI emit its spans through it. You get three kinds of span with no wrappers:

  • The run root, named invoke_agent <agent name>.
  • One generation per model request, named chat <model>, with tokens and cost.
  • One span per tool call, named execute_tool <tool name>.

Spans are named after your agents, models and tools. A request to a second model therefore shows up under that model’s own name.

Retries Pydantic AI makes itself. When a tool raises ModelRetry, or the output fails validation, the framework sends the error back to the model and asks again, up to the agent’s retries setting (1 by default). Each new attempt is one more chat span, and for a tool one more execute_tool span, inside the same run. The provider client under the model also retries a failed HTTP request on its own (the OpenAI and Anthropic clients retry twice by default). Those attempts happen inside one request, so they never show as separate spans.

What needs a span of your own. Your own retry loop or fallback choice is plain Python in your code, so wrap each attempt in rius.observe. A bare observe makes a span named after the function. The attempt then has a visible name in the trace, and a failed attempt is a failed span you can find.

Where it shows. Open the trace on the Traces page and read the waterfall:

  • Failed spans are highlighted along the path from the root to the error.
  • A failed trace whose root span finished without an error of its own is badged recovered. Child spans errored, the run retried or fell back, and the run itself completed clean. The errors are still counted.
  • Back-to-back calls of the same tool or step with the same input collapse into one row such as fetch_article · 3 attempts · recovered, when every attempt but the last failed. Expand the row to see each attempt.

See Exploring traces for the full tour of these views.

Set it up

  1. Install the SDK and Pydantic AI. No extra is needed. The Pydantic AI integration page covers the setup in full, and the integrations overview lists the other frameworks.

    pip install glassflow-rius pydantic-ai
  2. Initialize Rius and turn on Pydantic AI instrumentation. Wrap each attempt in rius.observe, and keep the retry or fallback decision in a function that calls them. In this example the agents, model names and function names are yours to change.

    import rius from pydantic_ai import Agent rius.init(api_key="ri_...", service_name="my-agent") Agent.instrument_all(True) primary = Agent("openai:gpt-5-mini", instructions="Answer support questions.") backup = Agent("anthropic:claude-haiku-4-5-20251001", instructions="Answer support questions.") @rius.observe def ask_primary(ticket: str) -> str: return primary.run_sync(ticket).output @rius.observe def ask_backup(ticket: str) -> str: return backup.run_sync(ticket).output @rius.observe def handle(ticket: str) -> str: try: return ask_primary(ticket) except Exception: return ask_backup(ticket)
  3. Scope each conversation with rius.session(), reusing your conversation id, so every run of a conversation groups together. The framework’s spans inherit that scope.

  4. Run one request that fails on the first attempt, then open the trace. Look for the failed ask_primary span, the ask_backup span after it, and the chat span named for each model that was called.

  5. To find these runs later, filter Traces by status failed. On the Spans tab, press ]e to jump to the next failed span.

What you get

  • Every model request and tool call from Pydantic AI as its own span, with tokens and cost on the chat spans.
  • Your retry and fallback steps as named spans, so a reader can tell the first attempt from the second.
  • Failed attempts highlighted in the waterfall, and the recovered badge on runs that failed in the middle and completed clean.
  • Retry chains collapsed into one row with an attempt count, so a retry loop reads as one event instead of a wall of identical spans.
  • A side-by-side Compare runs view against another run of the same agent, to see which steps were added or dropped.

The model-request and tool-call spans come from the integration with no code. The retry and fallback spans appear only for the attempts you wrap. For the wider picture of watching agents in production, see Monitor AI agents in production.

When something else fits

  • If you only need to know that a run failed, the failed and recovered statuses and the failed-span highlights already give you that, with no wrappers.
  • If your retry or fallback logic sits outside Pydantic AI, for example in a gateway or proxy, Rius shows only the requests that reach your agent. Rius does not offer gateway features such as retries and fallbacks itself.

Still stuck? Get help

Last updated on