How do I name my agent in Rius when it uses the Vercel AI SDK?

Rius names your Vercel AI SDK agent from the service name you pass to init, so you set the name once in your Rius setup and not in your AI SDK calls. An optional agent name overrides it for the Agents page. You put the version next to the name, not inside it.

How it works

The Vercel AI SDK integration is TypeScript only. It traces your calls, and the name comes from how you call init() in @glassflow-ai/rius.

• serviceName (RIUS_SERVICE_NAME) is stamped as 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.
• agentName (RIUS_AGENT_NAME) is the name instances and spans group under on the Agents page. It defaults to serviceName. Set it separately only when several services together form one logical agent.
• serviceVersion (RIUS_SERVICE_VERSION) is the build or release this process runs.
• mainAgentVersion (RIUS_MAIN_AGENT_VERSION) is the version of the agent definition: its prompt, tools and policy. It moves independently of the build.

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. Do not put a version number in the name.

You do not register agents. Rius finds the agent from your traces and heartbeats. A process that sends no service name or agent name, or only the unknown_service placeholder, does not appear in the Agents list.

Set it up

1. Install the SDK for your ai version. The full install and every init option are in Installation and configuration.

   npm install @glassflow-ai/rius @opentelemetry/api
   npm install @ai-sdk/otel   # ai 7 only, needs Node 22 or newer

2. Pass the name and the two versions to init(), then await ready before your first call. On ai 7, init() registers the telemetry for you.

   import { init } from '@glassflow-ai/rius'
   import { openai } from '@ai-sdk/openai'
   import { generateText } from 'ai'
    
   const rius = init({
     apiKey: 'ri_...',
     serviceName: 'support-agent',       // service.name, your main handle
     agentName: 'support-agent',         // optional, defaults to serviceName
     serviceVersion: '2026.09.29-a41f3c', // the build
     mainAgentVersion: 'prompt-v12',      // prompt, tools, policy
   })
   await rius.ready
    
   const { text } = await generateText({
     model: openai('gpt-4o-mini'),
     prompt: 'Summarize this ticket',
   })
    
   await rius.shutdown()  // export queued spans before the process exits

3. On ai 5 and 6, also set isEnabled to true in experimental_telemetry on each call, or nothing is traced. The Vercel AI SDK page covers both versions.

4. Or set the same values in the environment and leave them out of init(). 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

5. Run the agent and open Agents in the console. Your agent is listed under its name with an instance in running or ready. Heartbeats need an API key, so an instance appears only when you pass one.

What you get

• Your agent appears on the Agents page under the name you chose. You can search the list by that name, and the agent page shows its instances, traces, errors, cost and context usage.
• service.name is on every span, so you can filter traces and break down cost and analytics by it.
• The Versions section lists the versions that ran, from RIUS_MAIN_AGENT_VERSION or RIUS_SERVICE_VERSION. With two or more versions, Compare puts them side by side on traces, failed rate, cost per trace, latency and tokens, and warns when either side has fewer than 20 traces. If you set neither, the page says the agent reports no version.
• Costs are list-price estimates in US dollars, which Rius computes from the model and token counts of each AI SDK call.

Treat the name as an identifier, not a label. If you rename the agent, stored spans keep the old service.name and the new name starts empty. The old name’s instances show as gone until their heartbeat records age out. Without a mainAgentId (RIUS_MAIN_AGENT_ID), gen_ai.main_agent.id falls back to the agent name, so a rename changes it too. Set mainAgentId to a stable value such as a registry id if you want an identity that survives a rename.

When something else fits

• If several services make up one agent, set agentName separately so they group as one agent on the Agents page, and keep a distinct serviceName for each service.
• If you send traces through a plain OpenTelemetry SDK instead of the Rius SDK, set the main-agent name as a resource attribute, as described on the Agents page. You then get no heartbeats, so no Instances.
• For other frameworks and clients, see Integrations.

Related