How do I set the agent name attribute on an OpenTelemetry span in JavaScript?

Rius reads the agent name from the gen_ai.agent.name attribute, which you set with span.setAttributes from @opentelemetry/api on an invoke_agent span. Rius then files the span’s traces under that agent. To name the agent a whole process runs, set gen_ai.main_agent.name as a resource attribute. This works with a plain OpenTelemetry SDK in Node.js, with no Rius SDK needed.

How it works

Rius expects the GenAI convention keys, and each one has a job:

• gen_ai.agent.name on an invoke_agent span names the agent being invoked.
• gen_ai.agent.name on an execute_tool span names the agent executing the tool.
• gen_ai.main_agent.name is a resource attribute, so it applies to every span the process sends. It names the agent the process runs.

When a span arrives, Rius files it under the first of these that is set and is not a placeholder such as unknown_service:

1. the resource gen_ai.main_agent.name
2. the resource rius.main_agent.name (deprecated, still read)
3. the resource gen_ai.agent.name
4. the span’s own gen_ai.agent.name
5. service.name

So a span-level gen_ai.agent.name names the agent when no resource attribute does, and service.name is the last fallback. Always set service.name as well.

Set the span kind and operation too. gen_ai.operation.name of invoke_agent and openinference.span.kind of AGENT classify the span as an agent step. Setting either one makes Rius derive the other, and the Rius SDKs set both. Name the span the way the GenAI conventions ask, the operation followed by what it acted on, such as invoke_agent planner.

Set it up

1. Register a tracer provider that exports to Rius. This is the shared setup, covered in full on Vanilla OpenTelemetry SDKs, including the OTEL_EXPORTER_OTLP_* variables and your API key. In Node.js it looks like this:

import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
 
const sdk = new NodeSDK({
  // No url or headers in code, so the exporter reads OTEL_EXPORTER_OTLP_*
  traceExporter: new OTLPTraceExporter(),
  // Rius ingests traces only
  metricReaders: [],
  logRecordProcessors: [],
})
sdk.start()
 
// ... your agent code ...
 
// Flushes queued spans before the process exits (top-level await needs an ES module)
await sdk.shutdown()

2. Start an agent span and set the agent name on it. Replace planner with your own agent’s name:

import { trace } from '@opentelemetry/api'
 
const tracer = trace.getTracer('my-agent')
 
await tracer.startActiveSpan('invoke_agent planner', async (span) => {
  span.setAttributes({
    'openinference.span.kind': 'AGENT',
    'gen_ai.operation.name': 'invoke_agent',
    'gen_ai.agent.name': 'planner',
  })
  try {
    // ... run the agent ...
  } finally {
    span.end()
  }
})

3. For a tool the agent runs, use an execute_tool span. Put the tool’s own name in gen_ai.tool.name, never in the span name alone, and the agent running it in gen_ai.agent.name. Nest these spans the normal OpenTelemetry way, through parent context, so they arrive as one trace under a single root span for the run.

4. To name the agent for the whole process, add gen_ai.main_agent.name to the resource of your tracer provider, using your OpenTelemetry SDK’s own resource options. Keep service.name set, for example with OTEL_SERVICE_NAME.

5. Send a run and open the trace in the Rius console. The agent name on your spans is the name Rius files the traces under.

What you get

• Traces filed under a meaningful agent name instead of a placeholder service name.
• Agent steps classified as agent spans, apart from model calls and tools.
• Tool spans that record which agent ran them.
• One naming scheme that matches what the Rius SDKs emit, so a fleet mixing SDK and plain OpenTelemetry senders reads alike.

The full list of keys Rius reads is in the span attribute reference. For the wider picture of sending spans from your own code, see Trace LLM calls with OpenTelemetry.

When something else fits

• If you want the span kind and operation set for you, use the Rius TypeScript SDK instead of raw OpenTelemetry. It also adds auto-instrumentation for supported libraries.
• If you only need one agent per process, setting service.name alone already gives Rius a name to group by.

Related