This document extends the official OpenTelemetry GenAI Semantic Conventions with rules and recommendations specific to Agent Lens. Where upstream says MAY or SHOULD, this profile usually says MUST (following RFC 2119). Except where this document says otherwise, the official semantic conventions apply.
API
Send OTLP protobuf to POST /agents/otel/v1/traces. For authentication and project routing, see Send OpenTelemetry spans to Agent Lens.
Checklist
To ensure that Agent Lens properly ingests your OTel span, make sure they adhere to the following rules:
Agent Lens Data Model Mapping
The following attributes are stored and exposed by Agent Lens. This list is not exhaustive and the exact fallback logic may be more complex than indicated here. Support for legacy and deprecated attributes (including OpenInference) is best-effort.
Special GenAI Operation Names
Every span MUST set gen_ai.operation.name. Its value SHOULD be a well-known name defined in the official OTel semantic conventions. The following operation names are special in Agent Lens. These are the minimum operations necessary to describe most agentic workflows.
Custom Attributes
Agent Lens accepts vendor-specific and user-defined attribute names, and makes them available as custom attributes. For example, my_company.user.is_admin=true, my_company.user.sentiment="positive", and my_company.eval.score=0.5.
- Custom attribute values MUST be integers, floats, strings, or boolean values.
- Custom attribute names MUST be low-cardinality and MUST NOT be generated dynamically.
- Custom attribute names SHOULD use a consistent namespace, such as
my_company.*.
OTel Spans & Attributes
This section follows the structure of the official OTel semantic convention’s agent spans and inference spans, but lists only where this profile diverges. Everything else follows official guidelines, including span names, span kinds, and the spans not listed here.
In Agent Lens, a root span MUST be either invoke_workflow OR invoke_agent. Use invoke_workflow to handle complex cases where a user can invoke several agents at once. Otherwise prefer invoke_agent.
In Agent Lens, a root span MUST be either invoke_workflow OR invoke_agent. Use invoke_workflow to handle complex cases where a user can invoke several agents at once. Otherwise prefer invoke_agent.
Inference span
Agent Lens uses inference spans to build the message history of a conversation and estimate costs. Inference spans also carry tool call requests and responses. If a model sends its final response via tool call, that tool name MUST be: final_answer, final_result, set_model_response, or send_message.
Token usage and cost
Agent Lens estimates the cost of each inference span from its token usage and gen_ai.response.model:
gen_ai.usage.input_tokens MUST be the total input, including cached tokens. Cache reads and writes SHOULD also be reported in gen_ai.usage.cache_read.input_tokens and gen_ai.usage.cache_write.input_tokens. Agent Lens subtracts them from the total and prices them at their own rates. If gen_ai.usage.input_tokens counts only uncached tokens, input is undercounted and cost can show as negative.
gen_ai.usage.output_tokens MUST be the total output, including reasoning tokens.
- Some providers report these counts separately, so add them back into the totals. Anthropic reports cached tokens apart from input tokens, and Gemini reports thinking tokens apart from output tokens. OpenAI already includes cached tokens in its input count and reasoning tokens in its output count.
gen_ai.response.model MUST be the exact model ID the provider returned. An alias such as opus or sonnet has no price, and the call shows Cost -.
- Usage attributes SHOULD be set on inference spans only. Don’t copy a turn’s totals to its
invoke_agent span.
A tool call happens when a model asks your application to run a function. One tool call appears in three spans, and your instrumentation must record the same gen_ai.tool.call.id in each so that Agent Lens can link them:
- The inference span where the model requests the call, as a tool_call part in gen_ai.output.messages.
- The execute_tool span for the function run.
- The next inference span, which returns the result to the model as a tool_call_response part in gen_ai.input.messages.
The request, execution, and response parts MUST all be linked by the same gen_ai.tool.call.id, and this ID MUST be unique within a trace.
Examples
A workflow runs two agents in parallel
An agent generates an image
Last modified on November 18, 2026