Python: fix Google AI/Vertex AI crash on anyOf schema (#12442) (#13624)

### Motivation and Context

Closes #12442

When `ChatCompletionAgent` instances are used as plugins with
`GoogleAIChatCompletion`, the application crashes with:
```
ValueError: Unknown field for Schema: anyOf
```

**Root cause**: The Semantic Kernel JSON schema builder generates
`anyOf` for Union types (e.g. `str | list[str]` on the agent's
`messages` parameter) and type-as-array for Optional types (e.g.
`["string", "null"]`). Google AI's protobuf `Schema` does not support
these constructs.

### Description

Add `sanitize_schema_for_google_ai()` to `shared_utils.py` that
recursively rewrites unsupported schema constructs:

- `anyOf` / `oneOf` with a null variant → single type + `nullable: true`
- `anyOf` / `oneOf` without null → picks the first variant
- `type` as array (e.g. `["string", "null"]`) → single type + `nullable:
true`

Applied in both
`kernel_function_metadata_to_google_ai_function_call_format()` and
`kernel_function_metadata_to_vertex_ai_function_call_format()`.

### Contribution Checklist

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
- [x] The existing tests pass, and I have added 12 new regression tests
- [x] I didn't break any existing functionality

> [!NOTE]
> AI-assisted contribution: Claude helped with code review, test
generation, and formatting.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>

Author: 3 people

python/semantic_kernel/connectors/ai/google/google_ai/services/utils.py

@@ -13,6 +13,7 @@
 from semantic_kernel.connectors.ai.google.shared_utils import (
     FUNCTION_CHOICE_TYPE_TO_GOOGLE_FUNCTION_CALLING_MODE,
     GEMINI_FUNCTION_NAME_SEPARATOR,
+    sanitize_schema_for_google_ai,
 )
 from semantic_kernel.contents.chat_message_content import ChatMessageContent
 from semantic_kernel.contents.function_call_content import FunctionCallContent
@@ -147,16 +148,23 @@ def format_tool_message(message: ChatMessageContent) -> list[Part]:
 
 def kernel_function_metadata_to_google_ai_function_call_format(metadata: KernelFunctionMetadata) -> dict[str, Any]:
     """Convert the kernel function metadata to function calling format."""
+    parameters: dict[str, Any] | None = None
+    if metadata.parameters:
+        properties = {}
+        for param in metadata.parameters:
+            if param.name is None:
+                continue
+            prop_schema = sanitize_schema_for_google_ai(param.schema_data) if param.schema_data else param.schema_data
+            properties[param.name] = prop_schema
+        parameters = {
+            "type": "object",
+            "properties": properties,
+            "required": [p.name for p in metadata.parameters if p.is_required and p.name is not None],
+        }
     return {
         "name": metadata.custom_fully_qualified_name(GEMINI_FUNCTION_NAME_SEPARATOR),
         "description": metadata.description or "",
-        "parameters": {
-            "type": "object",
-            "properties": {param.name: param.schema_data for param in metadata.parameters},
-            "required": [p.name for p in metadata.parameters if p.is_required],
-        }
-        if metadata.parameters
-        else None,
+        "parameters": parameters,
     }
 
 

python/semantic_kernel/connectors/ai/google/shared_utils.py

@@ -1,6 +1,8 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import logging
+from copy import deepcopy
+from typing import Any
 
 from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceType
 from semantic_kernel.const import DEFAULT_FULLY_QUALIFIED_NAME_SEPARATOR
@@ -51,6 +53,64 @@ def format_gemini_function_name_to_kernel_function_fully_qualified_name(gemini_f
     return gemini_function_name
 
 
+def sanitize_schema_for_google_ai(schema: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Sanitize a JSON schema dict so it is compatible with Google AI / Vertex AI.
+
+    The Google AI protobuf ``Schema`` does not support ``anyOf``, ``oneOf``, or
+    ``allOf``.  It also does not accept ``type`` as an array (e.g.
+    ``["string", "null"]``).  This helper recursively rewrites those constructs
+    into the subset that Google AI understands, using ``nullable`` where
+    appropriate.
+    """
+    if schema is None:
+        return None
+
+    schema = deepcopy(schema)
+    return _sanitize_node(schema)
+
+
+def _sanitize_node(node: dict[str, Any]) -> dict[str, Any]:
+    """Recursively sanitize a single schema node."""
+    # --- handle ``type`` given as a list (e.g. ["string", "null"]) ---
+    type_val = node.get("type")
+    if isinstance(type_val, list):
+        non_null = [t for t in type_val if t != "null"]
+        if len(type_val) != len(non_null):
+            node["nullable"] = True
+        node["type"] = non_null[0] if non_null else "string"
+
+    # --- handle ``anyOf`` / ``oneOf`` / ``allOf`` ---
+    for key in ("anyOf", "oneOf", "allOf"):
+        variants = node.get(key)
+        if not variants:
+            continue
+        non_null = [v for v in variants if v.get("type") != "null"]
+        has_null = len(variants) != len(non_null)
+        chosen = _sanitize_node(non_null[0]) if non_null else {"type": "string"}
+        # Preserve description from the outer node
+        desc = node.get("description")
+        node.clear()
+        node.update(chosen)
+        if has_null:
+            node["nullable"] = True
+        if desc and "description" not in node:
+            node["description"] = desc
+        break  # only process the first matching key
+
+    # --- recurse into nested structures ---
+    props = node.get("properties")
+    if isinstance(props, dict):
+        for prop_name, prop_schema in props.items():
+            if isinstance(prop_schema, dict):
+                props[prop_name] = _sanitize_node(prop_schema)
+
+    items = node.get("items")
+    if isinstance(items, dict):
+        node["items"] = _sanitize_node(items)
+
+    return node
+
+
 def collapse_function_call_results_in_chat_history(chat_history: ChatHistory):
     """The Gemini API expects the results of parallel function calls to be contained in a single message to be returned.
 

python/semantic_kernel/connectors/ai/google/vertex_ai/services/utils.py

@@ -11,6 +11,7 @@
 from semantic_kernel.connectors.ai.google.shared_utils import (
     FUNCTION_CHOICE_TYPE_TO_GOOGLE_FUNCTION_CALLING_MODE,
     GEMINI_FUNCTION_NAME_SEPARATOR,
+    sanitize_schema_for_google_ai,
 )
 from semantic_kernel.connectors.ai.google.vertex_ai.vertex_ai_prompt_execution_settings import (
     VertexAIChatPromptExecutionSettings,
@@ -137,13 +138,20 @@ def format_tool_message(message: ChatMessageContent) -> list[Part]:
 
 def kernel_function_metadata_to_vertex_ai_function_call_format(metadata: KernelFunctionMetadata) -> FunctionDeclaration:
     """Convert the kernel function metadata to function calling format."""
+    properties: dict[str, Any] = {}
+    if metadata.parameters:
+        for param in metadata.parameters:
+            if param.name is None:
+                continue
+            prop_schema = sanitize_schema_for_google_ai(param.schema_data) if param.schema_data else param.schema_data
+            properties[param.name] = prop_schema
     return FunctionDeclaration(
         name=metadata.custom_fully_qualified_name(GEMINI_FUNCTION_NAME_SEPARATOR),
         description=metadata.description or "",
         parameters={
             "type": "object",
-            "properties": {param.name: param.schema_data for param in metadata.parameters},
-            "required": [p.name for p in metadata.parameters if p.is_required],
+            "properties": properties,
+            "required": [p.name for p in metadata.parameters if p.is_required and p.name is not None],
         },
     )
 

python/tests/unit/connectors/ai/google/google_ai/services/test_google_ai_utils.py

@@ -7,6 +7,7 @@
     finish_reason_from_google_ai_to_semantic_kernel,
     format_assistant_message,
     format_user_message,
+    kernel_function_metadata_to_google_ai_function_call_format,
 )
 from semantic_kernel.contents.chat_message_content import ChatMessageContent
 from semantic_kernel.contents.function_call_content import FunctionCallContent
@@ -16,6 +17,8 @@
 from semantic_kernel.contents.utils.author_role import AuthorRole
 from semantic_kernel.contents.utils.finish_reason import FinishReason as SemanticKernelFinishReason
 from semantic_kernel.exceptions.service_exceptions import ServiceInvalidRequestError
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.functions.kernel_parameter_metadata import KernelParameterMetadata
 
 
 def test_finish_reason_from_google_ai_to_semantic_kernel():
@@ -157,3 +160,42 @@ def test_format_assistant_message_without_thought_signature() -> None:
     assert formatted[0].function_call.name == "test_function"
     assert formatted[0].function_call.args == {"arg1": "value1"}
     assert not getattr(formatted[0], "thought_signature", None)
+
+
+def test_google_ai_function_call_format_sanitizes_anyof_schema() -> None:
+    """Integration test: anyOf in param schema_data is sanitized in the output dict."""
+    metadata = KernelFunctionMetadata(
+        name="test_func",
+        description="A test function",
+        is_prompt=False,
+        parameters=[
+            KernelParameterMetadata(
+                name="messages",
+                description="The user messages",
+                is_required=True,
+                schema_data={
+                    "anyOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}},
+                    ],
+                    "description": "The user messages",
+                },
+            ),
+        ],
+    )
+    result = kernel_function_metadata_to_google_ai_function_call_format(metadata)
+    param_schema = result["parameters"]["properties"]["messages"]
+    assert "anyOf" not in param_schema
+    assert param_schema["type"] == "string"
+
+
+def test_google_ai_function_call_format_empty_parameters() -> None:
+    """Integration test: metadata with no parameters produces parameters=None."""
+    metadata = KernelFunctionMetadata(
+        name="no_params_func",
+        description="No parameters",
+        is_prompt=False,
+        parameters=[],
+    )
+    result = kernel_function_metadata_to_google_ai_function_call_format(metadata)
+    assert result["parameters"] is None

python/tests/unit/connectors/ai/google/test_shared_utils.py

@@ -10,6 +10,7 @@
     collapse_function_call_results_in_chat_history,
     filter_system_message,
     format_gemini_function_name_to_kernel_function_fully_qualified_name,
+    sanitize_schema_for_google_ai,
 )
 from semantic_kernel.contents.chat_history import ChatHistory
 from semantic_kernel.contents.chat_message_content import ChatMessageContent
@@ -94,3 +95,174 @@ def test_collapse_function_call_results_in_chat_history() -> None:
     collapse_function_call_results_in_chat_history(chat_history)
     assert len(chat_history.messages) == 7
     assert len(chat_history.messages[1].items) == 2
+
+
+# --- sanitize_schema_for_google_ai tests ---
+
+
+def test_sanitize_schema_none():
+    """Test that None input returns None."""
+    assert sanitize_schema_for_google_ai(None) is None
+
+
+def test_sanitize_schema_simple_passthrough():
+    """Test that a simple schema passes through unchanged."""
+    schema = {"type": "string", "description": "A name"}
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "string", "description": "A name"}
+
+
+def test_sanitize_schema_type_as_list_with_null():
+    """type: ["string", "null"] should become type: "string" + nullable: true."""
+    schema = {"type": ["string", "null"], "description": "Optional field"}
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "string", "nullable": True, "description": "Optional field"}
+
+
+def test_sanitize_schema_type_as_list_without_null():
+    """type: ["string", "integer"] should pick the first type."""
+    schema = {"type": ["string", "integer"]}
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "string"}
+
+
+def test_sanitize_schema_anyof_with_null():
+    """AnyOf with null variant should become the non-null type + nullable."""
+    schema = {
+        "anyOf": [{"type": "string"}, {"type": "null"}],
+        "description": "Optional param",
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "string", "nullable": True, "description": "Optional param"}
+
+
+def test_sanitize_schema_anyof_without_null():
+    """AnyOf without null should pick the first variant."""
+    schema = {
+        "anyOf": [
+            {"type": "string"},
+            {"type": "array", "items": {"type": "string"}},
+        ],
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "string"}
+
+
+def test_sanitize_schema_oneof():
+    """OneOf should be handled the same as anyOf."""
+    schema = {
+        "oneOf": [{"type": "integer"}, {"type": "null"}],
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "integer", "nullable": True}
+
+
+def test_sanitize_schema_nested_properties():
+    """AnyOf inside nested properties should be sanitized recursively."""
+    schema = {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "value": {"anyOf": [{"type": "number"}, {"type": "null"}]},
+        },
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "value": {"type": "number", "nullable": True},
+        },
+    }
+
+
+def test_sanitize_schema_nested_items():
+    """AnyOf inside array items should be sanitized recursively."""
+    schema = {
+        "type": "array",
+        "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]},
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {
+        "type": "array",
+        "items": {"type": "string"},
+    }
+
+
+def test_sanitize_schema_does_not_mutate_original():
+    """The original schema dict should not be modified."""
+    schema = {
+        "anyOf": [{"type": "string"}, {"type": "null"}],
+        "description": "test",
+    }
+    original = {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "test"}
+    sanitize_schema_for_google_ai(schema)
+    assert schema == original
+
+
+def test_sanitize_schema_agent_messages_param():
+    """Reproducer for issue #12442: str | list[str] parameter schema."""
+    schema = {
+        "anyOf": [
+            {"type": "string"},
+            {"type": "array", "items": {"type": "string"}},
+        ],
+        "description": "The user messages for the agent.",
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert "anyOf" not in result
+    assert result["type"] == "string"
+    assert result["description"] == "The user messages for the agent."
+
+
+def test_sanitize_schema_allof():
+    """AllOf should be handled like anyOf/oneOf, picking the first variant."""
+    schema = {
+        "allOf": [
+            {"type": "object", "properties": {"name": {"type": "string"}}},
+            {"type": "object", "properties": {"age": {"type": "integer"}}},
+        ],
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert "allOf" not in result
+    assert result["type"] == "object"
+    assert "name" in result["properties"]
+
+
+def test_sanitize_schema_allof_with_null():
+    """AllOf with a null variant should produce nullable: true."""
+    schema = {
+        "allOf": [{"type": "string"}, {"type": "null"}],
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert "allOf" not in result
+    assert result["type"] == "string"
+    assert result["nullable"] is True
+
+
+def test_sanitize_schema_all_null_type_list():
+    """type: ["null"] should fall back to type: "string" + nullable: true."""
+    schema = {"type": ["null"]}
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "string", "nullable": True}
+
+
+def test_sanitize_schema_all_null_anyof():
+    """AnyOf where all variants are null should fall back to type: "string"."""
+    schema = {"anyOf": [{"type": "null"}]}
+    result = sanitize_schema_for_google_ai(schema)
+    assert result == {"type": "string", "nullable": True}
+
+
+def test_sanitize_schema_chosen_variant_keeps_own_description():
+    """When the chosen anyOf variant has its own description, do not overwrite it."""
+    schema = {
+        "anyOf": [
+            {"type": "string", "description": "inner desc"},
+            {"type": "null"},
+        ],
+        "description": "outer desc",
+    }
+    result = sanitize_schema_for_google_ai(schema)
+    assert result["description"] == "inner desc"
+    assert result["nullable"] is True