How can I see which agent version handled a request for my AI agent?

Rius shows the agent version on each trace once your spans carry it as the resource attribute rius.main_agent.version. It appears in the Version column of the trace list and in the header of a trace’s waterfall view. You can also filter the list by it to see only the runs one version handled.

How it works

A version is not a property of a single step, it is a property of the process that ran the request. That is why Rius reads it from the resource attributes, which ride on every span the process exports.

• The attribute. Rius reads the agent version from rius.main_agent.version. The SDKs fill it from the RIUS_MAIN_AGENT_VERSION environment variable.
• Trace list. A Version column appears when the traces carry a version. It shows the agent version, or the build when there is no version. Clicking a user, sender or agent cell filters the list, and you can add your own filter on the version.
• Waterfall. When you open a trace, the header summarizes the whole run: duration, span and error counts, tokens and cost. It also names the agent version, and the build, when the trace carries them.
• Span details. The version is not a section of its own on a single span. Open the span’s Raw tab, which shows the span exactly as ingested, to check which attributes arrived. Each attribute there has a Filter traces by this menu.

If the trace carries no version, the column and the header entry do not show. That is the first thing to check when you do not see it.

Set it up

1. Choose a version string that changes whenever the agent definition changes (its prompt, tools or policy), such as prompt-v12. It is your own value. Tag the build separately with RIUS_SERVICE_VERSION.
2. Set it in the environment of the process that runs your agent, before the process starts:

export RIUS_MAIN_AGENT_VERSION=prompt-v12

3. Initialize the SDK as usual. If you have not done that yet, Monitor AI agents in production walks through the full setup. If you send traces without the Rius SDK, set rius.main_agent.version yourself as a resource attribute on your exporter.
4. Run a request, then open Traces in the console. The time range presets are 15m, 1h, 1d, 7d (the default), 30d and a custom range, so make sure the range includes your new traces.
5. Look for the Version column in the list. Click a trace to open the waterfall and read the version in its header.
6. To see one version’s runs only, click Add filter, pick the field rius.main_agent.version, choose the operator is and pick the value. Attribute filters match exact values only, so prompt-v12 does not match prompt-v1. Filters live in the URL, so you can copy the link to a teammate.
7. To confirm what arrived on a particular span, open it and go to the Raw tab, then use Filter traces by this on the version attribute.

The other end of the page matters too: Exploring traces covers the list, waterfall and span panel in full, and Concepts explains how agents, instances, traces and spans relate.

What you get

• A Version column on every trace row, so you can tell at a glance which version handled each request.
• The agent version in the header of each trace’s waterfall, next to the end user, the session and the cost.
• A filter on rius.main_agent.version, so you can list the traces for one version, or exclude it with is not.
• A link you can copy that opens the same filtered list, which helps when you hand a failing request to a teammate.
• The same version value is the one the Agents page compares, so what you set once serves both the per-request view and the version comparison.

When something else fits

• If you want to know which running process handled a request rather than which version, use the instance. Every span carries service.instance.id, and a fresh instance id is minted on each process start.
• If you want to judge whether a new version is better overall, use the version comparison on the Agents page rather than reading traces one by one.

Related