fix(vertexai): normalize content message roles

Author: shuwpan

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

@@ -24,7 +24,8 @@
 
 from opentelemetry.instrumentation.vertexai.utils import (
     GenerateContentParams,
-    _map_finish_reason,
+    convert_candidate_to_output_message,
+    convert_content_to_input_message,
     convert_content_to_message_parts,
     extract_tool_definitions,
     get_genai_request_attributes,
@@ -125,12 +126,7 @@ def _build_invocation(
             )
         if params.contents:
             for c in params.contents:
-                input_messages.append(
-                    InputMessage(
-                        role=c.role or "user",
-                        parts=convert_content_to_message_parts(c),
-                    )
-                )
+                input_messages.append(convert_content_to_input_message(c))
 
     # Tool definitions are request metadata, not message content.
     request_functions = extract_tool_definitions(params.tools)
@@ -206,19 +202,13 @@ 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)
-        parts = []
-        if capture_content:
-            parts = convert_content_to_message_parts(candidate.content)
-        finish_reasons.append(fr)
-        output_messages.append(
-            OutputMessage(
-                role=getattr(candidate.content, "role", None) or "model",
-                parts=parts,
-                finish_reason=fr,
-            )
+        output_message = convert_candidate_to_output_message(
+            candidate,
+            capture_content=capture_content,
         )
+        fr = output_message.finish_reason
+        finish_reasons.append(fr)
+        output_messages.append(output_message)
 
     invocation.response_finish_reasons = finish_reasons
     invocation.output_messages = output_messages

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

@@ -36,7 +36,9 @@
 from opentelemetry.util.genai.types import (
     ContentCapturingMode,
     FinishReason,
+    InputMessage,
     MessagePart,
+    OutputMessage,
     Text,
     ToolCall,
     ToolCallResponse,
@@ -219,6 +221,53 @@ def convert_content_to_message_parts(
     return parts
 
 
+def convert_content_to_input_message(
+    content: content.Content | content_v1beta1.Content,
+) -> InputMessage:
+    """Convert Vertex AI Content proto to a normalized util-genai InputMessage."""
+    parts = convert_content_to_message_parts(content)
+    return InputMessage(
+        role=_normalize_content_role(getattr(content, "role", None), parts),
+        parts=parts,
+    )
+
+
+def convert_candidate_to_output_message(
+    candidate: content.Candidate | content_v1beta1.Candidate,
+    *,
+    capture_content: bool,
+) -> OutputMessage:
+    """Convert a Vertex AI candidate to a normalized util-genai OutputMessage."""
+    parts = (
+        convert_content_to_message_parts(candidate.content)
+        if capture_content
+        else []
+    )
+    return OutputMessage(
+        role=_normalize_content_role(
+            getattr(candidate.content, "role", None), parts
+        ),
+        parts=parts,
+        finish_reason=_map_finish_reason(candidate.finish_reason),
+    )
+
+
+def _normalize_content_role(
+    role: str | None,
+    parts: Sequence[MessagePart],
+) -> str:
+    """Map Vertex AI provider roles to OTel GenAI message roles."""
+    if role == "model":
+        return "assistant"
+    if (
+        role == "user"
+        and parts
+        and all(isinstance(part, ToolCallResponse) for part in parts)
+    ):
+        return "tool"
+    return role or "user"
+
+
 def _map_finish_reason(
     finish_reason: content.Candidate.FinishReason
     | content_v1beta1.Candidate.FinishReason

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

@@ -86,7 +86,7 @@ def test_generate_content(
     output_msgs = json.loads(attrs["gen_ai.output.messages"])
     assert output_msgs == [
         {
-            "role": "model",
+            "role": "assistant",
             "parts": [{"type": "text", "content": "This is a test."}],
             "finish_reason": "stop",
         }
@@ -104,7 +104,7 @@ def test_generate_content(
     ]
     assert body["gen_ai.output.messages"] == [
         {
-            "role": "model",
+            "role": "assistant",
             "parts": [{"type": "text", "content": "This is a test."}],
             "finish_reason": "stop",
         }
@@ -384,7 +384,7 @@ def generate_content_all_input_messages(
     assert input_msgs[0]["parts"] == [
         {"type": "text", "content": "My name is OpenTelemetry"}
     ]
-    assert input_msgs[1]["role"] == "model"
+    assert input_msgs[1]["role"] == "assistant"
     assert input_msgs[1]["parts"] == [
         {"type": "text", "content": "Hello OpenTelemetry!"}
     ]
@@ -400,7 +400,7 @@ def generate_content_all_input_messages(
     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]["role"] == "assistant"
     assert output_msgs[0]["parts"] == [
         {"type": "text", "content": "OpenTelemetry, this is a test."}
     ]

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

@@ -76,7 +76,7 @@ def test_function_call_choice(
     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]["role"] == "assistant"
     assert output_msgs[0]["finish_reason"] == "stop"
     assert len(output_msgs[0]["parts"]) == 2
     assert output_msgs[0]["parts"][0]["type"] == "tool_call"
@@ -163,7 +163,7 @@ def test_tool_events(
     )
     assert "gen_ai.request.function.0.parameters" in attrs
 
-    # Content on span: user text, model function_call, user tool responses, model text response
+    # Content on span: user text, assistant function_call, tool responses, assistant text response
     assert "gen_ai.input.messages" in attrs
     input_msgs = json.loads(attrs["gen_ai.input.messages"])
     assert len(input_msgs) == 3
@@ -175,8 +175,8 @@ def test_tool_events(
             "content": "Get weather details in New Delhi and San Francisco?",
         }
     ]
-    # Second message: model with function_call parts now mapped to ToolCall
-    assert input_msgs[1]["role"] == "model"
+    # Second message: assistant with function_call parts now mapped to ToolCall
+    assert input_msgs[1]["role"] == "assistant"
     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"
@@ -186,8 +186,8 @@ def test_tool_events(
     assert input_msgs[1]["parts"][1]["arguments"] == {
         "location": "San Francisco"
     }
-    # Third message: user with tool call responses
-    assert input_msgs[2]["role"] == "user"
+    # Third message: tool with tool call responses
+    assert input_msgs[2]["role"] == "tool"
     assert len(input_msgs[2]["parts"]) == 2
     assert input_msgs[2]["parts"][0]["type"] == "tool_call_response"
     assert input_msgs[2]["parts"][1]["type"] == "tool_call_response"
@@ -196,7 +196,7 @@ def test_tool_events(
     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]["role"] == "assistant"
     assert output_msgs[0]["finish_reason"] == "stop"
     assert len(output_msgs[0]["parts"]) == 1
     assert output_msgs[0]["parts"][0]["type"] == "text"

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

@@ -23,6 +23,7 @@
 
 from opentelemetry.instrumentation.vertexai.utils import (
     _map_finish_reason,
+    convert_content_to_input_message,
     convert_content_to_message_parts,
     extract_tool_definitions,
     get_server_attributes,
@@ -126,6 +127,33 @@ def test_convert_content_mixed_parts():
     assert parts[2].response == {"answer": "world"}
 
 
+def test_convert_content_to_input_message_normalizes_roles():
+    model_content = content.Content(
+        {
+            "role": "model",
+            "parts": [{"text": "hello"}],
+        }
+    )
+    model_message = convert_content_to_input_message(model_content)
+    assert model_message.role == "assistant"
+
+    tool_content = content.Content(
+        {
+            "role": "user",
+            "parts": [
+                {
+                    "function_response": {
+                        "name": "search",
+                        "response": {"answer": "world"},
+                    }
+                }
+            ],
+        }
+    )
+    tool_message = convert_content_to_input_message(tool_content)
+    assert tool_message.role == "tool"
+
+
 def test_extract_tool_definitions():
     """extract_tool_definitions converts Tool protos to dicts."""
     t = tool.Tool(