Skip to Content

How do I monitor a multi-agent workflow in production?

Rius makes a multi-agent workflow readable by tracing the run as a waterfall of spans: a root span for the run, a span for each LLM call, and a span for each tool or agent step. Once it is live, you watch the Agents page for errors, cost, drift and instance health, and rely on alerts for recurring errors and tool loops. The setup is the one in Monitor AI agents in production, plus a few choices about span kinds, names and versions.

How it works

A run of a multi-agent workflow appears in the Traces view as one waterfall, from the root span down to every step beneath it.

  • The run. Wrap your entry point with observe and pass kind=SpanKind.AGENT (kind: SpanKind.AGENT in TypeScript). A bare observe records a CHAIN span, so the kind is what marks a step as an agent step.
  • Each LLM call. With a global init(), every installed integration is turned on automatically. Each call becomes a generation span with its model, token counts and cost, computed by Rius from the spans. You never send a cost value.
  • Each tool or retrieval step. A retrieval or search step gets observe with kind=SpanKind.RETRIEVER and a data_source_id. A function the model calls as a tool gets kind=SpanKind.TOOL. Tool Loop alerts need TOOL spans, so this kind also powers an alert.
  • Framework integrations. If you use a supported agent framework, its integration emits its own tool and agent spans, so you may not need to wrap anything.

Token counts, cost and errors sit on the spans, so you can see which step in a run failed or spent the most. Cost is a list-price estimate in US dollars.

Rius finds agents from your traces and heartbeats, with no registration. The SDK sends a heartbeat by default, so each process shows as an instance under its agent name.

Set it up

  1. Install the SDK with the extra for your LLM library and call init(), as the Monitor AI agents in production guide shows in full.

    pip install "glassflow-rius[anthropic]" anthropic

  2. Give the run a root span. Wrap the workflow’s entry point with observe and kind=SpanKind.AGENT. The span is named invoke_agent followed by the agent name, not the function name.

  3. Wrap each tool, retrieval step and sub-agent entry point with observe, using kind=SpanKind.TOOL for tools, kind=SpanKind.RETRIEVER for retrieval, and kind=SpanKind.AGENT with agent_name= for each sub-agent, so each shows under its own name.

  4. Name your agents. Set agent_name in init() or RIUS_AGENT_NAME; it defaults to the service name. If the agents in your workflow run as separate processes, give each its own name so each gets its own row on the Agents page.

  5. Tag the version so you can compare releases:

    RIUS_MAIN_AGENT_VERSION=prompt-v12      # the agent definition: prompt, tools, policy
RIUS_SERVICE_VERSION=2026.09.29-a41f3c  # the build or deploy

  6. Call shutdown() from your SIGTERM handler. A process killed without it ends as gone instead of stopped, which makes crashes and deploys hard to tell apart. In a short TypeScript script, end with await rius.shutdown() so queued spans are exported.

  7. Create a channel (Slack, email or webhook) and attach it to each alert from that alert’s Delivers to section. A workspace admin does this. Without a channel, a firing is only a row on the Alerts page.

What you get

Views to watch once it is live

  • Traces. Open a run to see the waterfall of generations, tool spans and agent spans, with tokens, cost and errors on each span.
  • Agents list. Scan the Errors and Cost columns.
  • Error rate against failed traces. A high error rate with few failed traces means the workflow recovers, for example through retries or fallbacks. A failed trace is a run whose root span ended in error. Traces count toward the agent that is their root agent.
  • Drift and Versions. Charts for time to first token, cost per trace and failed rate show change over time. Compare two versions side by side. Rius warns when either side has fewer than 20 traces.
  • Exceptions. Errored spans grouped by failure type show whether many errors come from one cause or several.
  • Context. Peak usage shows how close the largest call came to the model’s context window.
  • Instances. stopped means a clean exit. gone usually points to a crash, an out-of-memory kill or a deploy. Heartbeats show that a process is alive, not that it is making progress, so a hung process that still sends heartbeats shows as running.

Alerts

  • Consistent Error Pattern fires when the same error recurs across runs.
  • Swallowed Error fires when a run reports success while a step inside it that is not a tool call failed. Errored tool calls do not count, because the model saw the failure.
  • Tool Loop fires when the same tool is called with identical arguments three or more times in a row within one trace. An admin can disable it.
  • Custom alerts let you set thresholds on metrics such as cost, duration, error rate and tokens, filtered by service, agent, step or model.

When something else fits

  • If you already send OpenTelemetry GenAI spans from another SDK or a collector, you can keep that setup and send traces to Rius without the Rius SDK. Heartbeats need the Rius SDK, so the Instances view stays empty without it.
  • If you need evals, scoring or guardrails on your workflow, Rius does not offer them. It traces, prices and alerts on agent runs.

Still stuck? Get help

Last updated on
Quickstart