Which OpenTelemetry attribute should my spans use for agent name?

Rius reads the agent name from gen_ai.agent.name on each invoke_agent span, and from the resource attribute gen_ai.main_agent.name for the agent your process runs. Set gen_ai.main_agent.name once on the resource, and set gen_ai.agent.name on the spans that invoke the agent or run its tools. Rius still reads the older rius.main_agent.name, so telemetry that already sends it keeps its agent name.

How it works

Two levels carry an agent name. Each has its own attribute.

• Resource level: gen_ai.main_agent.name names the agent the whole process runs. Without the Rius SDK, set this key to name your agent. Rius groups traces and the Agents view by it.
• Span level: gen_ai.agent.name goes on invoke_agent spans, where it is the agent being invoked. It also goes on execute_tool spans, where it is the agent executing the tool.

Rius files a span under 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 gen_ai.agent.name
5. service.name

So service.name is the last fallback. If you set nothing else, your agent shows up under your service name.

Rius keys, deprecated and current:

• rius.main_agent.name is deprecated in favor of gen_ai.main_agent.name. It is read second, so existing telemetry is not affected. The Rius SDKs send both keys through the deprecation window.
• rius.main_agent.id and rius.main_agent.description are deprecated in favor of gen_ai.main_agent.id and gen_ai.main_agent.description.
• rius.main_agent.version is not deprecated, because the GenAI conventions have no equivalent. It carries the version of the agent’s definition.

Other conventions Rius normalizes:

• From OpenLLMetry (Traceloop), the name of the decorated entity becomes the invoked agent name.
• From Laminar, lmnr.association.properties.metadata.agent.name is normalized to the agent name.

Normalization fills gaps and never overwrites. A native gen_ai.* key always wins. Search and filter on the canonical key, not on the source key.

Set it up

1. Set gen_ai.main_agent.name as a resource attribute, next to service.name, in your OpenTelemetry resource configuration. This names the agent your process runs.
2. On every invoke_agent span, set gen_ai.operation.name to invoke_agent and gen_ai.agent.name to the agent’s name. Rius derives the AGENT span kind from the operation. On execute_tool spans, set gen_ai.agent.name to the agent that ran the tool, plus gen_ai.tool.name for the tool itself. Name the spans the way the GenAI conventions ask, such as invoke_agent planner.
3. Check the result. The example below shows the attributes on a resource and its spans.

Resource attributes
  service.name = support-bot
  gen_ai.main_agent.name = support-agent

Span: invoke_agent planner
  gen_ai.operation.name = invoke_agent
  gen_ai.agent.name = planner

Span: execute_tool get_weather
  gen_ai.operation.name = execute_tool
  gen_ai.agent.name = planner
  gen_ai.tool.name = get_weather

4. If you use the Rius SDK, set the name with the RIUS_AGENT_NAME environment variable. It defaults to the service name.

export RIUS_AGENT_NAME=support-agent

The full list of attributes, including content and session keys, is on the span attribute reference. For sending spans without the SDK, see Trace LLM calls with OpenTelemetry.

What you get

• Traces grouped under your agent’s name instead of a generic service name.
• Spans classified as agent steps and tool runs, because invoke_agent maps to the AGENT kind and execute_tool to TOOL.
• Tool spans tied to the agent that executed them.
• Existing telemetry that sends rius.main_agent.name, or that comes from OpenLLMetry or Laminar, keeps its agent name without changes.
• A way to compare versions of one agent, when you also set rius.main_agent.version.

When something else fits

• If one process runs one agent and the service name already describes it, service.name alone is enough, because Rius falls back to it.
• If you only need to name the tool that ran, use gen_ai.tool.name. gen_ai.agent.name names the agent, not the tool.

Related