feat: update toolcall types to match semconv

Author: keith-decker

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py

@@ -43,17 +43,53 @@ class ContentCapturingMode(Enum):
 
 @dataclass()
 class ToolCall:
-    """Represents a tool call requested by the model
-
-    This model is specified as part of semconv in `GenAI messages Python models - ToolCallRequestPart
-    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """Represents a tool call with dual usage: message part and execution tracking.
+
+    This type serves two purposes as defined in OpenTelemetry semantic conventions:
+
+    1. Message Part (ToolCallRequestPart):
+       Represents a tool call requested by the model as part of a message.
+       Reference: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb
+
+    2. Tool Execution (execute_tool spans):
+       Represents the actual execution of a tool call, tracked via spans and metrics.
+       Reference: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md#execute-tool-span
+
+    The execution-only fields (tool_type, tool_description, tool_result, error_type)
+    are used when tracking tool execution via spans, but are typically not present when
+    this type is used as a message part in InputMessage or OutputMessage.
+
+    Semantic convention attributes for execute_tool spans:
+    - gen_ai.operation.name: "execute_tool" (Required)
+    - gen_ai.tool.name: Name of the tool (Recommended)
+    - gen_ai.tool.call.id: Tool call identifier (Recommended if available)
+    - gen_ai.tool.type: Type classification - "function", "extension", or "datastore" (Recommended if available)
+    - gen_ai.tool.description: Tool description (Recommended if available)
+    - gen_ai.tool.call.arguments: Parameters passed to tool (Opt-In, may contain sensitive data)
+    - gen_ai.tool.call.result: Result returned by tool (Opt-In, may contain sensitive data)
+    - error.type: Error type if operation failed (Conditionally Required)
     """
 
-    arguments: Any
+    # Fields used for both message part and execution tracking:
+    # gen_ai.tool.name - Name of the tool
     name: str
-    id: str | None
+    # gen_ai.tool.call.arguments - Arguments passed to the tool (Opt-In, may contain sensitive data)
+    arguments: Any = None
+    # gen_ai.tool.call.id - Unique identifier for the tool call
+    id: str | None = None
+    # Message part type identifier
     type: Literal["tool_call"] = "tool_call"
 
+    # Execution-only fields (used for execute_tool spans, not typically in messages):
+    # gen_ai.tool.type - Tool type: "function", "extension", or "datastore"
+    tool_type: str | None = None
+    # gen_ai.tool.description - Description of what the tool does
+    tool_description: str | None = None
+    # gen_ai.tool.call.result - Result returned by the tool (Opt-In, may contain sensitive data)
+    tool_result: Any = None
+    # error.type - Error type if the tool call failed
+    error_type: str | None = None
+
 
 @dataclass()
 class ToolCallResponse:

util/opentelemetry-util-genai/tests/test_toolcall.py

@@ -0,0 +1,125 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for Enhanced ToolCall Type Definition"""
+
+import pytest
+
+from opentelemetry.util.genai.types import (
+    InputMessage,
+    OutputMessage,
+    ToolCall,
+)
+
+
+class TestToolCallEnhancements:
+    """Test suite for Enhanced ToolCall Type Definition"""
+
+    def test_toolcall_backward_compatibility(self):
+        """Test backward compatibility as message part"""
+        tc = ToolCall(
+            name="get_weather",
+            arguments={"location": "Paris"},
+            id="call_123",
+        )
+        assert tc.name == "get_weather"
+        assert tc.arguments == {"location": "Paris"}
+        assert tc.id == "call_123"
+        assert tc.type == "tool_call"
+
+    def test_toolcall_in_message(self):
+        """Test ToolCall works as message part in InputMessage"""
+        tc = ToolCall(name="get_weather", arguments={"location": "Paris"})
+        msg = InputMessage(role="user", parts=[tc])
+        assert len(msg.parts) == 1
+        assert msg.parts[0] == tc
+
+    def test_toolcall_full_lifecycle(self):
+        """Test complete tool call lifecycle with all fields"""
+        # Start with tool call request
+        tc = ToolCall(
+            name="get_weather",
+            arguments={"location": "Paris", "units": "metric"},
+            id="call_abc123",
+            tool_type="function",
+            tool_description="Retrieves current weather for a location",
+        )
+
+        # Simulate successful execution - set result
+        tc.tool_result = {"temperature": 15, "condition": "cloudy"}
+
+        assert tc.name == "get_weather"
+        assert tc.tool_type == "function"
+        assert tc.tool_result is not None
+        assert tc.error_type is None
+
+        # Simulate failed execution - set error
+        tc_failed = ToolCall(
+            name="get_weather",
+            arguments={"location": "Invalid"},
+            id="call_xyz789",
+            tool_type="function",
+        )
+        tc_failed.error_type = "InvalidLocationError"
+
+        assert tc_failed.error_type == "InvalidLocationError"
+        assert tc_failed.tool_result is None
+
+    def test_toolcall_with_output_message(self):
+        """Test ToolCall in OutputMessage (backward compatibility)"""
+        tc = ToolCall(
+            name="get_weather",
+            arguments={"location": "Paris"},
+            id="call_123",
+        )
+        msg = OutputMessage(
+            role="assistant", parts=[tc], finish_reason="tool_calls"
+        )
+
+        assert len(msg.parts) == 1
+        assert msg.parts[0].name == "get_weather"
+        assert msg.finish_reason == "tool_calls"
+
+    def test_toolcall_field_values(self):
+        """Test that ToolCall fields can be set and retrieved correctly"""
+        tc = ToolCall(
+            name="get_weather",
+            id="call_123",
+            tool_type="function",
+            tool_description="Weather tool",
+            arguments={"location": "Paris"},
+            tool_result={"temp": 20},
+        )
+
+        # Verify all field values are set correctly
+        assert tc.name == "get_weather"
+        assert tc.id == "call_123"
+        assert tc.tool_type == "function"
+        assert tc.tool_description == "Weather tool"
+        assert tc.arguments == {"location": "Paris"}
+        assert tc.tool_result == {"temp": 20}
+        assert tc.error_type is None
+
+        # Verify these fields map to semantic convention attributes:
+        # - name -> gen_ai.tool.name
+        # - id -> gen_ai.tool.call.id
+        # - tool_type -> gen_ai.tool.type
+        # - tool_description -> gen_ai.tool.description
+        # - arguments -> gen_ai.tool.call.arguments (Opt-In)
+        # - tool_result -> gen_ai.tool.call.result (Opt-In)
+        # - error_type -> error.type
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])