Evalgent
Back to Blog
Voice AI Testing

OpenTelemetry GenAI Semantic Conventions for Voice Agents: What Exists and What to Add

Deepesh Jayal
14 min read
OpenTelemetry GenAI Semantic Conventions for Voice Agents: What Exists and What to Add
On this page

If your team traces a voice agent, you will meet the gen_ai.* names fast. They are the shared vocabulary for model calls, agents and tools. The gen_ai semantic conventions also look like the natural home for voice data. But the page you bookmarked last spring may be a redirect now, and the status line matters before you build on it. This post checks the OpenTelemetry GenAI semantic conventions voice teams can rely on, on the day of writing. Then it separates what a voice stack can reuse from what you must add yourself.

For the basic span tree of a voice call, read OpenTelemetry observability for voice agents. This post does not repeat it. It covers one narrower question: what do the GenAI conventions give you, and where do they stop?

All facts below come from the OpenTelemetry pages and vendor docs linked inline, read on November 19, 2026. The conventions change often. Re-check before you commit a schema.

Where the GenAI conventions live and their status

The old home was opentelemetry.io/docs/specs/semconv/gen-ai/. As of November 19, 2026, those pages show a notice instead of a spec. The GenAI conventions index on opentelemetry.io says the conventions have moved to the OpenTelemetry GenAI semantic conventions repository. It also says the page "is no longer maintained in this repository." The index marks every sub-page (spans, agent spans, metrics, events) as moved.

The current source is the semantic-conventions-genai repository. Its README describes it as conventions for spans, metrics and events for GenAI clients, MCP and provider-specific conventions. It extends the core semantic conventions. Shared, non-GenAI attributes such as server.address and error.type stay in the core repository.

Two status facts matter for planning:

  • Stability. The GenAI conventions index in that repository says Status: Development. The pages for client inference and realtime generation say the same. Nothing I read marks the GenAI signals as stable.
  • Schema URL. The repository README lists the Schema URL as TODO today. There is no published schema URL to pin against yet.

On the opt-in environment variable: none of the OpenTelemetry GenAI pages I read mention OTEL_SEMCONV_STABILITY_OPT_IN. Datadog's documentation does. It says that if your framework supported a pre-1.37 version of the OpenTelemetry specification, you also set OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental. So treat that variable as an instrumentation-library detail. Check the docs of each library you use, and do not assume a global switch.

Status board showing the GenAI semantic conventions at Development status, moved to a new repository, with no published Schema URL, as checked on November 19, 2026

What the conventions define today

The index lists these signal groups. All are in the new repository.

Signal groupWhat it coversSpan name pattern
Client inferenceOne model call that returns a response or a tool request{gen_ai.operation.name} {gen_ai.request.model}
Client embeddingsEmbedding calls{gen_ai.operation.name} {gen_ai.request.model}
Execute toolOne tool runexecute_tool {gen_ai.tool.name}
RetrievalA retrieval pipeline{gen_ai.operation.name}
Agent invocationInvoking, creating and planning for an agentinvoke_agent {gen_ai.agent.name}
Realtime content generationServer-side generation in a streaming session{gen_ai.operation.name} {gen_ai.request.model}
Events, exceptions, metricsInputs and outputs, errors, durations and token countsNot applicable

Provider pages exist for Anthropic, Azure AI Inference, AWS Bedrock and OpenAI. There are also pages for the Model Context Protocol and Agent2Agent.

The well-known values of gen_ai.operation.name on the realtime conventions page include chat, generate_content, text_completion, embeddings, retrieval, execute_tool, create_agent, invoke_agent, invoke_workflow, invoke_runner, plan, realtime_inference and user_speech. The page says that if one of the well-known values applies, you MUST use it. Otherwise a custom value MAY be used.

That last rule is your door for voice-specific operations. It is also a warning. A custom value works in your backend, but no other tool will know what it means.

Metrics

