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

Raised when FunctionChoiceBehavior.Auto.filters contains keys outside the allowed set {excluded_plugins, included_plugins, excluded_functions, included_functions}. Typo'd or version-mismatched filter keys are rejected before reaching the Azure service.

Source

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

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

        Args:
            agent: The agent instance.
            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

Rename unknown filter keys to the valid set shown in the error: included_plugins, excluded_plugins, included_functions, excluded_functions.
Use plural forms (plugins/functions) and the included_/excluded_ prefixes exactly.
Cross-check against the FunctionChoiceBehaviorFilters Pydantic model fields in the installed semantic_kernel version.

Example fix

// before
behavior = FunctionChoiceBehavior.Auto(
    filters={"include_functions": ["MyPlugin-MyFunc"]}
)

// after
behavior = FunctionChoiceBehavior.Auto(
    filters={"included_functions": ["MyPlugin-MyFunc"]}
)

Defensive patterns

Strategy: validation

Validate before calling

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

def validate_filter_keys(behavior) -> None:
    if behavior is None or behavior.filters is None:
        return
    bad = set(behavior.filters) - VALID_FILTER_KEYS
    if bad:
        raise ValueError(f"Unknown filter keys: {sorted(bad)}")

Type guard

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

def filters_use_valid_keys(b: object) -> bool:
    f = getattr(b, "filters", None)
    return f is None or set(map(str, f)).issubset(VALID_FILTER_KEYS)

Prevention

Keep a single constant set of valid filter keys and validate against it before agent invocation.
Document the four valid keys wherever filters are constructed in the codebase.

When it happens

Trigger: Passing a filters dict with keys like 'include_functions' (singular), 'plugin_filters', or any key not in the four recognized names.

Common situations: Developer copies filter key names from a different SDK version or from chat-completion samples that use a different vocabulary; the message lists the offending keys and valid keys.

Related errors

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