Skip to Content

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

Rius names your Pydantic AI agent from the service_name you pass to rius.init, which becomes service.name on every span. Set agent_name only when you want instances grouped under a different name. Set the version beside the name, never inside it, and the name appears on the Agents page and in your trace filters.

How it works

  • service_name (RIUS_SERVICE_NAME) is stamped as the service.name resource attribute on every span. It defaults to unknown_service, so set it. It is how you find your agent in trace filters, analytics and cost breakdowns.
  • 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.
  • The SDK stamps the agent name on the resource as gen_ai.main_agent.name and gen_ai.agent.name. 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. Because the SDK sets the main-agent keys, they decide the name you see.
  • Pydantic AI names its own spans. The root span of a run is invoke_agent followed by your agent’s name, and model requests and tool calls are named after the model and the tool. Those span names help you read a single trace. The name on the Agents page comes from the Rius settings above.
  • The version goes next to the name. service_version (RIUS_SERVICE_VERSION) is the build or release and is stamped as service.version. main_agent_version (RIUS_MAIN_AGENT_VERSION) is the version of the agent definition, meaning its prompt, tools and policy, and is stamped as rius.main_agent.version. They move independently, so the SDK never derives one from the other.

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. Pydantic AI needs no extra install for any of this: rius.init() installs the global tracer provider and Agent.instrument_all(True) makes the framework emit its spans through it. The Pydantic AI integration page covers the rest of the setup, and Integrations lists the other frameworks.

Set it up

  1. Install the SDK and Pydantic AI. No extra is needed. See Installation and configuration for the full list of options.
pip install glassflow-rius pydantic-ai
  1. Call rius.init() before you build your agents. Pass the name and both versions, then turn on Pydantic AI instrumentation. Replace the example names and values with your own.
import rius
from pydantic_ai import Agent
 
rius.init(
    api_key="ri_...",
    service_name="support-agent",
    service_version="2026.09.29-a41f3c",
    main_agent_version="prompt-v12",
)
Agent.instrument_all(True)
 
support_agent = Agent(
    "openai:gpt-5-mini",
    instructions="Answer support questions; check accounts with the tool.",
)

  1. Optional: if several services make up one agent, add agent_name="support-agent" to init, or set RIUS_AGENT_NAME. Leave it out otherwise, and the agent name follows service_name.

  2. Optional: if you want an identity that survives a rename, set main_agent_id (RIUS_MAIN_AGENT_ID) to a stable value such as a registry id. Without it, gen_ai.main_agent.id falls back to the agent name, so renaming the agent changes it. Never use an id minted at process start.

  3. Run one request and open the Agents page. Your agent is listed under the name you set, with an instance in running or ready. Heartbeats need an API key, so an agent started without one is marked no heartbeat and has no instances. When the process exits normally, the instance moves to stopped.

What you get

  • Your agent appears on the Agents page under the name you chose. You search the list by that name, and each row shows its instances, traces, errors, time to first token and cost.
  • The agent page opens with its summary, instances, context, versions and drift. View all in Traces opens the trace list filtered to the agent.
  • service.name is the handle for trace filters, analytics and cost breakdowns, so one constant name keeps all of that in one place.
  • The Versions section reads RIUS_MAIN_AGENT_VERSION (the agent definition) or RIUS_SERVICE_VERSION (the build). With two or more versions you can compare them on traces, failed rate, cost per trace, latency and tokens per trace. Rius warns when either side has fewer than 20 traces.
  • Three replicas of the same agent show as three 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, while the new name starts empty. On the Agents page the old name’s instances report gone until their heartbeat records age out.

When something else fits

  • If several services together form one logical agent, set agent_name apart from service_name so their instances group under one name.
  • If you send Pydantic AI spans through a plain OpenTelemetry setup instead of the Rius SDK, set gen_ai.main_agent.id and gen_ai.main_agent.name as resource attributes. Everything on the Agents page works except Instances and Lifecycle events, because heartbeats need the Rius SDK.
  • If you want to change the name later, expect the new name to start with no history and plan the switch for a quiet moment.

Still stuck? Get help

Last updated on
Quickstart