The conventions define duration and token metrics for inference, embeddings, tool execution, retrieval and agent invocation. For a voice agent, three matter most:

  • gen_ai.client.inference.time_to_first_chunk measures how long a client waits for the first output chunk.
  • gen_ai.client.inference.time_per_output_chunk measures the pace of streamed output.
  • gen_ai.execute_tool.duration measures tool latency.

The client inference page defines a chunk as a decoded provider stream event with new, non-empty output. Audio counts as output. The same page says time to first chunk is measured from the start of the logical inference operation, including authentication, failed attempts and retry backoff.

That is a client-side model latency. It is not the gap a caller hears. For that, see what to measure for voice agent latency.

What a voice agent can reuse as is

Most of the model, tool and agent plumbing in a voice stack maps to existing conventions. Voice stacks inherit OpenTelemetry LLM tracing for the model step. The GenAI spans attributes below can be reused without change.

Model calls. The LLM step in a cascaded pipeline is an inference span. Set gen_ai.operation.name to chat (or the value that fits), plus gen_ai.provider.name and gen_ai.request.model. Both operation name and provider name are Required. Record gen_ai.usage.input_tokens and gen_ai.usage.output_tokens. These are Recommended attributes.

Finish reasons. gen_ai.response.finish_reasons is Recommended. The client inference page says that for interrupted generations, instrumentations SHOULD report the provider-reported interruption reason when available, and interrupted otherwise. That gives you a standard way to mark an LLM response cut short. It does not tell you the caller spoke, only that generation ended early.

Tool calls. An execute_tool span is INTERNAL, named execute_tool {gen_ai.tool.name}. The execute tool page makes gen_ai.tool.name Required and gen_ai.tool.call.id Conditionally Required. Arguments and results are Opt-In. That matches how a voice agent books, looks up and transfers. For the failure side, see detecting silent tool failures.

Agents. The agent invocation conventions give you gen_ai.agent.name, gen_ai.agent.id, gen_ai.agent.version and gen_ai.agent.description. Use gen_ai.agent.version on the root span so you can tie a failure to a release.

Call identity. gen_ai.conversation.id is the shared attribute across operations. The index says instrumentations MAY propagate it to nested instrumentations. It is Conditionally Required: required if the library has one or your application supplies one. Set it to your call ID. What to log for voice agent calls explains why one ID everywhere is the rule that holds the rest together.

Content capture. Message content (gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions) is Opt-In. In a voice agent those fields are what callers said and what the agent said. Treat them as personal data. Keep them off by default and mask before export. See voice agent PII leakage detection.

What the conventions say about speech and realtime

The current pages include a realtime page. Here is only what it says.

A realtime inference span. The realtime_inference operation is one server-side model generation inside a realtime, bidirectional streaming session, such as OpenAI Realtime or Gemini Live. The span kind SHOULD be CLIENT. Instrumentation SHOULD record one span per generation the provider identifies. If the provider ends a generation to request a tool and starts another after the result, that is two spans. The page also says instrumentation SHOULD NOT create this span by default for long-running or non-conversational generations, with speech translation and transcription as examples.

A user speech span. The user_speech operation describes the capture of a user speech utterance. It is Opt-In and its kind SHOULD be INTERNAL. Instrumentation MAY record it when it can reliably determine start and end of speech, either from voice-activity detection events in the model response or from client-side events. If it cannot, it SHOULD NOT record the span. The page names OpenAI Realtime's input_audio_buffer.speech_started and input_audio_buffer.speech_stopped as examples of such events.

Session events. gen_ai.client.realtime_session.started and gen_ai.client.realtime_session.ended mark the session. The ended event is WARN severity when error.type is set and INFO otherwise.

A session ID that is not the conversation ID. gen_ai.realtime_session.id identifies a long-lived streaming connection. The page says instrumentations MUST NOT use gen_ai.conversation.id as a realtime session identifier. A call can span several sessions. Keep both.

