How can my coding agent compare two versions of an agent in Rius?

Rius gives your coding agent the compare_agent_versions tool on its MCP server, which puts two versions of one agent side by side over the same time window. Ask in plain words, such as “Did planner’s version 8 make things worse than 7 this week?”, and your client fills in the agent, the version dimension, the base and head versions, and the window. You get traces, failed rate, cost per trace, latency p50, time to first token p50 and tokens per trace, with the change from base to head. Your client can call agent_versions first to learn which version values exist.

How it works

The tool takes one agent and compares two of its versions over one window. The main parameters are:

• agent: the exact agent name. Required.
• dimension: which version identity to compare. Required. Use agent for the agent definition (prompt, tools, policy), stamped as rius.main_agent.version. Use service for the build, stamped as service.version (build is accepted as a synonym). The two move independently, so they are not interchangeable.
• base: the older version’s exact value. Required.
• head: the newer version’s exact value. Required. The change is head measured against base.
• hours, or start and end: the window. hours defaults to 24, and start and end are RFC3339 timestamps that override it.
• workspace and instance: optional. workspace picks a workspace by name or ID, and instance narrows both sides to one running copy of the agent.

To find the exact version values and the agent name, your client uses agent_versions for that agent, which lists the versions that ran in the window and labels each as an agent or service version. Agent names come from list_agents or the root_agent column of list_agent_traces.

The tool runs the same trace summary twice, once per version, using the same six rows and change rules as the compare tiles in the Rius console. An agent and a human therefore read the same change. The full argument list is in the tool reference.

Set it up

1. Connect your client to the Rius MCP server once. For Claude Code, run:

claude mcp add --transport http rius https://mcp.eu.console.rius-glassflow.com/mcp

If you use the Rius plugin, it already registers this server as rius. For other clients, and for headless agents that authenticate with a read-scoped API key, follow the MCP page. A read-scoped key can use this tool.

2. Make sure each version stamps itself. Set RIUS_MAIN_AGENT_VERSION for the agent definition, which is the version the Agents page compares, and RIUS_SERVICE_VERSION for the build. Without a version on your traces there is nothing to compare.

3. Ask your client in plain words. It picks the tools and arguments itself:

   • “Which versions of planner ran this week?” The client calls agent_versions.
   • “Did planner’s version 8 make things worse than 7 this week?” The client calls compare_agent_versions.
   • “Compare the last two builds of planner.” The client compares on the build dimension.

4. If you want to see what the client sends, these are the calls behind the last two questions:

{
    "name": "compare_agent_versions",
    "arguments": {
        "agent": "planner", "dimension": "agent", "base": "7", "head": "8",
        "hours": 168
    }
}

{
    "name": "compare_agent_versions",
    "arguments": {
        "agent": "planner", "dimension": "service", "base": "2.3.1", "head": "2.4.0"
    }
}

5. Widen the window when a version is new or quiet. Pass hours: 168 for a week, or start and end for exact dates.

What you get

The reply is Markdown, which your client renders as a table. It holds six rows for the two versions: traces, failed rate, cost per trace, latency p50, time to first token p50 and tokens per trace. Each row carries the change from base to head.

• The failed rate changes in percentage points, for example “+1.0 pp”, never as a percent of the base.
• The other rows change as a percent of the base.
• A dash means one side is unknown or the base is zero. It never means “no change”.
• Below 20 traces on either side, the reply says the differences can be noise. It never claims statistical significance either way.

Costs are list-price estimates in US dollars, not billed amounts.

The tool refuses to answer where the deployment does not offer the version filter, instead of returning the whole agent’s numbers on both sides and showing a false “no change”. If your client reports a refusal, treat it as the answer and not as a zero difference.

The same comparison is also on the Agents page of the console, so you can check what your agent tells you.

When something else fits

• To see whether one version is drifting over time rather than comparing two, ask for agent_traces_summary with group_by set to bucket. Add a filters clause to scope it to one model.
• To find out why a version fails, use agent_error_groups to group its errors, then get_agent_trace for a full span waterfall.
• For connection details, auth options and key scopes, see the MCP page, and for general monitoring see Monitor AI agents in production.

Related