Skip to Content

How do I see which agent version handled a request in an agent built with the Claude Agent SDK?

Rius shows the agent version on each trace when you set RIUS_MAIN_AGENT_VERSION for your Claude Agent SDK process, because the integration does not record a version itself. Set the variable before the agent starts, run a task, and the version appears in the Version column of the trace list and in the header of the trace. You can then filter traces by it.

How it works

The Claude Agent SDK drives the Claude Code runtime in a separate process, so Rius has no model client to hook in your process. Coverage is manual, and the Claude Agent SDK integration records two things on its own terms:

  • The root span for each task, which is the observe wrapper you write with kind SpanKind.AGENT.
  • One generation for the whole runtime turn, filled from the run result with the model id, tokens and cost.

A trace looks like this:

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

Neither span carries an agent version. The model id on the generation is the model that answered, not the version of your agent, so do not read it as one.

The version comes from a setting of your own. RIUS_MAIN_AGENT_VERSION sets rius.main_agent.version, a resource attribute that Rius reads as the agent’s version. Both SDKs read the variable, so you do not change your observe wrapper or your generation. Set it once for the process, and the traces that process sends carry it.

The runtime’s inner steps, such as tool calls and file operations, produce no spans, so the version appears on the traces you already see and not on separate steps.

Set it up

  1. Install the SDK and add the root span and generation from the Claude Agent SDK integration page. That page has the full setup and the runnable code.
  2. Choose a version string for your agent definition, meaning its prompt, tools and policy, such as a release number. The build or deploy goes in RIUS_SERVICE_VERSION, which the Agents page offers as Build.
  3. Export it in the environment that starts your agent, before the process runs:
pip install glassflow-rius claude-agent-sdk export RIUS_MAIN_AGENT_VERSION=1.4.0
  1. Run one task through your handle-task wrapper, then open Traces in the console.
  2. Look for the Version column in the list. It appears when the traces carry a version. Open the trace and check the header, which shows the agent version next to the session and the end user.
  3. Change the value when you ship a new build, so each deployment shows under its own version.

To narrow the list to one version, click Add filter, pick the field from the attributes your agents send, choose is and type the version. Filters match exact values only, and the link you copy keeps the filter. Each trace belongs to the process that sent it, so two builds running at the same time show as two versions side by side.

If you also scope tasks with rius.session(), the trace header links the session and shows the version beside it. Read the Integrations page for how the other frameworks handle the same setting.

What you get

  • The agent version on every trace the process sends, in the Version column and in the trace header.
  • A filter on the version, so you can list only the requests that one build handled.
  • A way to tell two builds apart when a failure appears after a deploy. Open a failing trace, read its version, and compare it with traces from the earlier version.
  • Version comparison on the Agents page, which uses the same rius.main_agent.version value to compare two versions on failed rate, cost per trace, latency and tokens per trace.
  • The trace views as before, with the per-task root span, the generation, tokens and cost. For the trace page itself, see Exploring traces. For the wider workflow, see Monitor AI agents in production.

When something else fits

  • If you need the version to change per request inside one running process, a single environment variable does not do it, because it is set once for the process. Run each build as its own process.
  • If you only need to know which model answered, the generation already records the real model id, and you need no version setting for that.
  • If the Version column does not appear, the traces carry no version yet, so check that the variable is set in the environment of the process that runs the agent.

Still stuck? Get help

Last updated on