Audio token counts and output type. gen_ai.usage.audio.input_tokens and gen_ai.usage.audio.output_tokens exist, and gen_ai.output.type has a speech value.

All of this is Development status. The OpenTelemetry GenAI semantic conventions voice teams use are also scoped to model-side realtime APIs. The realtime page defines no span for a speech-to-text service or a text-to-speech service in a cascaded pipeline. In the operation list I read, there is no transcription or synthesis operation.

A cascaded stack has to choose. You can emit STT and TTS spans with a custom gen_ai.operation.name value, as the rule above allows. Or you can emit them without any gen_ai.operation.name. Pipecat shows the framework route. Its tracing docs describe conversation, turn, stt, llm and tts spans. LLM spans carry gen_ai.provider.name, gen_ai.request.model and token usage. Turn spans carry turn.number, turn.duration_seconds and turn.was_interrupted. Its conversation spans use conversation.id, not gen_ai.conversation.id. For realtime services it uses spans named llm_setup, llm_response and llm_tool_call.

So a mixed picture is normal for an otel genai voice agent today. Part of your data uses gen_ai.* names. Part uses framework names. You map them at the collector or in your backend.

What voice needs that the conventions do not cover

The OpenTelemetry GenAI semantic conventions voice teams use describe calls to models and tools. A phone call has more structure than that. I searched the GenAI pages in the repository for turn, telephony, endpointing and audio-duration terms and found none. For each gap, I suggest a custom name.

Important: the voice.* names below are my own suggestions. They are not part of any OpenTelemetry standard. They sit under a custom namespace so they cannot collide with gen_ai.*. Rename them to fit your conventions, but keep one namespace.

GapWhat the GenAI pages coverSuggested custom attribute (own suggestion)
TurnNothing named a turn. user_speech and realtime_inference cover pieces of itvoice.turn.index, voice.turn.id
InterruptionFinish reason interrupted on a generationvoice.turn.interrupted (boolean), voice.turn.stop_delay_ms
Telephony legNo telephony attributes in the GenAI pagesvoice.call.id, voice.leg.id, voice.leg.direction, voice.carrier.name
Audio durationAudio token counts onlyvoice.audio.input.duration_ms, voice.audio.output.duration_ms
EndpointingNo end-of-turn decision eventvoice.endpointing.wait_ms
Caller-perceived gapClient-side time to first chunk onlyvoice.response.gap_ms
Call outcomeNo outcome or end-reason attributevoice.call.end_reason
Agent buildgen_ai.agent.versionvoice.prompt.hash, voice.semconv.pin

A few notes on these.

Turn. A turn is the unit voice teams debug. Callers say "it cut me off on the second question." You need a span or an attribute that says which turn. Pipecat's turn.* attributes show the idea. Because they are framework-specific, a backend cannot assume them either.

Interruption. The standard gives you interrupted as a finish reason. That records that a generation ended early. It does not record who spoke, how long the agent kept talking after the caller started, or whether the cut was clean. Derive that from event timestamps in your own trace. Our interruption rate guide defines the measurement.

Telephony leg. A phone call may have a carrier leg, a SIP leg and a media session. The GenAI conventions are silent here. Put your telephony provider's call identifier on a custom attribute, and set gen_ai.conversation.id to your own call ID, so you can join the provider's records to the trace. Keep the provider call ID as a separate attribute. Do not overload one field.

Audio duration. Token counts do not tell you how many seconds of caller speech the model received. If you bill, size or debug by talk time, you need a duration in seconds or milliseconds. Record it as a number your pipeline measured. Do not infer it from tokens.

Caller-perceived gap. gen_ai.client.inference.time_to_first_chunk stops when the client receives the first model chunk. The caller hears audio later, after synthesis and the phone network. Measure the gap from end of caller speech to first agent audio in your own code. Time to first audio explains the components.

Turn timeline mapping each stage of one voice turn to a standard gen_ai span or to a suggested custom voice attribute that is not part of the standard

How to adopt gen_ai conventions in a voice stack in 5 steps

