How do I name my agent in Rius when it uses LlamaIndex?

Rius names your LlamaIndex agent from the service_name you pass to rius.init, and that name appears on every span and on the Agents page. Set agent_name only if several services form one logical agent. Put the version in service_version or main_agent_version, never in the name.

How it works

The name comes from the same settings as any other agent that sends traces to Rius. The LlamaIndex integration (Python only) adds the spans for query engines, retrievers, embeddings and model calls, and the name is stamped on top of them.

• service_name (RIUS_SERVICE_NAME) becomes the service.name resource attribute on every span. It defaults to unknown_service, so set it. It is how you find the agent in trace filters, analytics and cost breakdowns.
• agent_name (RIUS_AGENT_NAME) controls how instances group on the Agents page. It defaults to service_name. Set it separately only when several services form one logical agent.
• service_version (RIUS_SERVICE_VERSION) is the build or release this process runs, stamped as service.version.
• main_agent_version (RIUS_MAIN_AGENT_VERSION) is the version of the agent definition, meaning its prompt, tools and policy, stamped as rius.main_agent.version. It moves independently of the build.

Rius picks the agent name from the first of these that is set: gen_ai.main_agent.name on the resource, rius.main_agent.name on the resource, gen_ai.agent.name on the resource, gen_ai.agent.name on the span, then service.name. The SDK sets the main-agent keys for you, so in practice your agent_name, or your service_name when you leave it out, is the name you see.

Keep the name constant across replicas and deploys. Each process start is a new instance under the same name, so three replicas show as three instances of one agent. An agent that sends no name of its own, or only the unknown_service placeholder, does not appear in the Agents list.

Set it up

1. Install the SDK with the LlamaIndex extra. The extra installs the instrumentation, not llama-index itself. The installation page covers the rest of the setup, and the LlamaIndex integration page covers what gets captured.

   pip install "glassflow-rius[llama-index]" llama-index

2. Call rius.init once, before you build indexes and query engines, and give it the name. This example sets agent_name to the same value as service_name, which is also the default if you leave it out.

   import rius
    
   client = rius.init(
       api_key="ri_...",
       service_name="support-rag-agent",
       agent_name="support-rag-agent",
   )
   # build indexes and query engines exactly as before

3. Keep versions out of the name. Set them in the environment so Rius can compare releases:

   RIUS_MAIN_AGENT_VERSION=prompt-v12      # the agent definition: prompt, tools, policy
   RIUS_SERVICE_VERSION=2026.09.29-a41f3c  # the build or deploy

4. Decide whether you need a stable identity. Without main_agent_id (RIUS_MAIN_AGENT_ID), gen_ai.main_agent.id falls back to the agent name, so renaming the agent also changes that id. Set main_agent_id to an id that survives restarts and renames, such as a registry id. Do not use a per-process id, because every restart would look like a new agent.

5. Run one query, then open Agents. Your agent shows an instance in running or ready. When the process exits normally it moves to stopped. If your process is stopped with SIGTERM, call client.shutdown() from your own handler so it does not end as gone.

The SDK stamps the name when you call init, so choose it before the first deploy. Renaming later does not re-key history. Stored spans keep the old service.name and stay filterable under it, the new name starts empty, and the old name’s instances report gone until their heartbeat records age out.

What you get

• The agent name on every span as service.name, so you can filter traces, analytics and cost breakdowns to this one agent. Each LlamaIndex query appears as nested spans for retrieval, embedding and the model call, under that name.
• A row on the Agents page with its instances, traces, errors, time to first token and cost. Open the agent for context usage, recent traces, errored traces, exceptions and lifecycle events.
• Version comparison. With RIUS_MAIN_AGENT_VERSION set, Versions and Drift show whether a new prompt or model changed the failed rate, cost per trace or time to first token. Rius warns when either side of a comparison has fewer than 20 traces.
• Replicas grouped under one name, each with its own instance status.
• Costs per call as list-price estimates in US dollars, computed by Rius from the model and token counts. You never send a cost value.

For how the integrations fit together, see Integrations.

When something else fits

• If one logical agent runs as several services, set agent_name apart from service_name so they group together, and keep service_name distinct per service.
• If you use LlamaIndex.TS, the Python integration does not apply. Use the OpenAI integration for provider calls, and observe or startAsCurrentSpan (for example a RETRIEVER span) for the rest of the pipeline.
• If you send traces through a plain OpenTelemetry SDK instead of the Rius SDK, set the main-agent names as resource attributes. You then get no heartbeats, so Instances and Lifecycle events stay empty.

Related