From b7edaeac8c8deb5d6e0bae9c622daf79c294c299 Mon Sep 17 00:00:00 2001 From: Naveen Chatlapalli Date: Thu, 17 Sep 2026 22:14:43 -0500 Subject: [PATCH 1/2] feat(gen-ai): require provider-supplied tool call ID on execute_tool (#489) Clarify that gen_ai.tool.call.id must be the identifier supplied by the model or provider and prohibit synthetic fallback IDs (such as memory addresses or sequential counters). Promote requirement level on execute_tool from Recommended to Conditionally Required when supplied. --- changelog.d/489.clarification.md | 1 + docs/gen-ai/gen-ai-spans.md | 28 +++++---- docs/registry/attributes/gen-ai.md | 98 ++++++++++++++++-------------- model/gen-ai/registry.yaml | 6 +- model/gen-ai/spans.yaml | 2 +- 5 files changed, 75 insertions(+), 60 deletions(-) create mode 100644 changelog.d/489.clarification.md diff --git a/changelog.d/489.clarification.md b/changelog.d/489.clarification.md new file mode 100644 index 00000000..5dceceab --- /dev/null +++ b/changelog.d/489.clarification.md @@ -0,0 +1 @@ +Clarify that `gen_ai.tool.call.id` must be supplied by the model or provider and must not be synthesized from local identifiers. Update requirement level on `execute_tool` to conditionally required when supplied. diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index f8caa0d1..f23ebc4c 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -1155,11 +1155,11 @@ instrumentations do not cover. | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. | `Math Tutor`; `Fiction Writer` | | [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If available. | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [3] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | -| [`gen_ai.tool.call.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` If available. | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | -| [`gen_ai.tool.description`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` If available. | string | The tool description. [4] | `Multiply two numbers` | -| [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` If available. | string | Type of the tool utilized by the agent [5] | `function`; `extension`; `datastore` | -| [`gen_ai.tool.call.arguments`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | any | Parameters passed to the tool call. [6] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | -| [`gen_ai.tool.call.result`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | any | The result returned by the tool call (if any and if execution was successful). [7] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | +| [`gen_ai.tool.call.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | string | The tool call identifier supplied by the model or provider. [5] | `call_mszuSIzqtI65i1wAUOE8w5H4` | +| [`gen_ai.tool.description`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` If available. | string | The tool description. [6] | `Multiply two numbers` | +| [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` If available. | string | Type of the tool utilized by the agent [7] | `function`; `extension`; `datastore` | +| [`gen_ai.tool.call.arguments`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | any | Parameters passed to the tool call. [8] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | +| [`gen_ai.tool.call.result`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | any | The result returned by the tool call (if any and if execution was successful). [9] | {
  "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. @@ -1186,18 +1186,24 @@ Application developers that manage conversation history MAY add conversation id spans or logs using custom span or log record processors or hooks provided by instrumentation libraries. -**[4] `gen_ai.tool.description`:** +**[4] `gen_ai.tool.call.id`:** If the model or provider supplied a tool call identifier. + +**[5] `gen_ai.tool.call.id`:** This attribute MUST carry the identifier generated and supplied by the model or provider. +Instrumentations MUST NOT synthesize, generate, or fall back to local identifiers +(such as memory addresses or sequential counters) when no provider identifier is available. + +**[6] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. -**[5] `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. +**[7] `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. -**[6] `gen_ai.tool.call.arguments`:** +**[8] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. @@ -1210,7 +1216,7 @@ Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-tool-call-argume When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. -**[7] `gen_ai.tool.call.result`:** +**[9] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. @@ -1253,7 +1259,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `delete_memory_store` | Delete or deprovision a memory store | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | | `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) | -| `fetch_response` | Fetch a previously generated model response by its identifier, without performing inference, such as [OpenAI Get a model response](https://platform.openai.com/docs/api-reference/responses/get) [8] | ![Development](https://img.shields.io/badge/-development-blue) | +| `fetch_response` | Fetch a previously generated model response by its identifier, without performing inference, such as [OpenAI Get a model response](https://platform.openai.com/docs/api-reference/responses/get) [10] | ![Development](https://img.shields.io/badge/-development-blue) | | `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) | | `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | @@ -1264,7 +1270,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `update_memory` | Update existing memory records | ![Development](https://img.shields.io/badge/-development-blue) | | `upsert_memory` | Create or update memory records without the caller choosing which | ![Development](https://img.shields.io/badge/-development-blue) | -**[8]:** Instrumentations SHOULD NOT report token usage (as attributes or metrics) for this operation. +**[10]:** Instrumentations SHOULD NOT report token usage (as attributes or metrics) for this operation. diff --git a/docs/registry/attributes/gen-ai.md b/docs/registry/attributes/gen-ai.md index 9c84be4b..86d77323 100644 --- a/docs/registry/attributes/gen-ai.md +++ b/docs/registry/attributes/gen-ai.md @@ -58,27 +58,27 @@ | `gen_ai.system_instructions` | ![Development](https://img.shields.io/badge/-development-blue) | any | The system message or instructions provided to the GenAI model separately from the chat history. [26] | [
  {
    "type": "text",
    "content": "You are an Agent that greet users, always use greetings tool to respond"
  }
]; [
  {
    "type": "text",
    "content": "You are a language translator."
  },
  {
    "type": "text",
    "content": "Your mission is to translate text in English to French."
  }
] | | `gen_ai.token.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The type of token being counted. | `input`; `output` | | `gen_ai.tool.call.arguments` | ![Development](https://img.shields.io/badge/-development-blue) | any | Parameters passed to the tool call. [27] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | -| `gen_ai.tool.call.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | -| `gen_ai.tool.call.result` | ![Development](https://img.shields.io/badge/-development-blue) | any | The result returned by the tool call (if any and if execution was successful). [28] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | -| `gen_ai.tool.definitions` | ![Development](https://img.shields.io/badge/-development-blue) | any | The list of tool definitions available to the GenAI agent or model. [29] | [
  {
    "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.tool.description` | ![Development](https://img.shields.io/badge/-development-blue) | string | The tool description. [30] | `Multiply two numbers` | +| `gen_ai.tool.call.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | The tool call identifier supplied by the model or provider. [28] | `call_mszuSIzqtI65i1wAUOE8w5H4` | +| `gen_ai.tool.call.result` | ![Development](https://img.shields.io/badge/-development-blue) | any | The result returned by the tool call (if any and if execution was successful). [29] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | +| `gen_ai.tool.definitions` | ![Development](https://img.shields.io/badge/-development-blue) | any | The list of tool definitions available to the GenAI agent or model. [30] | [
  {
    "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.tool.description` | ![Development](https://img.shields.io/badge/-development-blue) | string | The tool description. [31] | `Multiply two numbers` | | `gen_ai.tool.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Name of the tool utilized by the agent. | `Flights` | -| `gen_ai.tool.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Type of the tool utilized by the agent [31] | `function`; `extension`; `datastore` | -| `gen_ai.usage.audio.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of audio input tokens served from a provider-managed cache. [32] | `60` | -| `gen_ai.usage.audio.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of audio input tokens. [33] | `120` | -| `gen_ai.usage.audio.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of audio output tokens. [34] | `240` | -| `gen_ai.usage.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens served from a provider-managed cache. [35] | `50` | -| `gen_ai.usage.cache_write.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens written to a provider-managed cache. [36] | `25` | -| `gen_ai.usage.image.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of image input tokens served from a provider-managed cache. [37] | `128` | -| `gen_ai.usage.image.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of image input tokens. [38] | `258` | -| `gen_ai.usage.image.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of image output tokens. [39] | `1290` | -| `gen_ai.usage.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI input (prompt). [40] | `100` | -| `gen_ai.usage.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI response (completion). [41] | `180` | -| `gen_ai.usage.reasoning.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of output tokens used for reasoning (e.g. chain-of-thought, extended thinking). [42] | `50` | -| `gen_ai.usage.text.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of text input tokens served from a provider-managed cache. [43] | `40` | -| `gen_ai.usage.text.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of text input tokens. [44] | `100` | -| `gen_ai.usage.text.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of text output tokens. [45] | `180` | -| `gen_ai.workflow.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the GenAI workflow provided by the application. [46] | `multi_agent_rag`; `customer_support_pipeline` | +| `gen_ai.tool.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Type of the tool utilized by the agent [32] | `function`; `extension`; `datastore` | +| `gen_ai.usage.audio.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of audio input tokens served from a provider-managed cache. [33] | `60` | +| `gen_ai.usage.audio.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of audio input tokens. [34] | `120` | +| `gen_ai.usage.audio.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of audio output tokens. [35] | `240` | +| `gen_ai.usage.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens served from a provider-managed cache. [36] | `50` | +| `gen_ai.usage.cache_write.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens written to a provider-managed cache. [37] | `25` | +| `gen_ai.usage.image.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of image input tokens served from a provider-managed cache. [38] | `128` | +| `gen_ai.usage.image.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of image input tokens. [39] | `258` | +| `gen_ai.usage.image.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of image output tokens. [40] | `1290` | +| `gen_ai.usage.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI input (prompt). [41] | `100` | +| `gen_ai.usage.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI response (completion). [42] | `180` | +| `gen_ai.usage.reasoning.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of output tokens used for reasoning (e.g. chain-of-thought, extended thinking). [43] | `50` | +| `gen_ai.usage.text.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of text input tokens served from a provider-managed cache. [44] | `40` | +| `gen_ai.usage.text.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of text input tokens. [45] | `100` | +| `gen_ai.usage.text.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of text output tokens. [46] | `180` | +| `gen_ai.workflow.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the GenAI workflow provided by the application. [47] | `multi_agent_rag`; `customer_support_pipeline` | **[1] `gen_ai.agent.id`:** For hosted agents, this SHOULD be the provider-assigned stable identifier of the agent resource such as [AWS Bedrock agent ARN](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) or [GCP Agent Registry identifier](https://docs.cloud.google.com/agent-registry/concepts#agent-identifier). @@ -285,7 +285,11 @@ Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-tool-call-argume When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. -**[28] `gen_ai.tool.call.result`:** +**[28] `gen_ai.tool.call.id`:** This attribute MUST carry the identifier generated and supplied by the model or provider. +Instrumentations MUST NOT synthesize, generate, or fall back to local identifiers +(such as memory addresses or sequential counters) when no provider identifier is available. + +**[29] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. @@ -298,7 +302,7 @@ Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-tool-call-result When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. -**[29] `gen_ai.tool.definitions`:** +**[30] `gen_ai.tool.definitions`:** > [!WARNING] > This attribute may contain sensitive information. @@ -311,34 +315,34 @@ Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-tool-definitions When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. -**[30] `gen_ai.tool.description`:** +**[31] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. -**[31] `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. +**[32] `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. -**[32] `gen_ai.usage.audio.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.audio.input_tokens`. +**[33] `gen_ai.usage.audio.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.audio.input_tokens`. -**[33] `gen_ai.usage.audio.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. +**[34] `gen_ai.usage.audio.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. -**[34] `gen_ai.usage.audio.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. +**[35] `gen_ai.usage.audio.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. -**[35] `gen_ai.usage.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. +**[36] `gen_ai.usage.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. -**[36] `gen_ai.usage.cache_write.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. +**[37] `gen_ai.usage.cache_write.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. -**[37] `gen_ai.usage.image.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.image.input_tokens`. +**[38] `gen_ai.usage.image.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.image.input_tokens`. -**[38] `gen_ai.usage.image.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. +**[39] `gen_ai.usage.image.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. -**[39] `gen_ai.usage.image.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. +**[40] `gen_ai.usage.image.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. -**[40] `gen_ai.usage.input_tokens`:** This value SHOULD include all types of input tokens, including cached tokens. +**[41] `gen_ai.usage.input_tokens`:** This value SHOULD include all types of input tokens, including cached tokens. Instrumentations SHOULD make a best effort to populate this value, using a total provided by the provider when available or, depending on the provider API, by summing different token types parsed from the provider output. @@ -356,20 +360,20 @@ if a request has 100 text tokens (40 cached) and 200 image tokens: - `gen_ai.usage.text.cache_read.input_tokens`: 40 - `gen_ai.usage.image.input_tokens`: 200 -**[41] `gen_ai.usage.output_tokens`:** When the provider reports both billed token counts and model-consumed +**[42] `gen_ai.usage.output_tokens`:** When the provider reports both billed token counts and model-consumed token counts (for example, Cohere exposes both `usage.billed_units` and `usage.tokens`), instrumentations SHOULD report the billed count so the value matches the units the customer is charged for. -**[42] `gen_ai.usage.reasoning.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. +**[43] `gen_ai.usage.reasoning.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. -**[43] `gen_ai.usage.text.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.text.input_tokens`. +**[44] `gen_ai.usage.text.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.text.input_tokens`. -**[44] `gen_ai.usage.text.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. +**[45] `gen_ai.usage.text.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. -**[45] `gen_ai.usage.text.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. +**[46] `gen_ai.usage.text.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. -**[46] `gen_ai.workflow.name`:** The workflow name is usually a static, application-unique identifier defined +**[47] `gen_ai.workflow.name`:** The workflow name is usually a static, application-unique identifier defined in a framework-specific way. For example, it can be the name of the first chain in LangChain, @@ -398,7 +402,7 @@ what `gen_ai.workflow.name` means in the context of that framework. | `delete_memory_store` | Delete or deprovision a memory store | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | | `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) | -| `fetch_response` | Fetch a previously generated model response by its identifier, without performing inference, such as [OpenAI Get a model response](https://platform.openai.com/docs/api-reference/responses/get) [47] | ![Development](https://img.shields.io/badge/-development-blue) | +| `fetch_response` | Fetch a previously generated model response by its identifier, without performing inference, such as [OpenAI Get a model response](https://platform.openai.com/docs/api-reference/responses/get) [48] | ![Development](https://img.shields.io/badge/-development-blue) | | `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) | | `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | @@ -409,7 +413,7 @@ what `gen_ai.workflow.name` means in the context of that framework. | `update_memory` | Update existing memory records | ![Development](https://img.shields.io/badge/-development-blue) | | `upsert_memory` | Create or update memory records without the caller choosing which | ![Development](https://img.shields.io/badge/-development-blue) | -**[47]:** Instrumentations SHOULD NOT report token usage (as attributes or metrics) for this operation. +**[48]:** Instrumentations SHOULD NOT report token usage (as attributes or metrics) for this operation. --- @@ -434,9 +438,9 @@ what `gen_ai.workflow.name` means in the context of that framework. | `azure.ai.openai` | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) | ![Development](https://img.shields.io/badge/-development-blue) | | `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [48] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [49] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [50] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [49] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [50] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [51] | ![Development](https://img.shields.io/badge/-development-blue) | | `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | | `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -445,11 +449,11 @@ what `gen_ai.workflow.name` means in the context of that framework. | `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | | `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -**[48]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. +**[49]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. -**[49]:** May be used when specific backend is unknown. +**[50]:** May be used when specific backend is unknown. -**[50]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. +**[51]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. --- diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml index d1d3a3f6..8e77f14c 100644 --- a/model/gen-ai/registry.yaml +++ b/model/gen-ai/registry.yaml @@ -477,7 +477,11 @@ attributes: stability: development - key: gen_ai.tool.call.id type: string - brief: The tool call identifier. + brief: The tool call identifier supplied by the model or provider. + note: | + This attribute MUST carry the identifier generated and supplied by the model or provider. + Instrumentations MUST NOT synthesize, generate, or fall back to local identifiers + (such as memory addresses or sequential counters) when no provider identifier is available. examples: ['call_mszuSIzqtI65i1wAUOE8w5H4'] stability: development - key: gen_ai.tool.description diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 32a8c27c..3f7949e8 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -600,7 +600,7 @@ spans: sampling_relevant: true - ref: gen_ai.tool.call.id requirement_level: - recommended: If available. + conditionally_required: If the model or provider supplied a tool call identifier. - ref: gen_ai.tool.description requirement_level: recommended: If available. From 5c0c59033f9d7d56b0ac93051fabb4d8aad14504 Mon Sep 17 00:00:00 2001 From: Naveen Chatlapalli Date: Thu, 17 Sep 2026 22:17:39 -0500 Subject: [PATCH 2/2] chore: update execute-tool reference report for conditionally required tool.call.id --- reference/reports/execute-tool-span.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/reports/execute-tool-span.md b/reference/reports/execute-tool-span.md index 3a1d00d1..a6d4a584 100644 --- a/reference/reports/execute-tool-span.md +++ b/reference/reports/execute-tool-span.md @@ -15,12 +15,12 @@ | --- | --- | | gen_ai.agent.name | [google-adk], [openai-agents], [pydantic-ai] | | gen_ai.conversation.id | [google-adk], [openai-assistants] | +| gen_ai.tool.call.id | [agent-framework], [autogen], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] | ## Recommended | Attribute | Supporting Libraries | | --- | --- | -| gen_ai.tool.call.id | [agent-framework], [autogen], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] | | gen_ai.tool.description | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] | | gen_ai.tool.type | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |