---
title: "AI Agents Module"
url: https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents/
---

# AI Agents Module | Sentry Docs

Agent tracing is agnostic to the library used. Agent invocation and tool execution spans are automatically instrumented in supported agent frameworks (such as LangChain). Requests to model providers are automatically instrumented when the request is issued with a client library instrumented by the SDK (first-party libraries from OpenAI, Anthropic, etc.). Requests through supported client libraries are instrumented even when triggered indirectly by an agent framework.

## [Spans Conventions](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#spans-conventions)

The `gen_ai.operation.name` attribute is essential to accurately categorize the GenAI span. The list of expected values is documented in the [conventions page](https://github.com/getsentry/sentry-conventions/blob/main/model/attributes/gen_ai/gen_ai__operation__name.json). For accurate cost calculation, token attributes and `gen_ai.response.model` are required. Cached and reasoning tokens are crucial if available, since they are subtracted from input and output tokens. The `gen_ai.agent.name`, or its `gen_ai.function_id` fallback drive grouping. The values allow users to filter for interactions with a specific identifier. For a span to show on the conversations page, `gen_ai.conversation.id` is required. The `gen_ai.input.messages` and `gen_ai.output.messages` are required to view the actual back-and-forth with a GenAI model. The page highlights an expanding set of part types, such as text, reasoning and tool uses.

##### Hint

The [Sentry Conventions](https://github.com/getsentry/sentry-conventions/) have all the detailed specifications for `"gen_ai.*"` span attributes.

Sentry Conventions is the single source of truth.

## [Span Relationships](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#span-relationships)

An agent invocation span has tool execution and chat span children, but chat spans need not have an agent invocation parent (not all chat requests are triggered by an agent). Agents can have other children such as extraction, decision and memory spans, depending on what's considered part of an agent execution in a given application. Automatic instrumentation considers an agent execution to be one run of the agent as represented by the supported library.

All span types can be children of a tool execution span because tools can be arbitrary functions (including starting subagents and performing handoffs). Chat, extraction and decision spans are basic building blocks and should not have GenAI spans as children.

Valid examples:

### [Agent execution with extraction, decision and memory children](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#agent-execution-with-extraction-decision-and-memory-children)

```bash
gen_ai.invoke_agent
├── gen_ai.chat
├── gen_ai.memory
├── gen_ai.extract
├── gen_ai.chat
├── gen_ai.execute_tool
├── gen_ai.chat
└── gen_ai.decide
```

### [Chat, memory, decision, and extraction spans outside of an agent execution](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#chat-memory-decision-and-extraction-spans-outside-of-an-agent-execution)

```bash
gen_ai.chat
gen_ai.extract
gen_ai.invoke_agent
├── gen_ai.chat
├── gen_ai.execute_tool
└── gen_ai.chat
gen_ai.decide
gen_ai.memory
```

### [Subagent](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#subagent)

```bash
gen_ai.invoke_agent
├── gen_ai.chat
├── gen_ai.execute_tool
│   └── gen_ai.invoke_agent
│       ├── gen_ai.chat
│       ├── gen_ai.execute_tool
│       └── gen_ai.chat
└── gen_ai.chat
```

## [Invoke Agent Span](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#invoke-agent-span)

Describes AI agent invocation. Agent invocations represent operations that can include multiple model calls, or some auxiliary work that goes beyond transforming the model input and output.

* Span `op` is `"gen_ai.invoke_agent"`.
* Span `name` is `"invoke_agent {gen_ai.agent.name}"`. (e.g. `"invoke_agent Weather Agent"`) In some agent libraries, the agent name is optional, and some do not provide the user an option to name their agents. In these cases, the span name is `"invoke_agent {call_id}"`, where `call_id` is some user-provided identifier for the agent invocation. For example, `functionId` in Vercel AI.
* Attribute `gen_ai.operation.name` is `"invoke_agent"`.
* Attribute `gen_ai.agent.name` is the agent's name. (e.g. `"Weather Agent"`). As a fallback to `gen_ai.agent.name`, the product also interprets `gen_ai.function_id` as an agent name for libraries that let users set a tracing identifier on a per-invocation basis.
* If relevant, the `gen_ai.pipeline.name` attribute is the name of the AI workflow, pipeline or chain within which the agent operates. (e.g. `"weather-pipeline"`)
* As a fallback to missing inputs and outputs on child chat spans, the Invoke Agent Span can carry `gen_ai.input.messages` and `gen_ai.system_instructions` based on the input of the first model call, and `gen_ai.output.messages` based on the output of the final model call under the agent execution.

## [AI Client Span](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#ai-client-span)

This span represents a chat model or text completion request.

* Span `op` is `"gen_ai.{gen_ai.operation.name}"`. (e.g. `"gen_ai.chat"`)
* Span `name` is `"{gen_ai.operation.name} {gen_ai.request.model}"`. (e.g. `"chat o3-mini"`)
* Attribute `gen_ai.operation.name` is `"chat"`, `"generate_content"` or `"text_completion"`.
* Attribute `gen_ai.provider.name` is the Generative AI product as identified by the client or server instrumentation. (e.g. `"openai"`)
* Attribute `gen_ai.request.model` is the requested model. (e.g. `"gpt-4o"`)
* Attribute `gen_ai.response.model` is the concrete response model. (e.g. `"gpt-4o-2024-08-06"`)
* If the request originates from an agent, the `gen_ai.agent.name` attribute is the name of the agent. (e.g. `"Weather Agent"`). As a fallback to `gen_ai.agent.name`, the product also interprets `gen_ai.function_id` as an agent name for libraries that let users set a tracing identifier on a per-invocation basis.
* If relevant, the `gen_ai.pipeline.name` attribute is the name of the AI workflow, pipeline or chain within which the agent operates. (e.g. `"weather-pipeline"`)

Additional attributes on the span:

### [Request Data](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#request-data)

| Attribute                          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Example                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.input.messages`            | string  | The messages passed to the model. It has to be a stringified version of an array of objects in the format `{role: "...", parts: [...]}`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. Each part is an object with a `type`, such as `{type: "text", content: "..."}`. Other part types include `"reasoning"`, `"tool_call"`, and `"tool_call_response"`. Put the model's thinking in a `{type: "reasoning", content: "..."}` part, not a `"text"` part. Sentry shows reasoning separately from user-visible messages. The legacy format `{role, content}` is also accepted. The first example shows this shape. Some operations use a different shape. See the additional context. | `'[{"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.tool.definitions`          | string  | The list of source system tool definitions available to the GenAI agent or model. It has to be a stringified version of an array of objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `'[{"type": "function", "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}}, "required": ["location", "unit"]}}]'`       |
| `gen_ai.system_instructions`       | string  | The system instructions passed to the model. It has to be a stringified version of an array of objects in the format `{type: "text", content: "..."}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `'[{"type": "text", "content": "You are a helpful assistant."}, {"type": "text", "content": "Be concise and clear."}]'`                                                                                                                                                                                                                                                       |
| `gen_ai.request.max_tokens`        | integer | The maximum number of tokens to generate in the response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `2048`                                                                                                                                                                                                                                                                                                                                                                        |
| `gen_ai.request.seed`              | string  | The seed, ideally models given the same seed and same other parameters will produce the exact same output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `"1234567890"`                                                                                                                                                                                                                                                                                                                                                                |
| `gen_ai.request.frequency_penalty` | double  | Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `0.5`                                                                                                                                                                                                                                                                                                                                                                         |
| `gen_ai.request.presence_penalty`  | double  | Used to reduce repetitiveness of generated tokens. Similar to frequency\_penalty, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `0.5`                                                                                                                                                                                                                                                                                                                                                                         |
| `gen_ai.request.temperature`       | double  | For an AI model call, the temperature parameter. Temperature essentially means how random the output will be.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `0.1`                                                                                                                                                                                                                                                                                                                                                                         |
| `gen_ai.request.top_p`             | double  | Limits the model to only consider tokens whose cumulative probability mass adds up to p, where p is a float between 0 and 1 (e.g., top\_p=0.7 means only tokens that sum up to 70% of the probability mass are considered).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `0.7`                                                                                                                                                                                                                                                                                                                                                                         |
| `gen_ai.request.top_k`             | integer | Limits the model to only consider the K most likely next tokens, where K is an integer (e.g., top\_k=20 means only the 20 highest probability tokens are considered).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `35`                                                                                                                                                                                                                                                                                                                                                                          |
| `gen_ai.request.reasoning.level`   | string  | The reasoning or thinking effort level requested for a GenAI model. Supported values vary by provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `"high"`                                                                                                                                                                                                                                                                                                                                                                      |

### [Response Data](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#response-data)

| Attribute                             | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Example                                                                                                                                    |
| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `gen_ai.output.messages`              | string  | The model's response messages. It has to be a stringified version of an array of message objects in the format `{role: "assistant", parts: [...]}`, which can include text responses and tool calls. Each part is an object with a `type`, such as `{type: "text", content: "..."}`. Other part types include `"reasoning"` and `"tool_call"`. Put the model's thinking in a `{type: "reasoning", content: "..."}` part, not a `"text"` part. Sentry shows reasoning separately from user-visible messages. The first example shows this shape. Some operations use a different shape. See the additional context. | `'[{"role": "assistant", "parts": [{"type": "text", "content": "The weather in Paris is currently rainy with a temperature of 57°F."}]}]'` |
| `gen_ai.response.finish_reasons`      | string  | The reason why the model stopped generating.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"COMPLETE"`                                                                                                                               |
| `gen_ai.response.id`                  | string  | Unique identifier for the completion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"gen_123abc"`                                                                                                                             |
| `gen_ai.response.streaming`           | boolean | Whether or not the AI model call's response was streamed back asynchronously                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `true`                                                                                                                                     |
| `gen_ai.response.time_to_first_chunk` | double  | Time in seconds when the first response content chunk arrived in streaming responses.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `0.6853435`                                                                                                                                |

### [Token Usage Data](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#token-usage-data)

| Attribute                                  | Type    | Description                                                                               | Example |
| ------------------------------------------ | ------- | ----------------------------------------------------------------------------------------- | ------- |
| `gen_ai.usage.input_tokens`                | integer | The number of tokens used to process the AI input (prompt) including cached input tokens. | `100`   |
| `gen_ai.usage.cache_read.input_tokens`     | integer | The number of cached tokens used to process the AI input (prompt).                        | `50`    |
| `gen_ai.usage.cache_creation.input_tokens` | integer | The number of tokens written to the cache when processing the AI input (prompt).          | `20`    |
| `gen_ai.usage.output_tokens`               | integer | The number of tokens used for creating the AI output (including reasoning tokens).        | `130`   |
| `gen_ai.usage.reasoning.output_tokens`     | integer | The number of tokens used for reasoning to create the AI output.                          | `30`    |
| `gen_ai.usage.total_tokens`                | integer | The total number of tokens used to process the prompt. (input tokens plus output tokens)  | `230`   |

## [Embedding Span](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#embedding-span)

This span represents a request to encode input into numeric vector embeddings.

* Span `op` is `"gen_ai.embeddings"`.
* Span `name` is `"embeddings {gen_ai.request.model}"`. (e.g. `"embeddings text-embedding-3-small"`)
* Attribute `gen_ai.operation.name` is `"embeddings"`.
* Attribute `gen_ai.provider.name` is the Generative AI product as identified by the client or server instrumentation. (e.g. `"openai"`)
* Attribute `gen_ai.request.model` is the requested model. (e.g. `"text-embedding-3-small"`)
* Attribute `gen_ai.response.model` is the concrete response model. (e.g. `"text-embedding-3-small-001"`)

Additional attributes on the span:

| Attribute                   | Type    | Description                                                                               | Example                          |
| --------------------------- | ------- | ----------------------------------------------------------------------------------------- | -------------------------------- |
| `gen_ai.embeddings.input`   | string  | The input to the embeddings model.                                                        | `"What's the weather in Paris?"` |
| `gen_ai.usage.input_tokens` | integer | The number of tokens used to process the AI input (prompt) including cached input tokens. | `100`                            |

## [Execute Tool Span](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#execute-tool-span)

Describes a tool execution.

* Span `op` is `"gen_ai.execute_tool"`.
* Span `name` is `"execute_tool {gen_ai.tool.name}"`. (e.g. `"execute_tool query_database"`)
* Attribute `gen_ai.operation.name` is `"execute_tool"`.
* Attribute `gen_ai.agent.name` is the name of the agent that invoked the tool. (e.g. `"Weather Agent"`). As a fallback to `gen_ai.agent.name`, the product also interprets `gen_ai.function_id` as an agent name for libraries that let users set a tracing identifier on a per-invocation basis.
* If relevant, the `gen_ai.pipeline.name` attribute is the name of the AI workflow, pipeline or chain within which the agent operates. (e.g. `"weather-pipeline"`)

Additional attributes on the span:

| Attribute                    | Type   | Description                                                                                      | Example                                                    |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `gen_ai.tool.name`           | string | Name of the tool utilized by the agent.                                                          | `"Flights"`                                                |
| `gen_ai.tool.description`    | string | The description of the tool being used.                                                          | `"Searches the web for current information about a topic"` |
| `gen_ai.tool.call.arguments` | string | The arguments of the tool call. It has to be a stringified version of the arguments to the tool. | `'{"location": "Paris"}'`                                  |
| `gen_ai.tool.call.result`    | string | The result of the tool call. It has to be a stringified version of the result of the tool.       | `"rainy, 57°F"`                                            |

## [Decision Span](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#decision-span)

Describes a decision on generated content against a set of questions, such as grading a model's reply for accuracy or classifying a support message, for example from TypeSafe Jev. Sentry shows decisions as their own rows in the conversation transcript and timeline, with dedicated **Input** and **Output** views.

* Span `op` is `"gen_ai.decide"`.
* Span `name` is `"decide {gen_ai.request.model}"`. (e.g. `"decide typesafe/jev-1.13"`)
* Attribute `gen_ai.operation.name` is `"decide"`. Decisions share the `ai_client` operation type with model calls, so this attribute is what tells them apart.
* Attribute `gen_ai.request.model` is the requested model. (e.g. `"typesafe/jev-1.13"`) Without a model, Relay doesn't classify the span as `ai_client`.
* Attribute `gen_ai.response.model` is the concrete response model, if the provider reports one. (e.g. `"typesafe/jev-1.13-20260917"`)
* If the decision runs under an agent, the `gen_ai.agent.name` attribute is the name of the agent. (e.g. `"Support Agent"`)

Additional attributes on the span:

| Attribute                    | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Example                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.input.messages`      | string  | The messages passed to the model. It has to be a stringified version of an array of objects in the format `{role: "...", parts: [...]}`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. Each part is an object with a `type`, such as `{type: "text", content: "..."}`. Other part types include `"reasoning"`, `"tool_call"`, and `"tool_call_response"`. Put the model's thinking in a `{type: "reasoning", content: "..."}` part, not a `"text"` part. Sentry shows reasoning separately from user-visible messages. The legacy format `{role, content}` is also accepted. The first example shows this shape. Some operations use a different shape. See the additional context. | `'[{"state": "I cannot log in, and I also want a refund for last month.", "questions": {"authIssue": {"type": "noul", "instructions": "Is there a login problem?"}, "department": {"type": "choice", "instructions": "Which team should handle this?", "criteria": {"billing": "Charges and refunds", "technical": "Bugs and outages"}}}}]'` |
| `gen_ai.output.messages`     | string  | The model's response messages. It has to be a stringified version of an array of message objects in the format `{role: "assistant", parts: [...]}`, which can include text responses and tool calls. Each part is an object with a `type`, such as `{type: "text", content: "..."}`. Other part types include `"reasoning"` and `"tool_call"`. Put the model's thinking in a `{type: "reasoning", content: "..."}` part, not a `"text"` part. Sentry shows reasoning separately from user-visible messages. The first example shows this shape. Some operations use a different shape. See the additional context.                                                                                         | `'[{"answers": {"authIssue": {"type": "noul", "noul": 0.98}, "department": {"type": "choice", "choice": "billing", "confidence": 0.28, "probabilities": {"billing": 0.64, "technical": 0.36}}}}]'`                                                                                                                                           |
| `gen_ai.usage.input_tokens`  | integer | The number of tokens used to process the AI input (prompt) including cached input tokens.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `100`                                                                                                                                                                                                                                                                                                                                        |
| `gen_ai.usage.output_tokens` | integer | The number of tokens used for creating the AI output (including reasoning tokens).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `130`                                                                                                                                                                                                                                                                                                                                        |

`gen_ai.input.messages` holds a one-element array with the content being evaluated (`state`) and the questions asked about it (`questions`). `gen_ai.output.messages` holds a one-element array with the answers (`answers`), keyed by the same question names.

## [Extraction Span](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#extraction-span)

Describes an extraction of typed fields from an input, such as the total and due date of an invoice, for example from Cloudflare Clairic. The model can extract values that are in the input, compute values from them, and estimate or forecast values that the input doesn't determine.

* Span `op` is `"gen_ai.extract"`.
* Span `name` is `"extract {gen_ai.request.model}"`. (e.g. `"extract @cf/cloudflare/clairic"`)
* Attribute `gen_ai.operation.name` is `"extract"`.
* Attribute `gen_ai.request.model` is the requested model. (e.g. `"@cf/cloudflare/clairic"`)
* Attribute `gen_ai.response.model` is the concrete response model, if the provider reports one. (e.g. `"clairic"`)
* If the extraction runs under an agent, the `gen_ai.agent.name` attribute is the name of the agent. (e.g. `"Billing Agent"`)

Additional attributes on the span:

| Attribute                    | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.input.messages`      | string  | The messages passed to the model. It has to be a stringified version of an array of objects in the format `{role: "...", parts: [...]}`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. Each part is an object with a `type`, such as `{type: "text", content: "..."}`. Other part types include `"reasoning"`, `"tool_call"`, and `"tool_call_response"`. Put the model's thinking in a `{type: "reasoning", content: "..."}` part, not a `"text"` part. Sentry shows reasoning separately from user-visible messages. The legacy format `{role, content}` is also accepted. The first example shows this shape. Some operations use a different shape. See the additional context. | `'[{"state": "Invoice INV-2291 from Northwind Supply, issued 2026-09-02, net 30. 4 pallets at $250.00 each, shipping $80.00. Contact: Dana Ruiz, Priya Shah.", "fields": {"invoice_number": {"type": "text"}, "due_date": {"type": "date", "instructions": "Issue date plus the net payment days"}, "total": {"type": "number", "decimals": 2, "unit": "USD", "instructions": "Amount due including shipping"}, "contacts": {"type": "list", "items": "text"}, "po_number": {"type": "text", "instructions": "Purchase order number"}, "days_to_pay": {"type": "estimate", "min": 0, "max": 120, "step": 1, "instructions": "Days after issue until this invoice is paid"}}}]'`                                                                                                                       |
| `gen_ai.output.messages`     | string  | The model's response messages. It has to be a stringified version of an array of message objects in the format `{role: "assistant", parts: [...]}`, which can include text responses and tool calls. Each part is an object with a `type`, such as `{type: "text", content: "..."}`. Other part types include `"reasoning"` and `"tool_call"`. Put the model's thinking in a `{type: "reasoning", content: "..."}` part, not a `"text"` part. Sentry shows reasoning separately from user-visible messages. The first example shows this shape. Some operations use a different shape. See the additional context.                                                                                         | `'[{"answers": {"invoice_number": {"type": "text", "p_null": 3.8e-10, "span": [8, 16], "guess": "INV-2291", "confidence": 1, "value": "INV-2291"}, "due_date": {"type": "date", "p_null": 1.9e-08, "guess": "2026-10-02", "confidence": 0.9999, "value": "2026-10-02"}, "total": {"type": "number", "p_null": 2.3e-08, "guess": 1080, "confidence": 0.9999, "value": 1080}, "contacts": {"type": "list", "value": ["Dana Ruiz", "Priya Shah"], "spans": [[120, 129], [131, 141]], "confidence": 0.9999}, "po_number": {"type": "text", "p_null": 1, "span": [8, 16], "guess": "INV-2291", "confidence": 0.9995, "value": null}, "days_to_pay": {"type": "estimate", "value": 30, "mean": 29.535, "median": 30, "p10": 21, "p90": 38, "p_below": 5.9e-06, "p_above": 1.2e-05}}, "truncated": false}]'` |
| `gen_ai.usage.input_tokens`  | integer | The number of tokens used to process the AI input (prompt) including cached input tokens.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `100`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `gen_ai.usage.output_tokens` | integer | The number of tokens used for creating the AI output (including reasoning tokens).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `130`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

`gen_ai.input.messages` holds a one-element array with the request body as the caller passed it, without `model`. `gen_ai.output.messages` holds a one-element array with the response body as the provider returned it, without `model` and `usage`. Don't send the other usage counts that the provider reports (such as Clairic's `state_tokens`, `image_tokens`, `schema_tokens`, and `passes`). `gen_ai.usage.input_tokens` already includes them.

## [Derived by Relay](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#derived-by-relay)

Relay sets these attributes during ingestion:

* `gen_ai.operation.type` is inferred from `gen_ai.operation.name` with a `sentry.op` fallback.
* `gen_ai.response.model` is set to `gen_ai.request.model` if not already present.
* `gen_ai.usage.total_tokens` is computed as `gen_ai.usage.input_tokens + gen_ai.usage.output_tokens`.
* `gen_ai.response.tokens_per_second` is computed as `gen_ai.usage.output_tokens` divided by the span duration.
* `gen_ai.context.window_size` is looked up from the model metadata registry by `gen_ai.response.model`.
* `gen_ai.context.utilization` is computed as `gen_ai.usage.total_tokens / gen_ai.context.window_size`.
* `gen_ai.cost.input_tokens`, `gen_ai.cost.output_tokens`, and `gen_ai.cost.total_tokens` are calculated from token counts and per-token pricing in the model registry.