These steps assume a cascaded or realtime stack that already exports OpenTelemetry traces. The code is simplified.

1. Pin the convention version you target — The repository has no published Schema URL today, so you pin two things yourself. First, pin your instrumentation library versions in your lockfile. Second, record a pointer to the convention source you read, such as the repository commit date, as a resource attribute. I suggest voice.semconv.pin. This is not a standard attribute. When the spec renames an attribute, the pin tells you which names your old traces use.

2. Set one call ID on everything — Generate the call ID when the call starts. Set gen_ai.conversation.id to it on every span you create. Put the telephony provider's call identifier on a separate custom attribute.

3. Map each pipeline stage to the closest existing operation — Use an inference span for the LLM, execute_tool for tools and invoke_agent for the agent root. For a realtime provider, use realtime_inference and, where you can detect speech start and end reliably, user_speech. For STT and TTS, choose a documented custom operation value and write it down.

4. Add the voice layer under a custom namespace — Add voice.turn.index, voice.turn.interrupted, audio durations and the response gap. Keep every custom name under one prefix. Never put custom names under gen_ai..

5. Test the mapping in your backend before you rely on it — Send a staged call and check what your backend does with each attribute. Check which ones it maps, which become plain tags and which it drops. Some backends keep only spans that carry gen_ai.* attributes, as the next section shows.

Four stacked attribute layers for a voice stack: standard gen_ai names, framework names mapped at the collector, a custom voice namespace, and a version pin recorded on the resource

Here is a simplified Python sketch of steps 2 to 4 for one turn. It uses the OpenTelemetry Python API. Names with voice. are the custom suggestions.

from opentelemetry import trace

tracer = trace.get_tracer("voice-agent")

def handle_turn(call_id, turn_index, interrupted, gap_ms):
    with tracer.start_as_current_span("turn") as turn:
        turn.set_attribute("gen_ai.conversation.id", call_id)
        turn.set_attribute("voice.turn.index", turn_index)

        with tracer.start_as_current_span("chat gpt-example") as llm:
            llm.set_attribute("gen_ai.operation.name", "chat")
            llm.set_attribute("gen_ai.provider.name", "openai")
            llm.set_attribute("gen_ai.request.model", "gpt-example")
            llm.set_attribute("gen_ai.conversation.id", call_id)

        turn.set_attribute("voice.turn.interrupted", interrupted)
        turn.set_attribute("voice.response.gap_ms", gap_ms)

The model name is a placeholder. Use the value your provider reports. The turn span here has no gen_ai.operation.name. Whether your backend keeps it is a step 5 question.

Which backends consume these conventions

Name a backend only after you read its docs. Two documented cases as of November 19, 2026:

Datadog. Its OpenTelemetry instrumentation page says it supports traces that follow the OpenTelemetry 1.37+ semantic conventions for generative AI. Conversion must be enabled with the dd_llmobs_enabled=true resource attribute or an export header. A trace is eligible only if at least one span has gen_ai.operation.name, gen_ai.provider.name or the deprecated gen_ai.system. The page also says only spans with gen_ai.* attributes, or certain OpenInference, Langfuse or TrueFoundry span-type attributes, are kept. Other spans are dropped. Unmapped gen_ai.* attributes become tags with values truncated to 256 characters. For a voice stack, that matters: a pure voice.* span may not survive. Test it.

Langfuse. Its OpenTelemetry integration page says Langfuse accepts OTLP traces over HTTP and "aims to be compliant" with the OpenTelemetry GenAI conventions. It maps examples such as gen_ai.request.model, gen_ai.response.model and gen_ai.usage.*. It also says its own langfuse.* attributes take precedence, and that the GenAI conventions are still evolving. It does not name a convention version.

I did not verify the same for other LLM-tracing backends, so I name no others. Check your own backend's docs for the same four things: the supported convention version, what is required, what is dropped and what becomes a plain tag.

Pitfalls to avoid

  • Treating Development as stable. The status means names and shapes can change. Pin and expect migrations.
  • Reusing gen_ai.conversation.id as a realtime session ID. The realtime page forbids it.
  • Putting custom names under gen_ai.. You will collide with a future standard name.
  • Capturing message content by default. It is Opt-In for a reason. Voice transcripts hold personal data.
  • Assuming time to first chunk equals what the caller hears. It stops at the client, before synthesis and the phone network.
  • Relying on a single attribute for interruptions. The standard finish reason says a generation ended early. It does not say why.

Where Evalgent fits

A schema is only useful if something reads it. Evalgent Observe, which is launching, ingests OpenTelemetry data from any stack. You do not need a particular framework to use it. Traces explain why a call failed by pointing to the step or handoff behind it. Where the data is blind, the finding stays undetermined. So the work in this post pays off twice: standard gen_ai.* fields keep your traces readable by any tool, and a consistent voice.* layer carries the voice-specific facts. For the wider picture, see voice agent observability and how it differs from testing and monitoring. For production alerts on what you trace, see monitoring AI voice agents in production.

Frequently asked questions

Are the OpenTelemetry GenAI semantic conventions stable?

No. As of November 19, 2026, the GenAI conventions index in the semantic-conventions-genai repository says Status: Development. The client inference and realtime pages say the same. Nothing I read marks the GenAI signals as stable, so pin versions and plan for renames.

Where did the OpenTelemetry GenAI semantic conventions move?

They moved to the OpenTelemetry GenAI semantic conventions repository, semantic-conventions-genai on GitHub. The old pages on opentelemetry.io now show a notice saying the conventions moved and the page is no longer maintained there. Shared non-GenAI attributes, such as server.address, stay in the core semantic conventions repository.

Do the GenAI conventions cover speech or realtime audio?

Partly. The realtime page defines a realtime_inference span for model generation in streaming sessions, an opt-in user_speech span, session started and ended events, and gen_ai.realtime_session.id. All are Development status. There is no span for a separate STT or TTS service in a cascaded pipeline.

Is there an opt-in environment variable for GenAI conventions?

The OpenTelemetry GenAI pages I read do not mention one. Datadog's docs say that if a framework supported a pre-1.37 specification, you also set OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental. Treat it as a per-library setting and read each library's documentation.

What gen_ai attributes should every voice agent span carry?

Set gen_ai.conversation.id to your call ID on every span. On model spans, set gen_ai.operation.name and gen_ai.provider.name, which are Required, plus gen_ai.request.model. Add gen_ai.agent.version on the root span. Token counts are Recommended. Message content is Opt-In and should stay off by default.

How do I model a conversation turn with OpenTelemetry?

The GenAI conventions name no turn. Create a turn span per exchange under a call-level parent and add your own attributes, such as a turn index. Use a custom namespace like voice.*, and say in your own docs that these are not standard names. Pipecat's turn spans use a different, framework-specific turn.* set.

Should I use gen_ai or a custom namespace for voice data?

Use both, with a clear line between them. Use gen_ai.* where a convention already describes the data: model calls, tools, agents, call identity. Use one custom prefix, such as voice.*, for turns, interruptions, telephony legs and audio durations. Never put custom names inside gen_ai.*.

Which backends read GenAI semantic conventions?

Two I verified on their docs today, both for OpenTelemetry GenAI semantic conventions voice traces would use. Datadog says it supports OpenTelemetry 1.37+ GenAI conventions and keeps only spans with gen_ai.* attributes. Langfuse says it aims to be compliant with the conventions and that they are still evolving. Test any backend with a staged call before you depend on it.

The bottom line

The OpenTelemetry GenAI semantic conventions voice agents can use give standard names for model calls, tools, agents and call identity, plus early realtime and user speech signals, all at Development status. Everything specific to a phone call, such as turns, interruptions, telephony legs and audio duration, you add under your own voice.* namespace and pin by version.

Related Articles