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

Rius names your LiteLLM agent from the service_name you pass to rius.init(), and you set the version next to it with service_version. The name appears on every span, including the span for each LiteLLM completion. It also appears as the agent’s row on the Agents page. Set it once, keep it constant, and put version numbers in their own settings instead of in the name.

How it works

• The name comes from init(), not from LiteLLM. service_name (or RIUS_SERVICE_NAME) becomes the service.name resource attribute on every span the SDK exports. That includes the span for each routed completion. Explicit arguments win over environment variables, which win over defaults.
• Set it explicitly. The default is unknown_service. An agent that sends only that placeholder does not appear in the Agents list.
• agent_name is optional. agent_name (or 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.
• The version goes next to the name, not in it. service_version (RIUS_SERVICE_VERSION) is the build or release and becomes service.version. main_agent_version (RIUS_MAIN_AGENT_VERSION) is the version of the agent definition, meaning its prompt, tools and policy, and becomes rius.main_agent.version. The two move independently, so the SDK never derives one from the other.
• Treat the name as an identifier. Each process start is a new instance under the same name, so three replicas show as three instances of one agent. Renaming does not re-key history. Stored spans keep the old service.name, the new name starts empty, and the old name’s instances report gone until their heartbeat records age out. Without a main_agent_id, a rename also changes gen_ai.main_agent.id, so set main_agent_id if you want an identity that survives a rename.

The LiteLLM integration turns on automatically with a global init(). The same naming applies to every other library listed under Integrations.

Set it up

1. Install the LiteLLM instrumentation. The extra installs the instrumentation, not litellm itself. Full install details are on the installation and configuration page.

   pip install "glassflow-rius[litellm]" litellm

2. Pass the name and both versions to init(), before your first litellm.completion call. Replace the values with your own.

   import rius
   import litellm
    
   client = rius.init(
       api_key="ri_...",
       service_name="checkout-agent",
       service_version="2026.09.29-a41f3c",
       main_agent_version="prompt-v12",
   )
    
   response = litellm.completion(
       model="gpt-4o-mini",  # or any provider LiteLLM routes to
       messages=[{"role": "user", "content": "hi"}],
   )
    
   client.shutdown()  # sends the final stopped heartbeat

3. If you prefer configuration outside the code, set the same values in the environment. Only the RIUS_* names are read.

   export RIUS_SERVICE_NAME=checkout-agent
   export RIUS_SERVICE_VERSION=2026.09.29-a41f3c
   export RIUS_MAIN_AGENT_VERSION=prompt-v12

4. Verify. Run one completion and open the Agents page. Your agent is listed under the name you chose, with an instance in running or ready. When the process exits normally, or after you call shutdown(), the instance moves to stopped. If your process is stopped with SIGTERM, call client.shutdown() from your own signal handler so it ends as stopped instead of gone.

Heartbeats, which power the instance status, need credentials, so pass an API key.

What you get

• A named agent in the Agents list. You see its instances, open traces, finished traces, errors, time to first token and cost over the window you pick. Search by agent name or instance ID.
• The same name in filters and breakdowns. service.name is how you find your agent in trace filters, analytics and cost breakdowns. Cost per call is computed by Rius from the model and token counts. These are list-price estimates in US dollars.
• Version comparison. With versions set, the Versions section compares two versions side by side on traces, failed rate, cost per trace, latency, time to first token (p50) and tokens per trace. It warns when either side has fewer than 20 traces. Drift charts show failed rate, cost per trace and time to first token over time.
• Stable grouping across replicas and deploys. A constant name keeps every replica under one agent, and the version fields carry the release information.
• Clear gaps. If a version is missing, the Agents page says so and tells you which variable to set.

When something else fits

• If you send traces with a plain OpenTelemetry SDK instead of the Rius SDK, set gen_ai.main_agent.id and gen_ai.main_agent.name as resource attributes, for example in OTEL_RESOURCE_ATTRIBUTES. Everything on the Agents page then works except Instances and Lifecycle events, because heartbeats need the Rius SDK.
• If you run LiteLLM as a proxy server, the proxy is a separate process. Name the agent in the process that instruments it, and name your own calling services in their own init().

Related