feat: refactor ToolCall to ToolCallRequest and enhance type definitions

Author: keith-decker

instrumentation-genai/opentelemetry-instrumentation-vertexai/src/opentelemetry/instrumentation/vertexai/utils.py

@@ -56,7 +56,7 @@
     FinishReason,
     MessagePart,
     Text,
-    ToolCall,
+    ToolCallRequest,
     ToolCallResponse,
 )
 from opentelemetry.util.genai.utils import get_content_capturing_mode
@@ -341,7 +341,7 @@ def convert_content_to_message_parts(
         elif "function_call" in part:
             part = part.function_call
             parts.append(
-                ToolCall(
+                ToolCallRequest(
                     id=f"{part.name}_{idx}",
                     name=part.name,
                     arguments=json_format.MessageToDict(

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

@@ -42,22 +42,30 @@ class ContentCapturingMode(Enum):
 
 
 @dataclass()
-class ToolCall:
-    """Represents a tool call with dual usage: message part and execution tracking.
+class ToolCallRequest:
+    """Represents a tool call requested by the model
 
-    This type serves two purposes as defined in OpenTelemetry semantic conventions:
+    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>`__.
+    """
+
+    arguments: Any
+    name: str
+    id: str | None
+    type: Literal["tool_call"] = "tool_call"
 
-    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
+@dataclass()
+class ToolCall(ToolCallRequest):
+    """Represents a tool call for execution tracking with spans and metrics.
+
+    This type extends ToolCallRequest with additional fields for tracking tool execution
+    per the execute_tool span semantic conventions.
+
+    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.
+    For simple message parts (tool calls requested by the model), consider using
+    ToolCallRequest instead to avoid unnecessary execution-tracking fields.
 
     Semantic convention attributes for execute_tool spans:
     - gen_ai.operation.name: "execute_tool" (Required)
@@ -70,17 +78,7 @@ class ToolCall:
     - error.type: Error type if operation failed (Conditionally Required)
     """
 
-    # Fields used for both message part and execution tracking:
-    # gen_ai.tool.name - Name of the tool
-    name: str
-    # 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):
+    # Execution-only fields (used for execute_tool spans):
     # 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
@@ -194,7 +192,15 @@ class GenericToolDefinition:
 ToolDefinition = Union[FunctionToolDefinition, GenericToolDefinition]
 
 MessagePart = Union[
-    Text, ToolCall, ToolCallResponse, Blob, File, Uri, Reasoning, Any
+    Text,
+    ToolCallRequest,
+    ToolCall,
+    ToolCallResponse,
+    Blob,
+    File,
+    Uri,
+    Reasoning,
+    Any,
 ]
 
 

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

@@ -12,114 +12,153 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Tests for Enhanced ToolCall Type Definition"""
+"""Tests for ToolCallRequest and ToolCall types"""
 
 import pytest
 
 from opentelemetry.util.genai.types import (
     InputMessage,
     OutputMessage,
     ToolCall,
+    ToolCallRequest,
 )
 
 
-def test_toolcall_backward_compatibility():
-    """Test backward compatibility as message part"""
-    tc = ToolCall(
+def test_toolcallrequest_basic():
+    """Test basic ToolCallRequest instantiation"""
+    tcr = ToolCallRequest(arguments=None, name="get_weather", id=None)
+    assert tcr.name == "get_weather"
+    assert tcr.type == "tool_call"
+    assert tcr.arguments is None
+    assert tcr.id is None
+
+
+def test_toolcallrequest_with_all_fields():
+    """Test ToolCallRequest with all fields"""
+    tcr = ToolCallRequest(
         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"
+    assert tcr.name == "get_weather"
+    assert tcr.arguments == {"location": "Paris"}
+    assert tcr.id == "call_123"
+    assert tcr.type == "tool_call"
 
 
-def test_toolcall_in_message():
-    """Test ToolCall works as message part in InputMessage"""
-    tc = ToolCall(name="get_weather", arguments={"location": "Paris"})
-    msg = InputMessage(role="user", parts=[tc])
+def test_toolcallrequest_in_message():
+    """Test ToolCallRequest works as message part"""
+    tcr = ToolCallRequest(
+        arguments={"location": "Paris"}, name="get_weather", id=None
+    )
+    msg = InputMessage(role="user", parts=[tcr])
     assert len(msg.parts) == 1
-    assert msg.parts[0] == tc
+    assert msg.parts[0] == tcr
+
+
+def test_toolcall_inherits_from_toolcallrequest():
+    """Test that ToolCall inherits from ToolCallRequest"""
+    tc = ToolCall(arguments=None, name="get_weather", id=None)
+    assert isinstance(tc, ToolCallRequest)
+    assert isinstance(tc, ToolCall)
+
 
+def test_toolcall_has_execution_fields():
+    """Test ToolCall has execution-only fields"""
+    tc = ToolCall(arguments=None, name="get_weather", id=None)
+    assert hasattr(tc, "tool_type")
+    assert hasattr(tc, "tool_description")
+    assert hasattr(tc, "tool_result")
+    assert hasattr(tc, "error_type")
 
-def test_toolcall_full_lifecycle():
-    """Test complete tool call lifecycle with all fields"""
-    # Start with tool call request
+
+def test_toolcall_execution_fields_default_none():
+    """Test ToolCall execution fields default to None"""
+    tc = ToolCall(arguments=None, name="get_weather", id=None)
+    assert tc.tool_type is None
+    assert tc.tool_description is None
+    assert tc.tool_result is None
+    assert tc.error_type is None
+
+
+def test_toolcall_with_execution_fields():
+    """Test ToolCall with execution fields set"""
     tc = ToolCall(
         name="get_weather",
-        arguments={"location": "Paris", "units": "metric"},
-        id="call_abc123",
+        arguments={"location": "Paris"},
+        id="call_123",
         tool_type="function",
-        tool_description="Retrieves current weather for a location",
+        tool_description="Get current weather",
+        tool_result={"temp": 20, "condition": "sunny"},
     )
-
-    # 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
+    assert tc.tool_description == "Get current weather"
+    assert tc.tool_result == {"temp": 20, "condition": "sunny"}
 
-    # Simulate failed execution - set error
-    tc_failed = ToolCall(
-        name="get_weather",
+
+def test_toolcall_with_error():
+    """Test ToolCall with error_type set"""
+    tc = ToolCall(
         arguments={"location": "Invalid"},
-        id="call_xyz789",
-        tool_type="function",
+        name="get_weather",
+        id=None,
+        error_type="InvalidLocationError",
     )
-    tc_failed.error_type = "InvalidLocationError"
-
-    assert tc_failed.error_type == "InvalidLocationError"
-    assert tc_failed.tool_result is None
+    assert tc.error_type == "InvalidLocationError"
+    assert tc.tool_result is None
 
 
-def test_toolcall_with_output_message():
-    """Test ToolCall in OutputMessage (backward compatibility)"""
+def test_toolcall_backward_compatibility():
+    """Test ToolCall still works as message part (backward compatibility)"""
     tc = ToolCall(
         name="get_weather",
         arguments={"location": "Paris"},
         id="call_123",
     )
-    msg = OutputMessage(
+    # Should work in messages
+    msg = InputMessage(role="user", parts=[tc])
+    assert len(msg.parts) == 1
+
+    # Should work in output messages
+    out_msg = OutputMessage(
         role="assistant", parts=[tc], finish_reason="tool_calls"
     )
+    assert len(out_msg.parts) == 1
 
-    assert len(msg.parts) == 1
-    assert msg.parts[0].name == "get_weather"
-    assert msg.finish_reason == "tool_calls"
 
+def test_toolcallrequest_no_execution_fields():
+    """Test that ToolCallRequest doesn't have execution fields"""
+    tcr = ToolCallRequest(arguments=None, name="get_weather", id=None)
+    # ToolCallRequest should only have message part fields
+    assert not hasattr(tcr, "tool_type")
+    assert not hasattr(tcr, "tool_description")
+    assert not hasattr(tcr, "tool_result")
+    assert not hasattr(tcr, "error_type")
 
-def test_toolcall_field_values():
-    """Test that ToolCall fields can be set and retrieved correctly"""
+
+def test_mixed_types_in_message():
+    """Test using both ToolCallRequest and ToolCall in messages"""
+    tcr = ToolCallRequest(arguments=None, name="simple_tool", id=None)
     tc = ToolCall(
-        name="get_weather",
-        id="call_123",
-        tool_type="function",
-        tool_description="Weather tool",
-        arguments={"location": "Paris"},
-        tool_result={"temp": 20},
+        arguments=None, name="complex_tool", id=None, tool_type="function"
     )
 
-    # 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
+    msg = InputMessage(role="user", parts=[tcr, tc])
+    assert len(msg.parts) == 2
+    assert isinstance(msg.parts[0], ToolCallRequest)
+    assert isinstance(msg.parts[1], ToolCall)
+    # ToolCall is also a ToolCallRequest
+    assert isinstance(msg.parts[1], ToolCallRequest)
+
+
+def test_toolcall_tool_type_values():
+    """Test valid tool_type values"""
+    for tool_type in ["function", "extension", "datastore"]:
+        tc = ToolCall(
+            arguments=None, name="test", id=None, tool_type=tool_type
+        )
+        assert tc.tool_type == tool_type
 
 
 if __name__ == "__main__":