How do I name my agent in Rius when it uses the OpenAI API?

Rius names your agent from the service name you pass to init, so set it once and every OpenAI call is traced under that name. Set agent_name only if several services form one logical agent, and put versions in their own settings, not in the name. The name then shows on the Agents page, in trace filters, in analytics and in cost breakdowns.

How it works

Rius resolves the agent name from the first of these that is set:

1. gen_ai.main_agent.name on the resource
2. rius.main_agent.name on the resource
3. gen_ai.agent.name on the resource
4. gen_ai.agent.name on the span
5. the service name (service.name)

The Rius SDK sets the main-agent keys for you, so in practice you set two options:

• service_name (RIUS_SERVICE_NAME) is the service.name stamped on every span. It defaults to unknown_service, which Rius does not accept as an agent name, so always set it.
• agent_name (RIUS_AGENT_NAME) controls how instances group on the Agents page. It defaults to the service name. Set it separately only when several services form one logical agent.

OpenAI calls need no separate naming. The instrumentation traces every client call in the process, and each span carries the resource attributes of your init() call. See the OpenAI integration for what each call records.

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. Keep version numbers out of the name:

• service_version (RIUS_SERVICE_VERSION) is the build or release, stamped as service.version.
• main_agent_version (RIUS_MAIN_AGENT_VERSION) is the version of the agent definition (prompt, tools, policy), stamped as rius.main_agent.version. The SDK never derives one version from the other.

Set it up

1. Install the OpenAI instrumentation. The extra installs the instrumentation, not openai itself. The Installation and configuration page covers the TypeScript package and every other option.

pip install "glassflow-rius[openai]" openai

2. Call init() once, before you create the OpenAI client, with the name and the two versions:

import rius
from openai import OpenAI
 
rius.init(
    api_key="ri_...",
    service_name="support-agent",
    agent_name="support-agent",
    service_version="2026.09.29-a41f3c",
    main_agent_version="prompt-v12",
)
client = OpenAI()  # use the client exactly as before

3. In TypeScript the options are camelCase:

import { init } from '@glassflow-ai/rius'
import OpenAI from 'openai'
 
const rius = init({
  apiKey: 'ri_...',
  serviceName: 'support-agent',
  agentName: 'support-agent',
  serviceVersion: '2026.09.29-a41f3c',
  mainAgentVersion: 'prompt-v12',
})
const client = new OpenAI()

4. Or set the same values in the environment, which an explicit argument overrides:

export RIUS_SERVICE_NAME=support-agent
export RIUS_AGENT_NAME=support-agent
export RIUS_SERVICE_VERSION=2026.09.29-a41f3c
export RIUS_MAIN_AGENT_VERSION=prompt-v12

5. Run one OpenAI call, open Agents in the console and check that support-agent has an instance in running or ready. Heartbeats need credentials, so an API key must be set.

6. Decide on a stable id. 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 if you want an identity that survives a rename.

What you get

• Your agent appears on the Agents page under the name you chose. You can search the list by agent name and open a row for instances, traces, errors, time to first token and cost.
• service.name is how you find the agent in trace filters, analytics and cost breakdowns, so OpenAI cost per agent follows the same name.
• With RIUS_MAIN_AGENT_VERSION or RIUS_SERVICE_VERSION set, Versions lists the versions that ran, and Compare sets two side by side on traces, failed rate, cost per trace, latency, time to first token and tokens per trace. The comparison warns when either side has fewer than 20 traces.
• The build version in RIUS_SERVICE_VERSION is available as a second view next to the agent version when traces carry both.
• Replicas of the same agent stay grouped as instances under one name.

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

For the other integrations and how they attach, see Integrations.

When something else fits

• If several services together make up one logical agent, give each its own service_name and share one agent_name so they group together on the Agents page.
• 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. Heartbeats need the Rius SDK, so the Instances section stays empty.

Related