How do I name my agent in Rius when it uses the Claude Agent SDK?

Rius names your Claude Agent SDK agent from the service_name you pass to rius.init, or from agent_name when you set that too. Put the build and prompt versions in their own settings, not in the name. The name then appears on the Agents page, in trace filters and in cost breakdowns.

How it works

The Claude Agent SDK runs the Claude Code runtime in a separate process, so your Rius coverage comes from rius.init plus an observe wrapper and a manual generation, as described on the Claude Agent SDK integration page. The agent’s identity comes from init, not from the wrapper.

• Service name. service_name (RIUS_SERVICE_NAME) becomes the service.name on every span. It defaults to unknown_service, so always set it.
• Agent name. agent_name (RIUS_AGENT_NAME) defaults to the service name. Set it separately only when several services form one logical agent.
• Versions. service_version (RIUS_SERVICE_VERSION) is the build or release. main_agent_version (RIUS_MAIN_AGENT_VERSION) is the version of the agent definition, meaning its prompt, tools and policy. The two move independently.
• Task name. The name you give observe labels the root span of each task, for example handle-task. It is a task label, separate from the agent name.

The SDK stamps the agent name on every span for you. Rius takes the agent name from the first of these that is set: gen_ai.main_agent.name, rius.main_agent.name, gen_ai.agent.name on the resource, gen_ai.agent.name on the span, then service.name.

Set it up

1. Install the SDK and the Claude Agent SDK. The base SDK is enough, and the claude CLI must be installed and authenticated.

   pip install glassflow-rius claude-agent-sdk

2. Call init once, early in your process, with a constant name and the versions beside it. The full init option list is on the installation page.

   import rius
    
   client = rius.init(
       api_key="ri_...",
       service_name="support-agent",
       agent_name="support-agent",
       service_version="2026.09.29-a41f3c",
       main_agent_version="prompt-v12",
   )

   Leave out agent_name if it would match service_name, since it defaults to that value.

3. Prefer environment variables? Set the versions outside your code instead:

   export RIUS_MAIN_AGENT_VERSION=prompt-v12
   export RIUS_SERVICE_VERSION=2026.09.29-a41f3c

4. Wrap each task as the root agent span, as the integration page shows. This line is the only naming-related part of the wrapper:

   @rius.observe(name="handle-task", kind=SpanKind.AGENT)

5. 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. Call client.shutdown() before exit so the instance ends as stopped instead of gone.

6. Set main_agent_id (RIUS_MAIN_AGENT_ID) if you may rename the agent later. Without an id, gen_ai.main_agent.id falls back to the agent name, so a rename changes it too.

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. Treat the name as an identifier, not a label.

What you get

• The agent appears on the Agents page under your name, with its instances, traces, errors, time to first token and cost. You can search the list by that name. Heartbeats need the API key you pass to init.
• The same name is the service.name you filter by in traces, analytics and cost breakdowns, so cost from the Claude Agent SDK runs groups under it. Costs are list-price estimates in US dollars.
• The Versions section lists the versions that ran, taken from RIUS_MAIN_AGENT_VERSION (the agent definition) or RIUS_SERVICE_VERSION (the build). With two or more versions you can compare them on traces, failed rate, cost per trace, latency and tokens per trace, and the Drift charts show how those change. Without a version, the page tells you which variable to set.
• Each task trace has a root agent span and one generation with the model, tokens and cost. The runtime’s inner steps do not appear as spans.
• Your own agent keeps your name. It is a different agent from the claude-code agent that the Claude Code plugin creates for coding sessions.

When something else fits

If several services together form one agent, set agent_name apart from service_name so they group as one. If you only need to tell tasks apart inside a trace, the observe name is enough and the agent name can stay at the service name. For other frameworks and the full list of integrations, see Integrations.

Related