What does the rius.main_agent.version attribute mean in Rius?

Rius reads rius.main_agent.version as the version of your agent’s definition, meaning its prompt, tools and policy. It is a string you choose, such as 7 or 2026-10-01, and it is separate from service.version. The Agents page compares agent versions using this value. The key has no older name that Rius reads it from.

How it works

• What the key holds. A string naming the version of the agent definition the process runs: its prompt, tools and policy. The registry gives 7 and 2026-10-01 as examples. Rius does not interpret the string, so use any scheme you can tell apart later.
• It is not the service version. service.version is the build or release the process runs. The two move independently: a service can sit at 2.3.1 while its agent definition is at 7. Rius does not derive one from the other, because that gives wrong data whenever they disagree. Set both if you want both.
• Which spans carry it. It is a resource attribute. It describes the process, so you set it once for the process instead of on each span, alongside service.name, service.version and gen_ai.main_agent.id.
• What Rius shows from it. The Agents page compares two versions of an agent on traces, failed rate, cost per trace, latency, time to first token (p50) and tokens per trace. It adds drift charts and a context section. When either side has fewer than 20 traces, the comparison shows a warning.
• Older names. None. The sibling keys rius.main_agent.name, rius.main_agent.id and rius.main_agent.description are deprecated in favor of gen_ai.main_agent.* keys. rius.main_agent.version is not deprecated, because the OpenTelemetry GenAI conventions have no equivalent key. It is the only key for this fact. Its stability in the registry is Development.

Set it up

1. Pick a version string that changes whenever you change the prompt, the tool set or the policy. A counter or a date both work.
2. If you use the Rius SDK, set the version with the environment variable that the SDKs read for this key, before the process starts:

export RIUS_MAIN_AGENT_VERSION=7

3. If you send spans without the Rius SDK, add rius.main_agent.version to the resource of your tracer provider, as a string. Setup for each sender is on Trace LLM calls with OpenTelemetry, and the full list of resource attributes Rius reads is in the span attribute reference.
4. Change the value on every deployment where the agent definition changes, and leave it alone when only the code around the agent changes. If you also bump service.version on every release, the two values can differ, which is expected.
5. Send enough traffic to each version. The comparison warns below 20 traces per side, so give a new version time to collect traces before you read the numbers.

The key’s type, stability and examples are in the rius namespace registry.

What you get

• A version label on the process’s telemetry that follows the agent definition, not the deployment pipeline.
• A side-by-side comparison of two versions on failed rate, cost per trace, latency, time to first token (p50) and tokens per trace, so you can tell whether a prompt or tool change helped.
• Cost in the comparison is a list-price estimate in US dollars, computed by Rius from the model and token counts. You never send a cost value.
• Drift charts of the agent’s TTFT, cost per trace and failed rate over time, and a Context section on the agent’s page.
• No migration work. Nothing replaces this key, so what you set today stays the right key.

When something else fits

• If you only need to know which build is running, service.version already covers it, and you can leave rius.main_agent.version unset.
• If you want to group by the agent’s identity or name, use gen_ai.main_agent.id and gen_ai.main_agent.name. They answer which agent, while this key answers which definition of it.

Related