What does the gen_ai.main_agent.id attribute mean in Rius?

In Rius, gen_ai.main_agent.id is a resource attribute holding the stable identifier of the agent your process runs, taken from the OpenTelemetry GenAI conventions. The Rius SDKs set it from your configured main agent id, or from the agent name if you configured no id. Its older name, rius.main_agent.id, is deprecated, and the SDKs send both keys during the deprecation window.

How it works

The key sits on the resource, which describes the process that produced the spans, not on any single span. You set it once per process. It is a stable identifier for the agent that process runs.

What the SDKs send:

• The configured main agent id, which you set with RIUS_MAIN_AGENT_ID.
• Otherwise the agent name. RIUS_AGENT_NAME sets that name, and it defaults to the service name.
• No gen_ai.main_agent.* key at all when they have neither.

Two companion keys, gen_ai.main_agent.name and gen_ai.main_agent.description, are sent only alongside the id. RIUS_MAIN_AGENT_DESCRIPTION sets the description.

Rius files a span under an agent by name, not by id. It takes the first of these that is set and is not a placeholder such as unknown_service:

1. The resource gen_ai.main_agent.name
2. The resource rius.main_agent.name
3. The resource gen_ai.agent.name
4. The span’s own gen_ai.agent.name
5. service.name

The older names are deprecated in favor of the gen_ai.main_agent.* keys. rius.main_agent.id is the old form of this key. It carries only an id you configured, never the agent name, so it can be absent when gen_ai.main_agent.id is present. rius.main_agent.description is the old form of the description. rius.main_agent.name is the old form of the name, and Rius still reads it, second after gen_ai.main_agent.name. rius.main_agent.version is not deprecated, because the GenAI conventions have no equivalent. It holds the version of the agent’s definition (prompt, tools, policy), which the Agents page compares.

This key comes from the OpenTelemetry GenAI conventions. Its full definition is in the upstream registry.

Set it up

1. With the Rius SDK, set the id through the environment before the process starts. The values below are your own agent’s:

   export RIUS_MAIN_AGENT_ID=support-agent
   export RIUS_AGENT_NAME=support-agent
   export RIUS_MAIN_AGENT_VERSION=2026-10-26

   RIUS_MAIN_AGENT_VERSION fills rius.main_agent.version, the version the Agents page compares. The variables are read by rius.init() in Python and init() in TypeScript. See SDK installation.

2. Leave the old keys alone. The SDKs send rius.main_agent.id next to gen_ai.main_agent.id, so you do not set both.

3. Without the SDK, with a vanilla OpenTelemetry SDK or a collector, set gen_ai.main_agent.id as a resource attribute on your own telemetry. Also set gen_ai.main_agent.name, because that is the key Rius reads first to name your agent. The attribute reference lists every resource attribute Rius reads. For the end-to-end route, see Trace LLM calls with OpenTelemetry.

4. Never send a cost attribute with it. Rius computes cost from the model and token counts.

What you get

• A stable identifier for the agent travels with the process’s spans, on the resource, so you do not repeat it per span.
• The id comes with the agent name, and with a description when you set RIUS_MAIN_AGENT_DESCRIPTION.
• Spans are grouped under an agent name by the order above, so telemetry that sends only rius.main_agent.name or service.name still lands under a sensible agent.
• Version comparison on the Agents page uses rius.main_agent.version, which you set with RIUS_MAIN_AGENT_VERSION.
• Telemetry from older SDK releases that sends only the rius.main_agent.* keys keeps its agent name.

When something else fits

• To identify one invoked agent, such as a hosted agent, use gen_ai.agent.id and gen_ai.agent.version on invoke_agent spans instead of this process-level key.
• If you only need a display name for the agent, set gen_ai.main_agent.name or rely on service.name, since Rius groups by name.

Related