microsoft/semantic-kernel · error · ServiceInvalidExecutionSettingsError

Auto-invocation of tool calls may only be used with a Vertex

Error message

Auto-invocation of tool calls may only be used with a VertexAIChatPromptExecutionSettings.candidate_count of 1.

What it means

Raised by VertexAIChatCompletion._verify_function_choice_settings when auto-invocation of tool calls is enabled and VertexAIChatPromptExecutionSettings.candidate_count is greater than 1. Auto-invocation requires a single deterministic candidate to drive the tool-call loop, so multiple candidates are incompatible and rejected.

Source

Thrown at python/semantic_kernel/connectors/ai/google/vertex_ai/services/vertex_ai_chat_completion.py:189

            contents=self._prepare_chat_history_for_request(chat_history),
            generation_config=settings.prepare_settings_dict(),
            tools=settings.tools,
            tool_config=settings.tool_config,
            stream=True,
        )

        async for chunk in response:
            yield [
                self._create_streaming_chat_message_content(chunk, candidate, function_invoke_attempt)
                for candidate in chunk.candidates
            ]

    @override
    def _verify_function_choice_settings(self, settings: "PromptExecutionSettings") -> None:
        if not isinstance(settings, VertexAIChatPromptExecutionSettings):
            raise ServiceInvalidExecutionSettingsError("The settings must be an VertexAIChatPromptExecutionSettings.")
        if settings.candidate_count is not None and settings.candidate_count > 1:
            raise ServiceInvalidExecutionSettingsError(
                "Auto-invocation of tool calls may only be used with a "
                "VertexAIChatPromptExecutionSettings.candidate_count of 1."
            )

    @override
    def _update_function_choice_settings_callback(
        self,
    ) -> Callable[["FunctionCallChoiceConfiguration", "PromptExecutionSettings", FunctionChoiceType], None]:
        return update_settings_from_function_choice_configuration

    @override
    def _reset_function_choice_settings(self, settings: "PromptExecutionSettings") -> None:
        if hasattr(settings, "tool_config"):
            settings.tool_config = None
        if hasattr(settings, "tools"):
            settings.tools = None

    @override

View on GitHub (pinned to c028a0c7dc)

Solutions

Set candidate_count to 1 (or leave it None) when using auto-invocation of tool calls.
If you need multiple candidates, disable auto-invocation (use manual function calling) instead of raising candidate_count.
Branch your settings: one configuration for multi-candidate sampling, another for tool auto-invocation.

Example fix

# before
settings = VertexAIChatPromptExecutionSettings(candidate_count=3)
settings.function_choice_behavior = FunctionChoiceBehavior.Auto()
# after
settings = VertexAIChatPromptExecutionSettings(candidate_count=1)
settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

Defensive patterns

Strategy: validation

Validate before calling

if getattr(settings, 'function_choice_behavior', None) and getattr(settings, 'candidate_count', None) and settings.candidate_count > 1:
    raise ValueError('Set candidate_count=1 when using tool auto-invocation')

Prevention

Treat candidate_count>1 and auto-invocation as mutually exclusive.
Default candidate_count to None/1 unless you specifically need multiple samples.
Add a config assertion before invoking the completion call.

When it happens

Trigger: Configuring FunctionChoiceBehavior with auto-invocation while setting candidate_count > 1 on VertexAIChatPromptExecutionSettings.

Common situations: Wanting several sample completions (candidate_count=n) and enabling automatic function calling at the same time. Carrying over an OpenAI n>1 setting to Vertex AI.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/ae0a3f8154e054e2. Report an issue: GitHub.