> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry semantic conventions for Agent Lens

> The OpenTelemetry GenAI span shapes and attributes that Agent Lens expects from your agent.

This document extends the official [OpenTelemetry GenAI Semantic Conventions](https://github.com/open-telemetry/semantic-conventions-genai) with rules and recommendations specific to Agent Lens. Where upstream says MAY or SHOULD, this profile usually says MUST (following [RFC 2119](https://www.ietf.org/archive/id/draft-saintandre-2119bis-01.html)). 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](https://docs.coreweave.com/products/agent-lens/get-started/opentelemetry.md).

## Checklist

To ensure that Agent Lens properly ingests your OTel span, make sure they adhere to the following rules:

| Applies to | Rule |
| - | - |
| All spans | MUST set `gen_ai.operation.name` and SHOULD set it to a [well-known](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/registry/attributes/gen-ai.md#gen-ai-operation-name) value |
| Root spans | MUST set `gen_ai.operation.name` to `invoke_agent` or `invoke_workflow` |
| Root spans | MUST set `gen_ai.conversation.id` and SHOULD set `user.id` |
| All traces | MUST include at least one `invoke_agent` span |
| All traces | MUST include a root span with no `parent_id` |
| All traces | MUST include at least one span that sets `gen_ai.input.messages` and `gen_ai.output.messages` (and SHOULD set `gen_ai.system_instructions` if applicable). |
| [Inference spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md#span-gen_aiclientinference) | MUST include the full context sent to the model in `gen_ai.input.messages` and MUST include its full response in `gen_ai.output.messages` (and SHOULD set `gen_ai.system_instructions` if applicable) |
| [Inference spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md#span-gen_aiclientinference) | MUST set `gen_ai.response.model` and SHOULD set `gen_ai.provider.name` |
| [Inference spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md#span-gen_aiclientinference) | SHOULD set `gen_ai.operation.name` to `chat`, `generate_content`, or `text_completion` |
| [Inference spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md#span-gen_aiclientinference) | SHOULD set all relevant `gen_ai.usage` attributes |
| [Tool execution spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md#execute-tool-span) | MUST set `gen_ai.tool.call.id` and this value MUST match the corresponding `tool_call` request and `tool_call_response` messages. |
| Failed spans | MUST set status `ERROR` and `error.type`. |

## 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.

| Agent Lens Field | OTel Source | Fallback Sources |
| - | - | - |
| `operation_name` | `gen_ai.operation.name` | `openinference.span.kind` |
| `conversation_id` | `gen_ai.conversation.id` | `conversation.id`, `session.id` |
| `user_id` | `user.id` | `enduser.id`, `enduser.pseudo.id`, `user.hash` |
| `user_email` | `user.email` | |
| `status_code` | OTel span status (not an attribute) | |
| `status_message` | OTel span status (not an attribute) | |
| `error_type` | `error.type` | |
| `provider_name` | `gen_ai.provider.name` | `gen_ai.system`, `llm.provider`, `llm.system` |
| `agent_name` | `gen_ai.agent.name` | `agent.name` |
| `agent_version` | `gen_ai.agent.version` | |
| `request_model` | `gen_ai.request.model` | `gen_ai.response.model`, `llm.request.model_name`, `embedding.model_name`, `llm.invocation_parameters.model`, `llm.model_name` |
| `response_model` | `gen_ai.response.model` | `gen_ai.request.model`, `llm.response.model_name`, `llm.model_name` |
| `input_messages` | `gen_ai.input.messages` | `gen_ai.prompt`, `llm.input_messages`, `llm.prompts.N.prompt.text`, `input.value` |
| `output_messages` | `gen_ai.output.messages` | `gen_ai.completion`, `llm.output_messages`, `llm.choices.N.completion.text`, `output.value` |
| `output_type` | `gen_ai.output.type` | |
| `system_instructions` | `gen_ai.system_instructions` | The text of system role messages |
| `finish_reasons` | `gen_ai.response.finish_reasons` | `llm.finish_reason` |
| `tool_call_id` | `gen_ai.tool.call.id` | `tool_call.id`, `tool.id`, `data.tool_call_id` |
| `tool_name` | `gen_ai.tool.name` | `tool.name`, `tool_call.function.name` |
| `tool_definitions` | `gen_ai.tool.definitions` | `llm.tools.N.tool.json_schema` |
| `tool_call_result` | `gen_ai.tool.call.result` | `data.content`, `output.value` |
| `tool_call_arguments` | `gen_ai.tool.call.arguments` | `tool_call.function.arguments`, `input.value` |
| `input_tokens` | `gen_ai.usage.input_tokens` | `llm.token_count.prompt` |
| `output_tokens` | `gen_ai.usage.output_tokens` | `llm.token_count.completion` |
| `reasoning_tokens` | `gen_ai.usage.reasoning.output_tokens` | `gen_ai.usage.reasoning_tokens`, `gen_ai.usage.experimental.reasoning_tokens`, `llm.token_count.completion_details.reasoning` |
| `cache_creation_input_tokens` | `gen_ai.usage.cache_write.input_tokens` | `gen_ai.usage.cache_creation.input_tokens`, `llm.token_count.prompt_details.cache_write` |
| `cache_read_input_tokens` | `gen_ai.usage.cache_read.input_tokens` | `gen_ai.usage.prompt_tokens_details.cached_tokens`, `gen_ai.usage.input_tokens_details.cached_tokens`, `prompt_tokens_details.cached_tokens`, `llm.token_count.prompt_details.cache_read`, `llm.token_count.prompt_details.cache_input` |

## 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](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/registry/attributes/gen-ai.md#gen-ai-operation-name). The following operation names are special in Agent Lens. These are the minimum operations necessary to describe most agentic workflows.

| Operation Name | Represents | Special Use |
| - | - | - |
| [`invoke_agent`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span), [`invoke_workflow`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-workflow-span) | One turn | Determine the conversation ID and user ID for the entire turn. |
| [Inference spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md#span-gen_aiclientinference) (`chat`, `generate_content`, `text_completion`) | One model request | Determine the input and output messages in the chat history. Determine token usage and cost data. |
| [`execute_tool`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-spans.md#execute-tool-span) | One tool execution run by your application | Links `tool_call` requests with `tool_call_response` messages. |

## 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](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md#spans) and [inference spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md), but lists only where this profile diverges. Everything else follows official guidelines, including span names, span kinds, and the spans not listed here.

### [Invoke workflow span](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-workflow-span)

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`.

| Attribute | Requirement Level | Notes | Example Values |
| - | - | - | - |
| `gen_ai.operation.name` | Required | | `invoke_workflow` |
| `gen_ai.conversation.id` | Required | | `conv_5j66UpCpwteGg4YSxUnt7lPY` |
| `user.id` | Recommended | An ID for the user who initiated the turn. | `usr_8kscj` |
| `user.email` | Optional | An email for the user who initiated this turn. | `user@domain.com` |
| `gen_ai.agent.name` | Recommended | The agent's permanent name. SHOULD NOT include version information. | `Math Tutor`; `Fiction Writer` |
| `gen_ai.agent.version` | Recommended | | `1.0.0`; `2025-05-01` |
| `gen_ai.input.messages` | Recommended | The input that triggered this invocation. MUST NOT include history from earlier turns or system instructions. | `[{"role": "user", "parts": [{"type": "text", "content": "Summarize GPU news"}]}]` |
| `gen_ai.output.messages` | Recommended | The workflow's final response to the user. If several agents run in parallel, this is the combined result the user sees. | `[{"role": "assistant", "parts": [{"type": "text", "content": "GPU prices fell 8% this week."}]}]` |

### [Invoke agent span](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span)

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`.

| Attribute | Requirement Level | Notes | Example Values |
| - | - | - | - |
| `gen_ai.operation.name` | Required | | `invoke_agent` |
| `gen_ai.conversation.id` | Required | | `conv_5j66UpCpwteGg4YSxUnt7lPY` |
| `user.id` | Recommended | An ID for the user who initiated the turn. | `usr_8kscj` |
| `user.email` | Optional | An email for the user who initiated the turn. | `user@domain.com` |
| `gen_ai.agent.name` | Recommended | The agent's permanent name. SHOULD NOT include version information. | `Math Tutor`; `Fiction Writer` |
| `gen_ai.agent.version` | Recommended | | `1.0.0`; `2025-05-01` |
| `gen_ai.input.messages` | Recommended | The input that triggered this invocation. MUST NOT include history from earlier turns or system instructions. | `[{"role": "user", "parts": [{"type": "text", "content": "Where is order 12?"}]}]` |
| `gen_ai.output.messages` | Recommended | The agent's final response, as an assistant message. MUST NOT include intermediate tool calls or model outputs. | `[{"role": "assistant", "parts": [{"type": "text", "content": "It shipped yesterday."}]}]` |

### Inference span

Agent Lens uses [inference spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md#span-gen_aiclientinference) 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`.

| Attribute | Requirement Level | Notes | Example Values |
| - | - | - | - |
| `gen_ai.operation.name` | Required | | `chat`, `generate_content`, `text_completion` |
| `user.id` | Recommended | An ID for the user who initiated the turn. | `usr_8kscj` |
| `user.email` | Optional | An email for the user who initiated the turn. | `user@domain.com` |
| `gen_ai.agent.name` | Recommended | The agent's permanent name. SHOULD NOT include version information. | `Math Tutor`; `Fiction Writer` |
| `gen_ai.agent.version` | Recommended | | `1.0.0`; `2025-05-01` |
| `gen_ai.provider.name` | Recommended | | |
| `gen_ai.response.model` | Required | The exact model ID the provider returned, used to estimate cost | `gpt-4-0613` |
| `gen_ai.response.finish_reasons` | Recommended | One entry per output message, in the same order as `gen_ai.output.messages`. | `["stop", "length", "error"]` |
| `gen_ai.input.messages` | Required | Include the full context sent to the model, not just the most recent prompt. | `[{"role": "user", "parts": [{"type": "text", "content": "Weather in Paris?"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name": "get_weather", "arguments": {"location": "Paris"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "response": "rainy, 57°F"}]}]` |
| `gen_ai.output.messages` | Required | | `[{"role": "assistant", "parts": [{"type": "text", "content": "The weather in Paris is currently rainy with a temperature of 57°F."}]}]` |
| `gen_ai.system_instructions` | Recommended | | `[{"type": "text", "content": "You are an Agent that greet users, always use greetings tool to respond"}]` |
| `gen_ai.usage.input_tokens` | Required | MUST include cache read and write tokens (if any) | |
| `gen_ai.usage.output_tokens` | Required | MUST include reasoning tokens (if any) | |

#### 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.

### Execute tool span

A [tool call](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md#execute-tool-span)  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:

1. The inference span where the model requests the call, as a tool\_call part in gen\_ai.output.messages.
2. The execute\_tool span for the function run.
3. 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.

| Attribute | Requirement Level | Notes | Example Values |
| - | - | - | - |
| `gen_ai.operation.name` | Required | | `execute_tool` |
| `user.id` | Recommended | An ID for the user who initiated the turn. | `usr_8kscj` |
| `user.email` | Optional | An email for the user who initiated the turn. | `user@domain.com` |
| `gen_ai.agent.name` | Recommended | The agent's permanent name. SHOULD NOT include version information. | `Math Tutor`; `Fiction Writer` |
| `gen_ai.agent.version` | Recommended | | `1.0.0`; `2025-05-01` |
| `gen_ai.tool.call.id` | Required | MUST match the IDs of the corresponding `tool_call` and `tool_call_response` messages. | `call_mszuSIzqtI65i1wAUOE8w5H4` |
| `gen_ai.tool.call.arguments` | Required | | `{"location": "San Francisco?", "date": "2025-10-01"}` |
| `gen_ai.tool.call.result` | Recommended | | `{"temperature_range": {"high": 75, "low": 60}, "conditions": "sunny"}` |

## Examples

### An agent uses a tool to answer a question

```plaintext theme={"system"}
// The turn: the user's question and the agent's answer.
invoke_agent support-bot  conversation=conv_1  user=u_42
  in:   user "Where is order 12?"
  out:  assistant "It shipped."

  // The model requests a tool call, identified by call_1.
  chat claude-sonnet-5-5  provider=anthropic
    in:   user "Where is order 12?"
    out:  assistant call get_order[call_1] {"order_id": "12"}  finish=tool_call

  // The application runs the tool under the same call ID.
  execute_tool get_order  call=call_1
    args:    {"order_id": "12"}
    result:  "shipped"

  // The next model call sees the full context, including the tool result.
  chat claude-sonnet-5-5  provider=anthropic
    in:   ...
          tool result[call_1] "shipped"
    out:  assistant "It shipped."  finish=stop
```

### The agent calls a sub-agent as a tool

```plaintext theme={"system"}
// The turn: the user's question and the final answer.
invoke_agent triage  conversation=conv_3  user=u_42
  in:   user "Was I double charged?"
  out:  assistant "Yes, one charge was a duplicate."

  // The parent's model delegates by calling the sub-agent as a tool.
  chat claude-sonnet-5-5  provider=anthropic
    in:   user "Was I double charged?"
    out:  assistant call billing_agent[call_2] {"task": "Check account 88"}  finish=tool_call

  // The tool execution's result is the sub-agent's answer.
  execute_tool billing_agent  call=call_2
    args:    {"task": "Check account 88"}
    result:  "Yes, one duplicate."

    // The sub-agent sees only the task it was given.
    invoke_agent billing
      in:   user "Check account 88"
      out:  assistant "Yes, one duplicate."

  // The parent's model gets the answer back as the tool result and replies.
  chat claude-sonnet-5-5  provider=anthropic
    in:   ...
          tool result[call_2] "Yes, one duplicate."
    out:  assistant "Yes, one charge was a duplicate."  finish=stop
```

### A workflow runs two agents in parallel

```plaintext theme={"system"}
// The turn: a workflow that runs two agents in parallel and combines their answers.
invoke_workflow news-pipeline  conversation=conv_2  user=u_42
  in:   user "Summarize GPU and CPU news"
  out:  assistant "GPU prices fell 8% this week, and CPU prices held steady."

  // Both agents start together, and each gets only its own task.
  invoke_agent gpu-researcher
    in:   user "Find GPU pricing news"
    out:  assistant "GPU prices fell 8%."

  // Siblings under the same parent, with overlapping start and end times.
  invoke_agent cpu-researcher
    in:   user "Find CPU pricing news"
    out:  assistant "CPU prices held steady."
```

### An agent generates an image

```plaintext theme={"system"}
// The turn: the agent's response is an image.
invoke_agent designer  conversation=conv_6  user=u_42
  in:   user "Draw a coffee shop logo"
  out:  assistant [image/png blob]

  // The image is sent inline as a blob part, with its modality set.
  generate_content gemini-2.5-flash-image  provider=gcp.gemini
    in:   user "Draw a coffee shop logo"
    out:  assistant [image/png blob]  finish=stop
```

### A tool call that fails

```plaintext theme={"system"}
// The agent recovered, so the turn has no error status.
invoke_agent support-bot  conversation=conv_7  user=u_42
  in:   user "Where is order 34?"
  out:  assistant "The order system is down. Try again soon."

  // The model requests a tool call.
  chat claude-sonnet-5-5  provider=anthropic
    in:   user "Where is order 34?"
    out:  assistant call get_order[call_4] {"id": "34"}  finish=tool_call

  // The tool times out: status ERROR with error.type, and no result.
  execute_tool get_order  call=call_4  status=ERROR(TimeoutError)
    args:    {"id": "34"}

  // The error goes back to the model as the tool result, and it replies.
  chat claude-sonnet-5-5  provider=anthropic
    in:   ...
          tool result[call_4] "Error: timed out"
    out:  assistant "The order system is down. Try again soon."  finish=stop
```
