feat(vertexai): add function calling support via ToolCall and ToolCallResponse

- Map function_call parts to ToolCall, function_response to ToolCallResponse
- Populate request_functions from tool definitions (always, independent of content capture)
- Add tests for function call spans, tool events, and request function attributes

Author: shuwpan

instrumentation-genai/opentelemetry-instrumentation-vertexai/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Migrate to `TelemetryHandler` from `opentelemetry-util-genai`
 - Remove `_StabilityMode` branching, `events.py`, and experimental test files
+- Add function calling support via util-genai `ToolCall` and `ToolCallResponse` types
 
 ## Version 2.2b0 (2025-12-19)
 - Fix overwritten log attributes in vertexai instrumentation

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

@@ -25,6 +25,7 @@
     GenerateContentParams,
     _map_finish_reason,
     convert_content_to_message_parts,
+    extract_tool_definitions,
     get_genai_request_attributes,
     get_server_attributes,
 )
@@ -129,6 +130,9 @@ def _build_invocation(
                     )
                 )
 
+    # Tool definitions are request metadata, not message content.
+    request_functions = extract_tool_definitions(params.tools)
+
     invocation = LLMInvocation(
         request_model=request_attributes.get(
             GenAIAttributes.GEN_AI_REQUEST_MODEL, ""
@@ -161,6 +165,7 @@ def _build_invocation(
         request_seed=request_attributes.get(
             GenAIAttributes.GEN_AI_REQUEST_SEED
         ),
+        request_functions=request_functions,
     )
 
     # Propagate extra attributes that don't map to LLMInvocation fields
@@ -200,14 +205,15 @@ def _apply_response_to_invocation(
     finish_reasons = []
     output_messages: list[OutputMessage] = []
     for candidate in response.candidates:
+        # Vertex AI has no TOOL_CALLS finish reason; STOP is returned even for function calls.
         fr = _map_finish_reason(candidate.finish_reason)
-        finish_reasons.append(fr)
         parts = []
         if capture_content:
             parts = convert_content_to_message_parts(candidate.content)
+        finish_reasons.append(fr)
         output_messages.append(
             OutputMessage(
-                role=candidate.content.role or "model",
+                role=getattr(candidate.content, "role", None) or "model",
                 parts=parts,
                 finish_reason=fr,
             )

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

@@ -21,6 +21,7 @@
 from dataclasses import dataclass
 from typing import (
     TYPE_CHECKING,
+    Any,
     Mapping,
     Sequence,
 )
@@ -37,6 +38,7 @@
     FinishReason,
     MessagePart,
     Text,
+    ToolCall,
     ToolCallResponse,
 )
 from opentelemetry.util.genai.utils import get_content_capturing_mode
@@ -175,24 +177,32 @@ def convert_content_to_message_parts(
 ) -> list[MessagePart]:
     """Convert Vertex AI Content proto to a list of util-genai MessagePart objects.
 
-    Only Text and ToolCallResponse parts are supported in this version.
-    Unsupported part types (inline_data, file_data, function_call) are
-    skipped until the corresponding util-genai types are available (HYBIM-604).
+    Maps Vertex AI part types to util-genai equivalents:
+      function_call → ToolCall, function_response → ToolCallResponse, text → Text.
+    Unsupported types (inline_data, file_data) are skipped (HYBIM-604).
+
+    Note: ``._pb`` is used to access the underlying protobuf message because
+    proto-plus wrappers don't support direct ``MessageToDict`` conversion.
     """
     parts: list[MessagePart] = []
     for idx, part in enumerate(content.parts):
         if "function_response" in part:
             part = part.function_response
             parts.append(
                 ToolCallResponse(
-                    id=f"{part.name}_{idx}",
+                    id=f"{part.name}_{idx}",  # synthetic (Vertex AI has no call id)
                     response=json_format.MessageToDict(part._pb.response),  # type: ignore[reportUnknownMemberType]
                 )
             )
         elif "function_call" in part:
-            # ToolCallRequest not yet in util-genai (HYBIM-604) — skip
-            logging.debug(
-                "function_call part skipped (ToolCallRequest not yet supported)"
+            fc = part.function_call
+            args = json_format.MessageToDict(fc._pb.args) if fc.args else {}  # type: ignore[reportUnknownMemberType]
+            parts.append(
+                ToolCall(
+                    name=fc.name,
+                    arguments=args,
+                    id=f"{fc.name}_{idx}",  # synthetic (Vertex AI has no call id)
+                )
             )
         elif "text" in part:
             parts.append(Text(content=part.text))
@@ -227,3 +237,31 @@ def _map_finish_reason(
 
     # If there is no 1:1 mapping to an OTel preferred enum value, use the exact vertex reason
     return finish_reason.name
+
+
+def extract_tool_definitions(
+    tools: Sequence[tool.Tool] | Sequence[tool_v1beta1.Tool] | None,
+) -> list[dict[str, Any]]:
+    """Extract function declarations from Vertex AI Tools into a list of dicts.
+
+    Each dict has keys: name, description, parameters (matching the format
+    used by LLMInvocation.request_functions).
+
+    Note: Only ``function_declarations`` are extracted.  Other tool types
+    (Google Search, retrieval, code execution) do not carry function
+    metadata and are silently skipped.
+    """
+    if not tools:
+        return []
+    result: list[dict] = []
+    for t in tools:
+        for fd in t.function_declarations:
+            entry: dict = {"name": fd.name}
+            if fd.description:
+                entry["description"] = fd.description
+            if fd.parameters:
+                entry["parameters"] = json_format.MessageToDict(
+                    fd.parameters._pb
+                )  # type: ignore[reportUnknownMemberType]
+            result.append(entry)
+    return result

instrumentation-genai/opentelemetry-instrumentation-vertexai/tests/test_function_calling.py

@@ -63,6 +63,14 @@ def test_function_call_choice(
     assert attrs["server.address"] == "us-central1-aiplatform.googleapis.com"
     assert attrs["server.port"] == 443
 
+    # Tool definitions are always emitted (independent of content capture)
+    assert attrs["gen_ai.request.function.0.name"] == "get_current_weather"
+    assert (
+        attrs["gen_ai.request.function.0.description"]
+        == "Get the current weather in a given location"
+    )
+    assert "gen_ai.request.function.0.parameters" in attrs
+
     # Content on span
     assert "gen_ai.input.messages" in attrs
     input_msgs = json.loads(attrs["gen_ai.input.messages"])
@@ -78,12 +86,21 @@ def test_function_call_choice(
         }
     ]
 
-    # Output messages on span - function_call parts are skipped (HYBIM-604)
+    # Output messages on span — function_call parts now appear as ToolCall
     assert "gen_ai.output.messages" in attrs
     output_msgs = json.loads(attrs["gen_ai.output.messages"])
     assert len(output_msgs) == 1
     assert output_msgs[0]["role"] == "model"
     assert output_msgs[0]["finish_reason"] == "stop"
+    assert len(output_msgs[0]["parts"]) == 2
+    assert output_msgs[0]["parts"][0]["type"] == "tool_call"
+    assert output_msgs[0]["parts"][0]["name"] == "get_current_weather"
+    assert output_msgs[0]["parts"][0]["arguments"] == {"location": "New Delhi"}
+    assert output_msgs[0]["parts"][1]["type"] == "tool_call"
+    assert output_msgs[0]["parts"][1]["name"] == "get_current_weather"
+    assert output_msgs[0]["parts"][1]["arguments"] == {
+        "location": "San Francisco"
+    }
 
     # Content events emitter emits a single event
     logs = log_exporter.get_finished_logs()
@@ -108,7 +125,17 @@ def test_function_call_choice_no_content(
     attrs = dict(spans[0].attributes)
     assert attrs["gen_ai.operation.name"] == "chat"
     assert attrs["gen_ai.request.model"] == "gemini-2.5-pro"
+    assert attrs["gen_ai.response.finish_reasons"] == ("stop",)
     assert attrs["gen_ai.provider.name"] == "vertex_ai"
+
+    # Tool definitions are always emitted (independent of content capture)
+    assert attrs["gen_ai.request.function.0.name"] == "get_current_weather"
+    assert (
+        attrs["gen_ai.request.function.0.description"]
+        == "Get the current weather in a given location"
+    )
+    assert "gen_ai.request.function.0.parameters" in attrs
+
     assert "gen_ai.input.messages" not in attrs
     assert "gen_ai.output.messages" not in attrs
 
@@ -142,7 +169,15 @@ def test_tool_events(
     assert attrs["server.address"] == "us-central1-aiplatform.googleapis.com"
     assert attrs["server.port"] == 443
 
-    # Content on span: user text, model function_call (skipped), user tool responses, model text response
+    # Tool definitions are always emitted
+    assert attrs["gen_ai.request.function.0.name"] == "get_current_weather"
+    assert (
+        attrs["gen_ai.request.function.0.description"]
+        == "Get the current weather in a given location"
+    )
+    assert "gen_ai.request.function.0.parameters" in attrs
+
+    # Content on span: user text, model function_call, user tool responses, model text response
     assert "gen_ai.input.messages" in attrs
     input_msgs = json.loads(attrs["gen_ai.input.messages"])
     assert len(input_msgs) == 3
@@ -154,9 +189,17 @@ def test_tool_events(
             "content": "Get weather details in New Delhi and San Francisco?",
         }
     ]
-    # Second message: model with function_call parts (skipped by convert_content_to_message_parts)
+    # Second message: model with function_call parts now mapped to ToolCall
     assert input_msgs[1]["role"] == "model"
-    assert input_msgs[1]["parts"] == []
+    assert len(input_msgs[1]["parts"]) == 2
+    assert input_msgs[1]["parts"][0]["type"] == "tool_call"
+    assert input_msgs[1]["parts"][0]["name"] == "get_current_weather"
+    assert input_msgs[1]["parts"][0]["arguments"] == {"location": "New Delhi"}
+    assert input_msgs[1]["parts"][1]["type"] == "tool_call"
+    assert input_msgs[1]["parts"][1]["name"] == "get_current_weather"
+    assert input_msgs[1]["parts"][1]["arguments"] == {
+        "location": "San Francisco"
+    }
     # Third message: user with tool call responses
     assert input_msgs[2]["role"] == "user"
     assert len(input_msgs[2]["parts"]) == 2
@@ -202,6 +245,17 @@ def test_tool_events_no_content(
     assert attrs["gen_ai.usage.output_tokens"] == 22
     assert attrs["server.address"] == "us-central1-aiplatform.googleapis.com"
     assert attrs["server.port"] == 443
+
+    # Tool definitions are always emitted (independent of content capture)
+    assert attrs["gen_ai.request.function.0.name"] == "get_current_weather"
+    assert (
+        attrs["gen_ai.request.function.0.description"]
+        == "Get the current weather in a given location"
+    )
+    assert "gen_ai.request.function.0.parameters" in attrs
+
+    # finish_reason stays "stop" because the *response* is a final text
+    # answer (no function_call parts in the response candidates)
     assert "gen_ai.input.messages" not in attrs
     assert "gen_ai.output.messages" not in attrs
 

instrumentation-genai/opentelemetry-instrumentation-vertexai/tests/test_utils.py

@@ -15,13 +15,16 @@
 
 from google.cloud.aiplatform_v1.types import (
     content,
+    tool,
 )
 from google.cloud.aiplatform_v1beta1.types import (
     content as content_v1beta1,
 )
 
 from opentelemetry.instrumentation.vertexai.utils import (
     _map_finish_reason,
+    convert_content_to_message_parts,
+    extract_tool_definitions,
     get_server_attributes,
 )
 
@@ -62,3 +65,95 @@ def test_map_finish_reason():
             (Enum.SPII, "SPII"),
         ]:
             assert _map_finish_reason(finish_reason) == expect
+
+
+def test_convert_content_function_call():
+    """function_call parts are mapped to ToolCall message parts."""
+    c = content.Content(
+        {
+            "role": "model",
+            "parts": [
+                {
+                    "function_call": {
+                        "name": "get_weather",
+                        "args": {"location": "New Delhi"},
+                    }
+                }
+            ],
+        }
+    )
+    parts = convert_content_to_message_parts(c)
+    assert len(parts) == 1
+    tc = parts[0]
+    assert tc.type == "tool_call"
+    assert tc.name == "get_weather"
+    assert tc.arguments == {"location": "New Delhi"}
+    assert tc.id == "get_weather_0"
+
+
+def test_convert_content_mixed_parts():
+    """Text, function_call, and function_response parts are all mapped."""
+    c = content.Content(
+        {
+            "role": "model",
+            "parts": [
+                {"text": "intro"},
+                {
+                    "function_call": {
+                        "name": "search",
+                        "args": {"q": "hello"},
+                    }
+                },
+                {
+                    "function_response": {
+                        "name": "search",
+                        "response": {"answer": "world"},
+                    }
+                },
+            ],
+        }
+    )
+    parts = convert_content_to_message_parts(c)
+    assert len(parts) == 3
+    assert parts[0].type == "text"
+    assert parts[0].content == "intro"
+    assert parts[1].type == "tool_call"
+    assert parts[1].name == "search"
+    assert parts[2].type == "tool_call_response"
+    assert parts[2].response == {"answer": "world"}
+
+
+def test_extract_tool_definitions():
+    """extract_tool_definitions converts Tool protos to dicts."""
+    t = tool.Tool(
+        {
+            "function_declarations": [
+                {
+                    "name": "get_weather",
+                    "description": "Get weather",
+                    "parameters": {
+                        "type_": "OBJECT",
+                        "properties": {
+                            "loc": {"type_": "STRING"},
+                        },
+                    },
+                },
+                {
+                    "name": "get_time",
+                    "description": "Get time",
+                },
+            ]
+        }
+    )
+    result = extract_tool_definitions([t])
+    assert len(result) == 2
+    assert result[0]["name"] == "get_weather"
+    assert result[0]["description"] == "Get weather"
+    assert "properties" in result[0]["parameters"]
+    assert result[1]["name"] == "get_time"
+    assert result[1]["description"] == "Get time"
+
+
+def test_extract_tool_definitions_none():
+    """extract_tool_definitions returns empty list for None input."""
+    assert extract_tool_definitions(None) == []