microsoft/semantic-kernel · error · AgentInvokeException

Unknown filter key(s): {sorted(unknown_keys)}. Valid filter

Error message

Unknown filter key(s): {sorted(unknown_keys)}. Valid filter keys are: {sorted(valid_filter_keys)}.

What it means

When filters is provided and non-empty, each key must be one of the recognized set {excluded_plugins, included_plugins, excluded_functions, included_functions}. Any other key is reported via AgentInvokeException listing the unknown keys and the valid set, to prevent silent typos that would quietly include all functions.

Source

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

                "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,
    ) -> list[dict[str, str]]:
        """Get the list of tools for the assistant.

        Args:
            agent: The assistant agent.
            kernel: The kernel to use for function metadata.
            tools_override: When provided, overrides agent.definition.tools (SDK-level tools only).

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Use only the valid keys: excluded_plugins, included_plugins, excluded_functions, included_functions.
2. Copy the exact key names from the error message's valid set to avoid typos.
3. If constructing filters dynamically, validate keys against the valid set before building the behavior.

Example fix

// before
fcb = FunctionChoiceBehavior.Auto(filters={'include_functions': ['math.add']})
await assistant.invoke(kernel=kernel, function_choice_behavior=fcb, thread_id=tid)

// after
fcb = FunctionChoiceBehavior.Auto(filters={'included_functions': ['math.add']})
await assistant.invoke(kernel=kernel, function_choice_behavior=fcb, thread_id=tid)

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

def filters_keys_valid(fcb) -> bool:
    if fcb is None or getattr(fcb, 'filters', None) is None:
        return True
    return set(map(str, fcb.filters)) <= VALID

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

def has_only_valid_filter_keys(fcb) -> bool:
    if fcb is None or getattr(fcb, 'filters', None) is None:
        return True
    return set(map(str, fcb.filters)) <= VALID

When it happens

Trigger: Passing filters with a misspelled or unsupported key, e.g. {'include_functions': [...]} (missing 'd'), {'plugins': [...]}, or a deprecated key name from an older API.

Common situations: Typos in filter keys; copy-paste from documentation/chats using a different key name; version differences where filter key names changed; dynamically constructing keys from user input without validation.

Related errors

• FunctionChoiceBehavior filters must not be empty. Provide at
• FunctionChoiceBehavior with type '{function_choice_behavior.
• FunctionChoiceBehavior.Auto(auto_invoke=False) is not suppor
• FunctionChoiceBehavior filters must not be empty. Provide at
• Invalid message role `{message.role.value}`. Allowed roles a

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