microsoft/semantic-kernel · error · AgentInvokeException

FunctionChoiceBehavior filters must not be empty. Provide at

Error message

FunctionChoiceBehavior filters must not be empty. Provide at least one filter key from {sorted(valid_filter_keys)}, or omit filters entirely to include all kernel functions.

What it means

Raised when FunctionChoiceBehavior.Auto is given a filters dict that is present but empty (e.g. {}). An empty filter object is almost certainly a mistake — it neither includes nor excludes anything and signals the developer forgot to populate it.

Source

Thrown at python/semantic_kernel/agents/azure_ai/agent_thread_actions.py:1010

            raise AgentInvokeException(
                f"FunctionChoiceBehavior with type '{function_choice_behavior.type_}' is not supported for agent "
                "invocations. Use FunctionChoiceBehavior.Auto(filters=...) to control which kernel functions "
                "are available."
            )
        if not function_choice_behavior.auto_invoke_kernel_functions:
            raise AgentInvokeException(
                "FunctionChoiceBehavior.Auto(auto_invoke=False) is not supported for agent invocations. "
                "The agent run loop manages tool invocation; disabling auto_invoke is not compatible."
            )
        valid_filter_keys: set[str] = {
            "excluded_plugins",
            "included_plugins",
            "excluded_functions",
            "included_functions",
        }
        if function_choice_behavior.filters is not None:
            if not function_choice_behavior.filters:
                raise AgentInvokeException(
                    "FunctionChoiceBehavior filters must not be empty. Provide at least one filter key "
                    f"from {sorted(valid_filter_keys)}, or omit filters entirely to include all "
                    "kernel functions."
                )
            unknown_keys = {str(k) for k in function_choice_behavior.filters} - valid_filter_keys
            if unknown_keys:
                raise AgentInvokeException(
                    f"Unknown filter key(s): {sorted(unknown_keys)}. "
                    f"Valid filter keys are: {sorted(valid_filter_keys)}."
                )

    @classmethod
    def _get_tools(
        cls: type[_T],
        agent: "AzureAIAgent",
        kernel: "Kernel",
        tools_override: list[ToolDefinition] | None = None,
        function_choice_behavior: FunctionChoiceBehavior | None = None,

View on GitHub (pinned to c028a0c7dc)

Solutions

Omit the filters argument entirely to include all kernel functions.
Populate at least one valid key: included_plugins, excluded_plugins, included_functions, or excluded_functions.

Example fix

// before
behavior = FunctionChoiceBehavior.Auto(filters={})

// after
# omit filters entirely to include all functions
behavior = FunctionChoiceBehavior.Auto()

Defensive patterns

Strategy: validation

Validate before calling

def sanitize_filters(behavior):
    if behavior is not None and behavior.filters is not None and not behavior.filters:
        behavior.filters = None  # omit to include all
    return behavior

Type guard

def has_nonempty_filters(b: object) -> bool:
    f = getattr(b, "filters", None)
    return f is None or len(f) > 0

Prevention

When building filters from config, set filters=None instead of {} when no keys apply.
Add a schema check (e.g. Pydantic validator) that empty dicts resolve to None.

When it happens

Trigger: Passing FunctionChoiceBehavior.Auto(filters={}) or an empty FunctionChoiceBehaviorFilters instance to an AzureAIAgent invocation.

Common situations: Developer builds filters dynamically from config and ends up with an empty dict when no keys are set; or copies a filter template without filling keys.

Related errors

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