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

Rius names your LangChain agent from the service name you pass to init(), and you can set a separate agent name next to it. Set service_name (RIUS_SERVICE_NAME) before you build your chains. The agent name defaults to the service name, and you keep the version out of the name and set it in its own field. The name then shows on the Agents page, in trace filters, and in analytics and cost breakdowns.

How it works

The name comes from the same init() call you use for any Rius agent. The LangChain integration adds nothing to it, so there is no LangChain-specific naming option.

• service_name (RIUS_SERVICE_NAME) is the service.name resource attribute stamped on every span. It defaults to unknown_service, so set it explicitly.
• agent_name (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.
• service_version (RIUS_SERVICE_VERSION) is the build or release this process runs, 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.

When traces arrive, Rius picks the agent 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 SDK sets the main-agent keys for you, so with init() you only choose the names.

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.

Set it up

1. Install the LangChain integration. The extra installs the instrumentation, not LangChain itself. The LangChain integration page covers the TypeScript package and what gets captured.

   pip install "glassflow-rius[langchain]" langchain

2. Pass the names to init(), before you build or run any chain. Explicit arguments win over environment variables, which win over defaults.

   import rius
    
   client = rius.init(
       api_key="ri_...",
       service_name="checkout-agent",
       agent_name="checkout-agent",
   )
   # build and run your chains exactly as before

   In TypeScript the options are serviceName and agentName, with the same meaning.

3. Set the versions in the environment, not in the name. Use the first for the agent definition and the second for the build or deploy.

   RIUS_MAIN_AGENT_VERSION=prompt-v12      # the agent definition: prompt, tools, policy
   RIUS_SERVICE_VERSION=2026.09.29-a41f3c  # the build or deploy

4. If you want an identity that survives a rename, also set main_agent_id (RIUS_MAIN_AGENT_ID). Without it, gen_ai.main_agent.id falls back to the agent name, so renaming the agent changes it.

5. Run one chain that calls a model, then open Agents in the console. Your agent appears under the name you set. Every option is listed in Installation and configuration.

What you get

• One name in every view. The service name is how you find your agent in trace filters, analytics and cost breakdowns. Each agent also gets a row in the Agents list, which you can search by agent name.
• A page per agent. Open the agent to see its instances, failed traces, error rate, cost and time to first token, recent traces and exceptions. The Agents page explains each section.
• Version comparison. With RIUS_MAIN_AGENT_VERSION or RIUS_SERVICE_VERSION set, the Versions section lists what ran. With two or more versions, Compare shows traces, failed rate, cost per trace, latency and time to first token (p50), and tokens per trace side by side, and warns when either side has fewer than 20 traces.
• Instances under one name. Replicas group under the agent name, and each shows as running, ready, stale, gone or stopped.

Treat the name as an identifier, not a label. If you rename the agent, stored spans keep the old service.name and stay filterable under it, while the new name starts empty. The old name’s instances show as gone until their heartbeat records are removed.

If your agent is missing from the list, it sent no agent name and no service name. Rius ignores the unknown_service placeholder, so set service_name or agent_name.

For the other frameworks and libraries Rius traces with the same init() call, see Integrations.

When something else fits

• If several services together form one logical agent, set agent_name separately from service_name so they group as one agent while each service keeps its own name.
• If you send traces from 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 stays empty.

Related