---
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.extraction
├── 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.extraction
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"`) **\[2]**
* 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 | List of dictionaries describing the messages (prompts) sent to the LLM. **\[0]**, **\[1]**             | `'[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]'` |
| `gen_ai.tool.definitions`          | string | List of dictionaries describing the available tools. **\[0]**                                          | `'[{"name": "random_number", "description": "..."}, ...]'`            |
| `gen_ai.system_instructions`       | string | The system instructions passed to the model.                                                           | `"You are a helpful assistant."`                                      |
| `gen_ai.request.max_tokens`        | int    | Model configuration parameter.                                                                         | `500`                                                                 |
| `gen_ai.request.seed`              | string | Seed for reproducible outputs.                                                                         | `"12345"`                                                             |
| `gen_ai.request.frequency_penalty` | float  | Model configuration parameter.                                                                         | `0.5`                                                                 |
| `gen_ai.request.presence_penalty`  | float  | Model configuration parameter.                                                                         | `0.5`                                                                 |
| `gen_ai.request.temperature`       | float  | Model configuration parameter.                                                                         | `0.1`                                                                 |
| `gen_ai.request.top_p`             | float  | Model configuration parameter.                                                                         | `0.7`                                                                 |
| `gen_ai.request.top_k`             | int    | Limits model to K most likely next tokens.                                                             | `40`                                                                  |
| `gen_ai.request.reasoning.level`   | string | The reasoning or thinking effort level requested for a GenAI model. Supported values vary by provider. | `"medium"`                                                            |

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

| Attribute                             | Type    | Description                                                                              | Example                                                                    |
| ------------------------------------- | ------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `gen_ai.output.messages`              | string  | Stringified array of message objects representing the model's output. **\[0]**, **\[1]** | `'[{"role": "assistant", "parts": [{"type": "text", "content": "..."}]}]'` |
| `gen_ai.response.finish_reasons`      | string  | The reason why the model stopped generating.                                             | `"stop"`                                                                   |
| `gen_ai.response.id`                  | string  | Unique identifier for the completion.                                                    | `"chatcmpl-abc123"`                                                        |
| `gen_ai.response.streaming`           | boolean | Whether response was streamed asynchronously.                                            | `true`                                                                     |
| `gen_ai.response.time_to_first_chunk` | double  | Seconds until first response chunk in streaming.                                         | `0.5`                                                                      |

### [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.[\[1\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-1)[\[2\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-2) | `10`    |
| `gen_ai.usage.cache_read.input_tokens`     | integer | The number of cached tokens used to process the AI input (prompt).[\[1\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-1)[\[3\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-3)                        | `50`    |
| `gen_ai.usage.cache_creation.input_tokens` | integer | The number of tokens written to the cache when processing the AI input (prompt).[\[1\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-1)                                                                                                                        | `100`   |
| `gen_ai.usage.output_tokens`               | integer | The number of tokens used for creating the AI output (including reasoning tokens).[\[1\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-1)[\[4\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-4)        | `10`    |
| `gen_ai.usage.reasoning.output_tokens`     | integer | The number of tokens used for reasoning to create the AI output.[\[1\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-1)[\[5\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-5)                          | `75`    |
| `gen_ai.usage.total_tokens`                | integer | The total number of tokens used to process the prompt. (input tokens plus output todkens)[\[1\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-1)[\[6\]](https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents.md#gen_ai-usage-input_tokens-note-6) | `20`    |

1. This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen\_ai.operation.type:ai\_client to avoid double-counting hierarchical spans.
2. This count includes cached input tokens. gen\_ai.usage.cache\_read.input\_tokens is a subset of this value, not an independent count — do not sum them together.
3. This is a subset of gen\_ai.usage.input\_tokens, not an independent count. Do not sum this with gen\_ai.usage.input\_tokens — it is already included.
4. This count includes reasoning tokens. gen\_ai.usage.reasoning.output\_tokens is a subset of this value, not an independent count — do not sum them together.
5. This is a subset of gen\_ai.usage.output\_tokens, not an independent count. Do not sum this with gen\_ai.usage.output\_tokens — it is already included.
6. This is the sum of gen\_ai.usage.input\_tokens and gen\_ai.usage.output\_tokens. Do not sum this with either of them — they are already included.

See all [`gen_ai` attributes in Sentry Conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/).

## [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 | Input to embed.                         | "Hello, world!" |
| `gen_ai.usage.input_tokens` | int    | The number of tokens used in the input. | `60`            |

## [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"`                                            |

See all [`gen_ai` attributes in Sentry Conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/).

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

**\[0]:**

Span attributes only allow primitive data types (like `int`, `float`, `boolean`, `string`). This means you need to use a stringified version of a list of dictionaries. Do NOT set the object/array `[{"foo": "bar"}]` but rather the string `'[{"foo": "bar"}]'` (must be parsable JSON).

**\[1]:**

Messages use the format `{role, parts}` where `parts` is an array of typed objects: `[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. Each part has a `type`; common types include `"text"` (user-visible content), `"reasoning"` (internal thinking/chain-of-thought), `"tool_call"`, and `"tool_call_response"`. Use `{"type": "reasoning", "content": "..."}` for the model's thinking output — Sentry surfaces it separately and does not render it as a user-visible message in Conversations, so do not represent thinking content as a `"text"` part. For backwards compatibility, the legacy format `{role, content}` is also accepted.

**\[2]**

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.
