Skip to Content

How do I see retries and fallbacks in an agent built with the Claude Agent SDK?

Rius shows retries and fallbacks in a Claude Agent SDK agent when you put each attempt in its own span, because the integration records only one generation for the whole runtime turn. Wrap each attempt in your own code with a generation, and Rius groups repeated failed attempts into a single retry row on the trace page. Retries that happen inside the Claude Code runtime do not appear.

How it works

The Claude Agent SDK drives the Claude Code runtime in a separate process, so no model client runs in your process and nothing is instrumented automatically. Coverage is manual and has two parts:

  • An observe wrapper makes each task the root AGENT span.
  • A manual generation wraps the query() loop and is filled from the run’s ResultMessage with tokens, the real model id and the answer.

A task with no retries looks like this:

handle-task AGENT 5.0s └─ claude_agent_turn LLM 5.0s claude-haiku-4-5, tokens + cost

What the integration records on its own is the task and one turn with its totals. What it does not record is anything inside the runtime: tool calls, sub-turns and file operations produce no spans. A retry or fallback the runtime performs internally is therefore invisible.

What needs your own span is a retry or fallback in your code, for example a loop that calls query() again after a failure, or a switch to a second model. Rius builds the retry view from the spans you create:

  • Retry rows. Back-to-back calls of the same step with the same input collapse into one row such as fetch_article · 3 attempts · recovered, when every attempt but the last failed. Repeated calls that all succeeded stay as separate rows.
  • Recovered badge. If child spans errored but the root span finished without an error of its own, the trace is badged recovered. The errors are still counted, only the verdict changes.

Set it up

  1. Set up the manual tracing from the Claude Agent SDK integration. It needs the base package and the claude CLI installed and authenticated:
pip install glassflow-rius claude-agent-sdk
  1. Keep the observe wrapper with kind=SpanKind.AGENT around the whole task, outside your retry loop. The root span then covers every attempt, and it finishes clean when a later attempt or a fallback succeeds.
  2. Move the generation inside your retry loop, so each call to query() gets its own generation. Keep the same generation name and the same input on every attempt, since the retry row groups calls of the same step with the same input.
  3. Fill usage on every attempt from that attempt’s ResultMessage, as the integration page shows, and keep provider="anthropic". An attempt without usage carries no tokens and no cost.
  4. Let a failed attempt end with an error on its span. The Claude Agent SDK reports a failed run on ResultMessage.is_error rather than by raising, so raise inside the generation block when it is true. Rius reads status from error status on the spans, not from anything your agent reports, so an attempt that fails quietly looks like a success.
  5. For a fallback to another model, give it its own generation and pass that model’s full id, such as claude-haiku-4-5, never an alias like haiku. An alias produces a generation with no cost, and cost is computed from the requested model.
  6. If one conversation spans several tasks, scope them with rius.session() so the attempts group under one session.
import rius from claude_agent_sdk import ( AssistantMessage, ClaudeAgentOptions, ResultMessage, TextBlock, query, ) from rius import SpanKind rius.init(api_key="ri_...", service_name="my-agent") MODELS = ["claude-sonnet-4-5", "claude-haiku-4-5"] # first choice, then fallback async def attempt(task: str, model: str) -> str: options = ClaudeAgentOptions(model=model, max_turns=1) parts = [] with rius.start_as_current_generation( "claude_agent_turn", model=model, provider="anthropic", input=task ) as gen: async for message in query(prompt=task, options=options): if isinstance(message, AssistantMessage): parts.extend( b.text for b in message.content if isinstance(b, TextBlock) ) elif isinstance(message, ResultMessage): usage = message.usage or {} gen.set_usage( input_tokens=usage.get("input_tokens"), output_tokens=usage.get("output_tokens"), cache_read_input_tokens=usage.get("cache_read_input_tokens"), cache_write_input_tokens=usage.get("cache_creation_input_tokens"), ) if message.is_error: # the run failed without raising: raise so the span records it raise RuntimeError(f"Claude run failed: {message.subtype}") answer = "".join(parts) gen.set_output(answer) return answer @rius.observe(name="handle-task", kind=SpanKind.AGENT) async def handle_task(task: str) -> str: for model in MODELS: try: return await attempt(task, model) except Exception: if model == MODELS[-1]: raise

Run it with asyncio.run(handle_task("...")).

What you get

Open the trace on the Traces page and read the retries where they happen:

  • Waterfall view. Each attempt is its own span under the root AGENT span, with failed spans highlighted along the path from the root to the error. For an error span, the detail panel leads with the exception and traceback.
  • Retry rows. A run of failed attempts followed by a success reads as one event, and you expand the row for the individual attempts.
  • Recovered badge. A trace where attempts failed but the task finished shows as recovered, so a retried run is not mistaken for a clean one or a failed one.
  • Per-attempt tokens and cost. Each attempt’s generation shows its model, tokens and cost, so you see what the retries spent. Costs are list-price estimates in US dollars.
  • Fallback model. The model on each generation shows which one answered.
  • Spans tab. Filter with All kinds to LLM to list every attempt across runs, and press ]e to jump to the next failed span.

For the full tour of the trace page, see Exploring traces. For watching these runs across your agents, see Monitor AI agents in production.

When something else fits

  • If the retries you care about happen inside the Claude Code runtime, Rius cannot show them, because the runtime’s inner steps produce no spans. Only your own loop and your own fallbacks are visible.
  • If your agent calls model clients directly in your process, such as the Anthropic client, an integration records each call automatically and you need less manual tracing.

Still stuck? Get help

Last updated on