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

Rius names your agent from the service_name you pass to rius.init(), or from agent_name when you set it separately. The name is stamped on every span, so your OpenAI Agents SDK runs appear under one agent on the Agents page. Put the version in main_agent_version and service_version, not in the name.

How it works

Rius finds agents in your traces and heartbeats, so there is nothing to register. Two init options decide the name:

• service_name (RIUS_SERVICE_NAME) is the service.name on every span. It is how you find your agent in trace filters, analytics and cost breakdowns. It defaults to unknown_service, so set it.
• agent_name (RIUS_AGENT_NAME) controls how instances group in the Agents view. It defaults to service_name. Set it separately only when several services form one logical agent.

The SDK stamps the agent name on the resource as gen_ai.main_agent.name and gen_ai.agent.name, plus the older rius.main_agent.name. Rius reads the 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 version sits next to the name, in two separate settings:

• 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, meaning its prompt, tools and policy, stamped as rius.main_agent.version. It moves independently of the build.

The Agents page compares versions from these two values.

Set it up

1. Install the SDK with the OpenAI extra, plus the framework. The OpenAI Agents SDK integration covers the rest of the framework setup, such as observe wrappers for tools.

   pip install "glassflow-rius[openai]" openai-agents

2. Name the agent in init(), once, before your agent runs. Use a constant name and keep version numbers out of it.

   import rius
   from agents import Agent, Runner, set_tracing_disabled
   from rius import SpanKind
    
   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",
   )
   set_tracing_disabled(True)
    
   support_agent = Agent(
       name="support_agent",
       instructions="Answer support questions.",
       model="gpt-5-mini",
   )
    
   @rius.observe(name="handle-ticket", kind=SpanKind.AGENT)
   def handle_ticket(ticket: str) -> str:
       result = Runner.run_sync(support_agent, ticket)
       return str(result.final_output)

   The name you give Agent(...) is the framework’s own label, used for handoffs. Rius does not read it: the name on the Agents page comes from service_name or agent_name.

3. If you prefer the environment, set the same values there. Explicit arguments win over environment variables.

   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

4. Pass an API key so heartbeats are sent. Without an api_key or an Authorization header, or with heartbeat turned off, the agent shows as no heartbeat and has no instances.

5. Call client.shutdown() when your process stops, so the instance ends as stopped instead of gone. See Installation and configuration for every init option.

6. Verify: run the agent, open Agents, and check that it appears under your name with an instance in running or ready.

Keep the name the same 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. If you rename the agent, 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, renaming also changes gen_ai.main_agent.id, so set main_agent_id if you want an identity that survives a rename.

What you get

• One agent on the Agents page under your chosen name, with its instances, traces, errors, time to first token and cost. You can search the list by agent name.
• The same name as service.name in trace filters, analytics and cost breakdowns.
• Versions and Drift sections filled from main_agent_version and service_version. With two or more versions, Compare shows traces, failed rate, cost per trace, latency and tokens side by side, so you see whether a new prompt or model helped. See Agents for each section.
• Replicas grouped as instances of one agent, with stopped and gone telling a clean exit from a kill.

The same naming works for every integration in the Integrations library.

When something else fits

• If several services together form one logical agent, give each its own service_name and share one agent_name so they group under a single agent.
• If you send traces with a plain OpenTelemetry SDK instead of the Rius SDK, set gen_ai.main_agent.name and gen_ai.main_agent.id as resource attributes. Heartbeats need the Rius SDK, so Instances stay empty.

Related