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

Rius names your CrewAI agent from the service_name you pass to rius.init (or RIUS_SERVICE_NAME), and shows it with its version on the Agents page. Set agent_name only if several services form one logical agent. The version goes in its own setting, never in the name.

How it works

The name comes from the Rius SDK’s init, not from CrewAI. You don’t register agents. Rius finds them in your traces and heartbeats, so the name you set in init is the name that appears.

• service_name (RIUS_SERVICE_NAME) is stamped as service.name on every span. It is how you find the agent in trace filters, analytics and cost breakdowns. It defaults to unknown_service, and an agent that sends only that placeholder is not listed on the Agents page, so always set it.
• 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, 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 SDK stamps the agent name as gen_ai.main_agent.name, which is the first place Rius looks. If that is missing, it falls back through rius.main_agent.name, gen_ai.agent.name on the resource, gen_ai.agent.name on the span, and finally service.name.

CrewAI crews and tasks produce no spans of their own, so the role you give a CrewAI Agent does not become the Rius agent name. The root span you create with observe has its own span name, such as handle-ticket, which appears inside the trace. The agent name on the Agents page is the one from init.

Set it up

1. Install the SDK with the OpenAI extra, which captures the model calls CrewAI makes, and CrewAI itself:

pip install "glassflow-rius[openai]" crewai

2. Name the agent in init and wrap your entrypoint. Keep the name constant across replicas and deploys:

import rius
from rius import SpanKind
 
rius.init(
    api_key="ri_...",
    service_name="support-agent",
    agent_name="support-agent",
    service_version="2026.09.29-a41f3c",
    main_agent_version="prompt-v12",
)
 
@rius.observe(name="handle-ticket", kind=SpanKind.AGENT)
def handle_ticket(ticket: str) -> str:
    ...  # build your Task and Crew, then return str(crew.kickoff())

You can drop agent_name if it matches service_name, because it defaults to the service name. For the full CrewAI example with tools, see CrewAI.

3. Prefer environment variables for versions? Set them where the process starts:

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

4. Run one ticket, open Agents, and look for your name. With an API key set, it has an instance in running or ready. When the process exits normally, the instance moves to stopped. If the process is stopped with SIGTERM, call shutdown() from your own handler so it ends as stopped rather than gone.

Every init argument and its environment variable is listed in Installation and configuration.

What you get

• Your agent listed by name on the Agents page, 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, so you can narrow to this agent anywhere.
• Replicas grouped under one name. Each process start is a fresh instance, so three replicas show as three instances of one agent.
• Versions on the agent page. Versions lists what ran in the window, Compare puts two versions side by side on traces, failed rate, cost per trace, latency, time to first token and tokens per trace, and Drift charts how the agent changes over time. Compare warns when either side has fewer than 20 traces.
• Heartbeat status for each instance, as long as the client has an API key or an Authorization header.

If the agent shows no version, the page tells you to set RIUS_MAIN_AGENT_VERSION or RIUS_SERVICE_VERSION. Treat the name as an identifier, not a label. 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. 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. For other frameworks and libraries, 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.
• If you send traces from a plain OpenTelemetry SDK instead of the Rius SDK, set gen_ai.main_agent.id and gen_ai.main_agent.name as resource attributes through OTEL_RESOURCE_ATTRIBUTES. The Agents page still works, but without Instances and Lifecycle events, because heartbeats need the Rius SDK.

Related