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

If you supply a filters object to FunctionChoiceBehavior for an agent invocation, it must not be empty/falsy. An empty filters value is rejected because it carries no information — you either provide at least one recognized key (excluded_plugins, included_plugins, excluded_functions, included_functions) or omit filters to include all kernel functions.

Source

Thrown at python/semantic_kernel/agents/open_ai/assistant_thread_actions.py:900

            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: "OpenAIAssistantAgent",
        kernel: "Kernel",
        tools_override: "list[AssistantToolParam] | None" = None,
        function_choice_behavior: FunctionChoiceBehavior | None = None,

View on GitHub (pinned to c028a0c7dc)

Solutions

Provide at least one recognized filter key, e.g. filters={'included_functions': ['x']}.
If you want all kernel functions available, omit filters entirely (pass None / do not set it).
Validate the filters dict is non-empty before constructing the behavior in dynamic code.

Example fix

// before
fcb = FunctionChoiceBehavior.Auto(filters={})
await assistant.invoke(kernel=kernel, function_choice_behavior=fcb, thread_id=tid)

// after
fcb = FunctionChoiceBehavior.Auto()  # include all kernel functions
await assistant.invoke(kernel=kernel, function_choice_behavior=fcb, thread_id=tid)

Defensive patterns

Strategy: validation

Validate before calling

VALID = {"excluded_plugins", "included_plugins", "excluded_functions", "included_functions"}

def filters_ok(fcb) -> bool:
    return fcb is None or fcb.filters is None or (isinstance(fcb.filters, dict) and len(fcb.filters) > 0 and set(fcb.filters) <= VALID)

Type guard

VALID = {"excluded_plugins", "included_plugins", "excluded_functions", "included_functions"}

def is_valid_filters(fcb) -> bool:
    if fcb is None or getattr(fcb, 'filters', None) is None:
        return True
    f = fcb.filters
    return bool(f) and set(f) <= VALID

Prevention

Omit filters to include all functions, or supply at least one recognized key.
When building filters dynamically, assert non-empty before constructing the behavior.

When it happens

Trigger: Constructing FunctionChoiceBehavior.Auto(filters={}) (empty dict/None-valued filter object) and passing it to an assistant agent invoke / thread-action call.

Common situations: Programmatically building filters that end up empty after conditionally dropping keys; deserializing config that yields an empty filters map; misunderstanding that an empty filter means 'no restriction' rather than 'include nothing'.

Related errors

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