Skip to Content

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

Rius shows LangChain retries and fallbacks in the trace as separate spans, a collapsed retry row, and a recovered badge when the run still finishes cleanly. Once rius.init() runs, the LangChain integration records each step as its own span, so a failed attempt and the attempt after it sit side by side in the waterfall. You add a span of your own only for retry logic that lives outside LangChain.

How it works

The LangChain integration hooks LangChain’s callback system. Anything that runs through it gets one span per step: chains as CHAIN spans, tools as TOOL, retrievers as RETRIEVER, and model calls as LLM spans with model, token usage and messages. Nesting follows your chain or graph, so a trace reads like the execution graph.

That gives you the raw material for retries and fallbacks:

  • A retried step appears as one span per attempt when the retry runs through LangChain, such as a runnable wrapped with .with_retry(). Rius reads a span as failed when it carries an OpenTelemetry ERROR status, normally a recorded exception.
  • A chat model’s own retries do not. max_retries on ChatOpenAI or ChatAnthropic (2 by default) is handed to the provider client, which retries inside one model call. You see one LLM span covering every attempt, failed only if the last attempt failed.
  • A fallback model call from .with_fallbacks() appears as another model-call span in the tree, and the span’s Model section shows its requested and response model.
  • A run that recovers is marked for you. A trace with failed child spans whose root span finished without an error of its own is badged recovered. The errors still count, and only the verdict changes.

The trace page then adds two reading aids on top of those spans:

  • Retry chains. 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. This happens when every attempt but the last failed. Repeated calls that all succeeded stay as separate rows, and a retry that changes its input does not collapse.
  • Failed-span highlighting. In the waterfall, failed spans are highlighted along the path from the root to the error.

For retry loops you write yourself, wrap each attempt in observe with kind=SpanKind.TOOL and give the function a name. Spans from a bare observe are CHAIN spans, so the Tool kind in the Spans tab never lists them. If the step you retry is already a LangChain tool, the integration records it and you add nothing.

Set it up

  1. Install the integration and initialize Rius once at startup. The full setup, including TypeScript, is on the LangChain page, and Integrations lists the others.

    pip install "glassflow-rius[langchain]" langchain
    import rius rius.init(api_key="ri_...", service_name="my-agent") # build and run your chains exactly as before
  2. Run a chain that retries or falls back, then open Traces. Filter the status to failed to find runs with an errored span. A run that retried or fell back and still completed shows the recovered badge.

  3. Open the trace. Look for a collapsed row like fetch_article · 3 attempts · recovered and expand it to read each attempt. For a fallback, find the failed model-call span and the model-call span after it, and compare the models in each span’s Model section.

  4. If you wrote the retry loop yourself, outside LangChain, wrap the attempted step in observe with kind=SpanKind.TOOL and keep the function name the same on every attempt. Same name and same input is what lets the retry chain row form.

  5. To jump between failures, press ]e for the next failed span and [e for the previous one. On the Spans tab, filter by status or by kind with the All kinds menu. In a span’s Raw tab, the menu next to an attribute offers Filter traces by this, which narrows the trace list to that value.

For the full tour of lists, filters and span panels, see Exploring traces.

What you get

  • Every attempt as its own span, with its error, timing, and for model calls the model, tokens and cost.
  • One readable row for a retry loop that ended in success, instead of a wall of identical spans.
  • A recovered badge that separates runs that hit errors and finished from runs that failed outright.
  • A way to see a fallback as it happened: the failed call, then the next call with its own model.
  • Trace-level context for each run, such as duration, span and error counts, total tokens and cost.

Step inputs, outputs and messages are content attributes, so the SDK’s privacy controls apply to the whole tree. This is how you decide whether the inputs that retry rows compare are sent at all. For a wider view of running agents, see Monitor AI agents in production.

When something else fits

  • If your retry logic runs outside LangChain’s callbacks, the integration does not see it. Wrap those attempts with observe as above.
  • If you want each provider-level retry as its own span, set max_retries=0 on the chat model and retry with .with_retry() instead, so every attempt runs through LangChain.
  • If a retried step changes its input each time, it appears as separate rows rather than one retry row. Read the attempts in the waterfall instead.
  • If you want a trace to state “this was a fallback” in your own words, that needs a span or attribute of your own naming the step.

Still stuck? Get help

Last updated on