What does the gen_ai.agent.name attribute mean in Rius?

In Rius, gen_ai.agent.name holds the name of an agent on an agent span or a tool span, and Rius uses it to file spans under an agent. On an invoke_agent span it is the agent being invoked. On an execute_tool span it is the agent executing the tool. It is one of several keys Rius checks when it decides which agent a span belongs to.

How it works

The key is a plain string, and it appears on two kinds of spans:

• invoke_agent spans: the value is the agent being invoked. Rius treats these spans as the AGENT kind, and the span name follows the convention invoke_agent planner.
• execute_tool spans: the value is the agent that executes the tool. These spans are the TOOL kind. The tool’s own name goes in gen_ai.tool.name, never in gen_ai.agent.name.

Set gen_ai.operation.name or openinference.span.kind and Rius derives the other, so invoke_agent and create_agent map to AGENT and execute_tool maps to TOOL.

Which agent a span is filed under. Rius takes the first of these that is set and is not a placeholder such as unknown_service:

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

So the span-level value decides the agent only when none of the three resource keys above it is set. If your process already sends gen_ai.main_agent.name, that name wins.

Upstream definition. The OpenTelemetry GenAI conventions define the key, at Development stability, as the human-readable name of the agent or workflow provided by the application, such as Math Tutor. It must have low cardinality, so use a stable name, not a run id or a framework default such as a class name. Its registry entry links to the upstream definition.

Older and foreign names. There is no deprecated older spelling of gen_ai.agent.name. Rius does read agent names from two other producers and moves them onto the canonical keys at ingest:

• OpenLLMetry and Traceloop: the name of a decorated agent entity becomes the invoked agent name.
• Laminar: lmnr.association.properties.metadata.agent.name is normalized into the agent name.

Native gen_ai.* keys always win, and normalization only fills gaps. Search and filter on the canonical key.

The attribute is for grouping and labeling. Rius computes cost from the request model and the token counts, not from the agent name. An agent span is not counted as an LLM call, even if it carries a model.

Set it up

1. Make sure your spans reach Rius. Send OTLP over HTTP to the ingest endpoint with your API key. The Trace LLM calls with OpenTelemetry guide covers the setup for each sender in full.

POST https://ingest.eu.console.rius-glassflow.com/v1/traces
Authorization: Bearer <your API key>
Content-Type: application/x-protobuf

2. On the span for each agent run, set gen_ai.operation.name to invoke_agent and set gen_ai.agent.name to the agent’s name. Name the span the way the GenAI conventions ask, for example invoke_agent planner.
3. On each span for a tool the agent runs, set gen_ai.operation.name to execute_tool, set gen_ai.tool.name to the tool’s own name, and set gen_ai.agent.name to the agent that ran it.
4. Name the process’s agent once, on the resource, with gen_ai.main_agent.name. This is the first key Rius checks, so every span from that process files under the same agent, whatever the span-level value says.
5. Open the trace in Rius and check that the span carries the kind and agent name you expect. The full list of keys and what Rius does with each is on the span attribute reference.

What you get

• Agent and tool spans classified by kind in trace views and per-kind analytics, because the operation name implies the kind.
• Spans filed under the agent you named, without registering the agent anywhere.
• Tool spans that show which agent ran them, next to the tool’s own name.
• Agent names carried over from OpenLLMetry, Traceloop and Laminar spans, which Rius moves onto the canonical key at ingest.

When something else fits

• To name the agent a whole process runs, use the resource attribute gen_ai.main_agent.name, which takes priority over the span-level key.
• To name a tool, use gen_ai.tool.name. To compare versions of an agent, send rius.main_agent.version.
• If you only set service.name, Rius uses it as the agent name when nothing else is set.

Related