# Semantic conventions for generative AI tool execution **Status**: [Development][DocumentStatus] - [Span: `gen_ai.execute_tool`](#span-gen_aiexecute_tool) - [Specialized tool call spans](#specialized-tool-call-spans) - [Agent as a tool](#agent-as-a-tool) - [Agent skills](#agent-skills) - [Load skill span](#load-skill-span) - [Read skill resource span](#read-skill-resource-span) - [Command execution span](#command-execution-span) - [Events](#events) - [Event: `gen_ai.execute_tool.exception`](#event-gen_aiexecute_toolexception) - [Metrics](#metrics) - [Metric: `gen_ai.execute_tool.duration`](#metric-gen_aiexecute_toolduration) This document defines semantic conventions for tool executions performed by GenAI agents, frameworks, or applications, including spans, events, and metrics. ## Span: `gen_ai.execute_tool` **Status:**  Describes tool execution span. `gen_ai.operation.name` SHOULD be `execute_tool`. GenAI instrumentations that can instrument tool execution calls SHOULD do so, unless another instrumentation can reliably cover all supported tool types. MCP tool executions may also be traced by the [corresponding MCP instrumentation](/docs/gen-ai/mcp.md#client). Tools are often executed directly by application code. Application developers are encouraged to follow this semantic convention for tools invoked by their own code and to manually instrument any tool calls that automatic instrumentations do not cover. When the library API or state identifies a specialized tool call, instrumentation SHOULD apply the corresponding [refinement](/docs/gen-ai/execute-tool.md#specialized-tool-call-spans) to the execute-tool span. Available refinements include [agents exposed as tools](/docs/gen-ai/execute-tool.md#agent-as-a-tool) and [Agent Skills](/docs/gen-ai/execute-tool.md#agent-skills). **Span name** SHOULD be `execute_tool {gen_ai.tool.name}`. **Span kind** SHOULD be `INTERNAL`. **Span status** SHOULD follow the [Recording Errors](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/recording-errors.md) document. **Entity Associations** The span SHOULD be associated with one of the following entities: - [`gen_ai.main_agent`](/docs/registry/entities/gen-ai.md#gen-ai-main-agent) **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `realtime_inference` | | [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | Name of the tool utilized by the agent. | `Flights` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. [3] | `Math Tutor`; `Fiction Writer` | | [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | | [`gen_ai.tool.call.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [5] | string | The tool call identifier supplied by the model or provider. [6] | `call_mszuSIzqtI65i1wAUOE8w5H4` | | [`gen_ai.tool.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | The tool description. [7] | `Multiply two numbers` | | [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | Type of the tool utilized by the agent [8] | `function`; `extension`; `datastore` | | [`gen_ai.tool.call.arguments`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | Parameters passed to the tool call. [9] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | | [`gen_ai.tool.call.result`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | The result returned by the tool call (if any and if execution was successful). [10] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. **[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[3] `gen_ai.agent.name`:** This attribute MUST have low cardinality. It is NOT RECOMMENDED to use instrumentation-time constants, framework defaults, or type names such as "StateGraph". When no meaningful, low-cardinality name is available, this attribute MUST NOT be captured by default. Semantic conventions for individual Generative AI frameworks SHOULD document how `gen_ai.agent.name` is recorded in the context of that framework. **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have an identifier for the conversation readily available for a given operation, for example: - when the client framework being instrumented manages conversation history (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/), [LangChain `session_id`](https://reference.langchain.com/python/langchain-core/runnables/history/RunnableWithMessageHistory), and [Google ADK sessions](https://adk.dev/sessions/session)) - when instrumenting GenAI client libraries that maintain a conversation on the backend (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html), [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads)) When no identifier for the conversation is available, instrumentations SHOULD NOT populate conversation id. For example, a new UUID, a trace identifier, or a hash of request content SHOULD NOT be used as a fallback value. Application developers that manage conversation history MAY add conversation id to GenAI and other spans or logs using custom span or log record processors or hooks provided by instrumentation libraries. **[5] `gen_ai.tool.call.id`:** If and only if the model or provider supplied a tool call identifier. **[6] `gen_ai.tool.call.id`:** This attribute SHOULD be set to the identifier received from the model or provider if and only if one was supplied. **[7] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. **[8] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. **[9] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-arguments.json). **[10] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-result.json). The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | ## Specialized tool call spans When the library API or state identifies a specialized tool call, instrumentation SHOULD refine the [execute tool span](#span-gen_aiexecute_tool) as described below. ### Agent as a tool **Status:**  Describes a tool call that transfers work or control to another agent. Instrumentation SHOULD use this refinement for tool calls that the instrumented framework or protocol identifies as agent transfers and SHOULD NOT report additional spans for these tool calls. It MUST NOT be used for transfers that do not happen through a tool call. Examples include: - [Google ADK agent tools](https://google.github.io/adk-docs/tools-custom/function-tools/#agent-tool) that invoke a configured sub-agent; - [LangChain or LangGraph transfer tools](https://docs.langchain.com/oss/python/langchain/multi-agent/handoffs) that return a `Command` targeting another agent node; - [OpenAI Agents tools](https://openai.github.io/openai-agents-python/tools/#agents-as-tools) created from another agent. **Span name** SHOULD be `execute_tool {gen_ai.tool.name}`. Semantic conventions for individual frameworks MAY specify different span name format. **Span kind** SHOULD be `INTERNAL`. **Span status** SHOULD follow the [Recording Errors](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/recording-errors.md) document. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `realtime_inference` | | [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | Name of the tool utilized by the agent. | `Flights` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. [3] | `Math Tutor`; `Fiction Writer` | | [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | | [`gen_ai.tool.call.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [5] | string | The tool call identifier supplied by the model or provider. [6] | `call_mszuSIzqtI65i1wAUOE8w5H4` | | [`gen_ai.transfer.mode`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [7] | string | Describes how control passes to the transfer target. | `return_to_caller`; `pass_control` | | [`gen_ai.transfer.target.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [8] | string | The human-readable name of the agent targeted by the transfer. | `weather_agent` | | [`gen_ai.tool.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | The tool description. [9] | `Multiply two numbers` | | [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | Type of the tool utilized by the agent [10] | `function`; `extension`; `datastore` | | [`gen_ai.tool.call.arguments`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | Parameters passed to the tool call. [11] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | | [`gen_ai.tool.call.result`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | The result returned by the tool call (if any and if execution was successful). [12] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. **[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[3] `gen_ai.agent.name`:** This attribute MUST have low cardinality. It is NOT RECOMMENDED to use instrumentation-time constants, framework defaults, or type names such as "StateGraph". When no meaningful, low-cardinality name is available, this attribute MUST NOT be captured by default. Semantic conventions for individual Generative AI frameworks SHOULD document how `gen_ai.agent.name` is recorded in the context of that framework. **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have an identifier for the conversation readily available for a given operation, for example: - when the client framework being instrumented manages conversation history (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/), [LangChain `session_id`](https://reference.langchain.com/python/langchain-core/runnables/history/RunnableWithMessageHistory), and [Google ADK sessions](https://adk.dev/sessions/session)) - when instrumenting GenAI client libraries that maintain a conversation on the backend (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html), [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads)) When no identifier for the conversation is available, instrumentations SHOULD NOT populate conversation id. For example, a new UUID, a trace identifier, or a hash of request content SHOULD NOT be used as a fallback value. Application developers that manage conversation history MAY add conversation id to GenAI and other spans or logs using custom span or log record processors or hooks provided by instrumentation libraries. **[5] `gen_ai.tool.call.id`:** If and only if the model or provider supplied a tool call identifier. **[6] `gen_ai.tool.call.id`:** This attribute SHOULD be set to the identifier received from the model or provider if and only if one was supplied. **[7] `gen_ai.transfer.mode`:** When readily available from the instrumented library API or state, including when the transfer attempt fails. **[8] `gen_ai.transfer.target.name`:** When readily available from the instrumented library API or state, including when the transfer attempt fails. **[9] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. **[10] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. **[11] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-arguments.json). **[12] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-result.json). The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.transfer.target.name`](/docs/registry/attributes/gen-ai.md) --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | --- `gen_ai.transfer.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `pass_control` | The initiator does not wait for the target to finish. The target takes control of the remaining work. |  | | `return_to_caller` | The initiator waits for the target to finish and then resumes execution. |  | ### Agent skills An [Agent Skill](https://agentskills.io) is a folder holding a `SKILL.md` file - metadata (`name`, `description`) plus instructions - and, optionally, bundled `references/`, `assets/`, and `scripts/`. When a tool is used to interact with a skill, instrumentations SHOULD refine the [execute tool span](#span-gen_aiexecute_tool) as described below. #### Load skill span **Status:**  Describes a tool call that loads a skill into an agent's context. This refinement applies when a dedicated tool loads a skill. Examples include: - [Google ADK](https://adk.dev/skills/) `load_skill`; - [OpenAI Agents](https://openai.github.io/openai-agents-python/sandbox/guide/) `load_skill` for a lazy skill source; - [Strands Agents](https://strandsagents.com/docs/user-guide/sdk/plugins/skills/) `skills`; - [Agno](https://docs.agno.com/skills/overview) `get_skill_instructions`. **Span name** SHOULD be `execute_tool {gen_ai.tool.name} {gen_ai.skill.name}` when `gen_ai.skill.name` is available and `execute_tool {gen_ai.tool.name}` otherwise. **Span kind** SHOULD be `INTERNAL`. **Span status** SHOULD follow the [Recording Errors](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/recording-errors.md) document. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `realtime_inference` | | [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | Name of the tool utilized by the agent. | `Flights` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. [3] | `Math Tutor`; `Fiction Writer` | | [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | | [`gen_ai.skill.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If the skill name is available. | string | The name of the [Agent Skill](https://agentskills.io/specification#skill-md-format). | `code-review`; `pdf-processing` | | [`gen_ai.tool.call.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [5] | string | The tool call identifier supplied by the model or provider. [6] | `call_mszuSIzqtI65i1wAUOE8w5H4` | | [`gen_ai.skill.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If the skill description is available. | string | The [description of the Agent Skill](https://agentskills.io/specification#skill-md-format). [7] | `Review a changelist against the team's review policy.` | | [`gen_ai.skill.source.uri`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If the skill source URI is available. | string | The source URI for loading the skill. [8] | `https://skills.example.com/code-review`; `gs://example-skills/code-review`; `file:///opt/skills/code-review` | | [`gen_ai.tool.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | The tool description. [9] | `Multiply two numbers` | | [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | Type of the tool utilized by the agent [10] | `function`; `extension`; `datastore` | | [`gen_ai.tool.call.arguments`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | Parameters passed to the tool call. [11] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | | [`gen_ai.tool.call.result`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | The result returned by the tool call (if any and if execution was successful). [12] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. **[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[3] `gen_ai.agent.name`:** This attribute MUST have low cardinality. It is NOT RECOMMENDED to use instrumentation-time constants, framework defaults, or type names such as "StateGraph". When no meaningful, low-cardinality name is available, this attribute MUST NOT be captured by default. Semantic conventions for individual Generative AI frameworks SHOULD document how `gen_ai.agent.name` is recorded in the context of that framework. **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have an identifier for the conversation readily available for a given operation, for example: - when the client framework being instrumented manages conversation history (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/), [LangChain `session_id`](https://reference.langchain.com/python/langchain-core/runnables/history/RunnableWithMessageHistory), and [Google ADK sessions](https://adk.dev/sessions/session)) - when instrumenting GenAI client libraries that maintain a conversation on the backend (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html), [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads)) When no identifier for the conversation is available, instrumentations SHOULD NOT populate conversation id. For example, a new UUID, a trace identifier, or a hash of request content SHOULD NOT be used as a fallback value. Application developers that manage conversation history MAY add conversation id to GenAI and other spans or logs using custom span or log record processors or hooks provided by instrumentation libraries. **[5] `gen_ai.tool.call.id`:** If and only if the model or provider supplied a tool call identifier. **[6] `gen_ai.tool.call.id`:** This attribute SHOULD be set to the identifier received from the model or provider if and only if one was supplied. **[7] `gen_ai.skill.description`:** > [!WARNING] > This attribute may contain sensitive information. **[8] `gen_ai.skill.source.uri`:** This SHOULD identify the skill source, not a temporary location where the skill was materialized for execution. > [!WARNING] > This attribute may contain sensitive information. Sensitive URI components, such as user information and access tokens in query parameters, SHOULD be scrubbed when instrumentations can identify them. **[9] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. **[10] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. **[11] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-arguments.json). **[12] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-result.json). The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.skill.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | #### Read skill resource span **Status:**  Describes a tool call that reads a resource belonging to a skill. This refinement applies when a dedicated tool reads a skill resource. Examples include: - [Google ADK](https://adk.dev/skills/) `load_skill_resource`; - [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/agents/skills) `read_skill_resource`; - [Agno](https://docs.agno.com/skills/overview) `get_skill_reference` and `get_skill_script` when called with `execute=false`. **Span name** SHOULD be `execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name}` when the skill and resource names are available, `execute_tool {gen_ai.tool.name} {gen_ai.skill.resource.name}` when only the resource name is available, and `execute_tool {gen_ai.tool.name}` otherwise. The skill name SHOULD NOT be appended by itself. **Span kind** SHOULD be `INTERNAL`. **Span status** SHOULD follow the [Recording Errors](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/recording-errors.md) document. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `realtime_inference` | | [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | Name of the tool utilized by the agent. | `Flights` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. [3] | `Math Tutor`; `Fiction Writer` | | [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | | [`gen_ai.skill.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If the skill name is available. | string | The name of the [Agent Skill](https://agentskills.io/specification#skill-md-format). | `code-review`; `pdf-processing` | | [`gen_ai.skill.resource.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If the skill resource name is available. | string | The skill-relative name of the resource (script, reference, or asset) being accessed or executed. | `references/review_policy.md`; `assets/report_template.html` | | [`gen_ai.tool.call.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [5] | string | The tool call identifier supplied by the model or provider. [6] | `call_mszuSIzqtI65i1wAUOE8w5H4` | | [`gen_ai.skill.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If the skill description is available. | string | The [description of the Agent Skill](https://agentskills.io/specification#skill-md-format). [7] | `Review a changelist against the team's review policy.` | | [`gen_ai.skill.source.uri`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If the skill source URI is available. | string | The source URI for loading the skill. [8] | `https://skills.example.com/code-review`; `gs://example-skills/code-review`; `file:///opt/skills/code-review` | | [`gen_ai.tool.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | The tool description. [9] | `Multiply two numbers` | | [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | Type of the tool utilized by the agent [10] | `function`; `extension`; `datastore` | | [`gen_ai.tool.call.arguments`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | Parameters passed to the tool call. [11] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | | [`gen_ai.tool.call.result`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | The result returned by the tool call (if any and if execution was successful). [12] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. **[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[3] `gen_ai.agent.name`:** This attribute MUST have low cardinality. It is NOT RECOMMENDED to use instrumentation-time constants, framework defaults, or type names such as "StateGraph". When no meaningful, low-cardinality name is available, this attribute MUST NOT be captured by default. Semantic conventions for individual Generative AI frameworks SHOULD document how `gen_ai.agent.name` is recorded in the context of that framework. **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have an identifier for the conversation readily available for a given operation, for example: - when the client framework being instrumented manages conversation history (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/), [LangChain `session_id`](https://reference.langchain.com/python/langchain-core/runnables/history/RunnableWithMessageHistory), and [Google ADK sessions](https://adk.dev/sessions/session)) - when instrumenting GenAI client libraries that maintain a conversation on the backend (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html), [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads)) When no identifier for the conversation is available, instrumentations SHOULD NOT populate conversation id. For example, a new UUID, a trace identifier, or a hash of request content SHOULD NOT be used as a fallback value. Application developers that manage conversation history MAY add conversation id to GenAI and other spans or logs using custom span or log record processors or hooks provided by instrumentation libraries. **[5] `gen_ai.tool.call.id`:** If and only if the model or provider supplied a tool call identifier. **[6] `gen_ai.tool.call.id`:** This attribute SHOULD be set to the identifier received from the model or provider if and only if one was supplied. **[7] `gen_ai.skill.description`:** > [!WARNING] > This attribute may contain sensitive information. **[8] `gen_ai.skill.source.uri`:** This SHOULD identify the skill source, not a temporary location where the skill was materialized for execution. > [!WARNING] > This attribute may contain sensitive information. Sensitive URI components, such as user information and access tokens in query parameters, SHOULD be scrubbed when instrumentations can identify them. **[9] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. **[10] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. **[11] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-arguments.json). **[12] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-result.json). The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.skill.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.skill.resource.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | ### Command execution span **Status:**  Describes a tool call that executes one or more commands. This refinement applies when a tool represents command execution, including the execution of skill's script. Examples include: - [OpenAI Agents](https://openai.github.io/openai-agents-python/sandbox/guide/) `exec_command`, which runs both general commands and scripts from materialized skills; - [LangChain Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) sandbox `execute`, which runs both general commands and skill scripts; - [Strands Agents](https://strandsagents.com/docs/user-guide/sdk/plugins/skills/) `shell`, which is used for both general commands and bundled skill scripts; - [Anthropic](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) client `bash` for general commands; - [Google ADK](https://adk.dev/skills/) `run_skill_script`, which is dedicated to scripts bundled with skills; - [Agno](https://docs.agno.com/skills/overview) `get_skill_script` when called with `execute=true`. Instrumentations MAY also emit additional spans following the [CLI client span conventions](https://opentelemetry.io/docs/specs/semconv/cli/cli-spans/) for each observed command, script, or process execution. **Span name** SHOULD be: - `execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name}` when the skill and resource names are both available; - `execute_tool {gen_ai.tool.name} {gen_ai.skill.resource.name}` when only the skill resource name is available; - `execute_tool {gen_ai.tool.name} {process.executable.name}` when only the executable name is available; - `execute_tool {gen_ai.tool.name}` otherwise. The skill name SHOULD NOT be appended without the resource name. **Span kind** SHOULD be `INTERNAL`. **Span status** SHOULD follow the [Recording Errors](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/recording-errors.md) document. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `realtime_inference` | | [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | Name of the tool utilized by the agent. | `Flights` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. [3] | `Math Tutor`; `Fiction Writer` | | [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | | [`gen_ai.skill.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [5] | string | The name of the [Agent Skill](https://agentskills.io/specification#skill-md-format). | `code-review`; `pdf-processing` | | [`gen_ai.skill.resource.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [6] | string | The skill-relative name of the resource (script, reference, or asset) being accessed or executed. | `references/review_policy.md`; `assets/report_template.html` | | [`gen_ai.tool.call.id`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [7] | string | The tool call identifier supplied by the model or provider. [8] | `call_mszuSIzqtI65i1wAUOE8w5H4` | | [`process.executable.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/process.md) |  | `Conditionally Required` [9] | string | The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | | [`process.exit.code`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/process.md) |  | `Conditionally Required` [10] | int | The exit code of the process. | `127` | | [`gen_ai.skill.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` [11] | string | The [description of the Agent Skill](https://agentskills.io/specification#skill-md-format). [12] | `Review a changelist against the team's review policy.` | | [`gen_ai.skill.source.uri`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` [13] | string | The source URI for loading the skill. [14] | `https://skills.example.com/code-review`; `gs://example-skills/code-review`; `file:///opt/skills/code-review` | | [`gen_ai.tool.description`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | The tool description. [15] | `Multiply two numbers` | | [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | Type of the tool utilized by the agent [16] | `function`; `extension`; `datastore` | | [`process.executable.path`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/process.md) |  | `Recommended` [17] | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | | [`gen_ai.tool.call.arguments`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | Parameters passed to the tool call. [18] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | | [`gen_ai.tool.call.result`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | The result returned by the tool call (if any and if execution was successful). [19] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. **[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[3] `gen_ai.agent.name`:** This attribute MUST have low cardinality. It is NOT RECOMMENDED to use instrumentation-time constants, framework defaults, or type names such as "StateGraph". When no meaningful, low-cardinality name is available, this attribute MUST NOT be captured by default. Semantic conventions for individual Generative AI frameworks SHOULD document how `gen_ai.agent.name` is recorded in the context of that framework. **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have an identifier for the conversation readily available for a given operation, for example: - when the client framework being instrumented manages conversation history (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/), [LangChain `session_id`](https://reference.langchain.com/python/langchain-core/runnables/history/RunnableWithMessageHistory), and [Google ADK sessions](https://adk.dev/sessions/session)) - when instrumenting GenAI client libraries that maintain a conversation on the backend (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html), [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads)) When no identifier for the conversation is available, instrumentations SHOULD NOT populate conversation id. For example, a new UUID, a trace identifier, or a hash of request content SHOULD NOT be used as a fallback value. Application developers that manage conversation history MAY add conversation id to GenAI and other spans or logs using custom span or log record processors or hooks provided by instrumentation libraries. **[5] `gen_ai.skill.name`:** If the command is associated with a skill and its name is available. **[6] `gen_ai.skill.resource.name`:** If the command executes a named skill resource and the name is available. **[7] `gen_ai.tool.call.id`:** If and only if the model or provider supplied a tool call identifier. **[8] `gen_ai.tool.call.id`:** This attribute SHOULD be set to the identifier received from the model or provider if and only if one was supplied. **[9] `process.executable.name`:** If the tool directly executes a single process and the executable name is available. **[10] `process.exit.code`:** If the tool reports a single command or process exit code. **[11] `gen_ai.skill.description`:** If the command is associated with a skill and its description is available. **[12] `gen_ai.skill.description`:** > [!WARNING] > This attribute may contain sensitive information. **[13] `gen_ai.skill.source.uri`:** If the command is associated with a skill and its source URI is available. **[14] `gen_ai.skill.source.uri`:** This SHOULD identify the skill source, not a temporary location where the skill was materialized for execution. > [!WARNING] > This attribute may contain sensitive information. Sensitive URI components, such as user information and access tokens in query parameters, SHOULD be scrubbed when instrumentations can identify them. **[15] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. **[16] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. **[17] `process.executable.path`:** If the tool directly executes a single process and the executable path is available. **[18] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-arguments.json). **[19] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. This attribute MUST be recorded as an [AnyValue](https://opentelemetry.io/docs/specs/otel/common/#anyvalue) conforming to its [JSON schema](/model/gen-ai/gen-ai-tool-call-result.json). The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.skill.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.skill.resource.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) * [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | ## Events ### Event: `gen_ai.execute_tool.exception` **Status:**  The event name MUST be `gen_ai.execute_tool.exception`. This event represents an exception that caused a Generative AI tool execution operation to fail. Exception recording SHOULD follow the general [recording errors](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/recording-errors.md) guidance. This log event SHOULD be correlated with the execute tool span using its trace and span identifiers. Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. Instrumentations MAY provide a configuration option to populate this event with attributes captured on the corresponding execute tool span. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`exception.message`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/exception.md) |  | `Conditionally Required` [1] | string | The exception message. [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` | | [`exception.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/exception.md) |  | `Conditionally Required` [3] | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. [4] | `java.net.ConnectException`; `OSError` | | [`exception.stacktrace`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/exception.md) |  | `Recommended` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | **[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. **[2] `exception.message`:** > [!WARNING] > > This attribute may contain sensitive information. **[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. **[4] `exception.type`:** If the recorded exception type is a wrapper that is not meaningful for failure classification, instrumentation MAY use the type of the inner exception instead. For example, in Go, errors created with `fmt.Errorf` using `%w` MAY be unwrapped when the wrapper type does not help classify the failure. ## Metrics ### Metric: `gen_ai.execute_tool.duration` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.execute_tool.duration` | Histogram | `s` | The duration of a single tool execution. [1] |  | | **[1]:** Instrumentation that can reliably bound a single tool call SHOULD record this metric for every tool execution they can observe. When this metric is reported alongside a `gen_ai.execute_tool` span, the metric value SHOULD be the same as the span duration. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | Name of the tool utilized by the agent. | `Flights` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.45.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. [2] | `Math Tutor`; `Fiction Writer` | | [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | Type of the tool utilized by the agent [3] | `function`; `extension`; `datastore` | **[1] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[2] `gen_ai.agent.name`:** This attribute MUST have low cardinality. It is NOT RECOMMENDED to use instrumentation-time constants, framework defaults, or type names such as "StateGraph". When no meaningful, low-cardinality name is available, this attribute MUST NOT be captured by default. Semantic conventions for individual Generative AI frameworks SHOULD document how `gen_ai.agent.name` is recorded in the context of that framework. **[3] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters