{"record":{"id":"4801cc2fcc88cc9f","repo":"microsoft/semantic-kernel","slug":"unknown-filter-key-s-sorted-unknown-keys-val","errorCode":null,"errorMessage":"Unknown filter key(s): {sorted(unknown_keys)}. Valid filter keys are: {sorted(valid_filter_keys)}.","messagePattern":"Unknown filter key\\(s\\): (.+?)\\. Valid filter keys are: (.+?)\\.","errorType":"validation","errorClass":"AgentInvokeException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/azure_ai/agent_thread_actions.py","lineNumber":1017,"sourceCode":"                \"FunctionChoiceBehavior.Auto(auto_invoke=False) is not supported for agent invocations. \"\n                \"The agent run loop manages tool invocation; disabling auto_invoke is not compatible.\"\n            )\n        valid_filter_keys: set[str] = {\n            \"excluded_plugins\",\n            \"included_plugins\",\n            \"excluded_functions\",\n            \"included_functions\",\n        }\n        if function_choice_behavior.filters is not None:\n            if not function_choice_behavior.filters:\n                raise AgentInvokeException(\n                    \"FunctionChoiceBehavior filters must not be empty. Provide at least one filter key \"\n                    f\"from {sorted(valid_filter_keys)}, or omit filters entirely to include all \"\n                    \"kernel functions.\"\n                )\n            unknown_keys = {str(k) for k in function_choice_behavior.filters} - valid_filter_keys\n            if unknown_keys:\n                raise AgentInvokeException(\n                    f\"Unknown filter key(s): {sorted(unknown_keys)}. \"\n                    f\"Valid filter keys are: {sorted(valid_filter_keys)}.\"\n                )\n\n    @classmethod\n    def _get_tools(\n        cls: type[_T],\n        agent: \"AzureAIAgent\",\n        kernel: \"Kernel\",\n        tools_override: list[ToolDefinition] | None = None,\n        function_choice_behavior: FunctionChoiceBehavior | None = None,\n    ) -> list[dict[str, Any] | ToolDefinition]:\n        \"\"\"Get the tools for the agent.\n\n        Args:\n            agent: The agent instance.\n            kernel: The kernel to use for function metadata.\n            tools_override: When provided, overrides agent.definition.tools (SDK-level tools only).","sourceCodeStart":999,"sourceCodeEnd":1035,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/azure_ai/agent_thread_actions.py#L999-L1035","documentation":"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.","triggerScenarios":"Passing a filters dict with keys like 'include_functions' (singular), 'plugin_filters', or any key not in the four recognized names.","commonSituations":"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.","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."],"exampleFix":"// before\nbehavior = FunctionChoiceBehavior.Auto(\n    filters={\"include_functions\": [\"MyPlugin-MyFunc\"]}\n)\n\n// after\nbehavior = FunctionChoiceBehavior.Auto(\n    filters={\"included_functions\": [\"MyPlugin-MyFunc\"]}\n)","handlingStrategy":"validation","validationCode":"VALID_FILTER_KEYS = {\"excluded_plugins\", \"included_plugins\", \"excluded_functions\", \"included_functions\"}\n\ndef validate_filter_keys(behavior) -> None:\n    if behavior is None or behavior.filters is None:\n        return\n    bad = set(behavior.filters) - VALID_FILTER_KEYS\n    if bad:\n        raise ValueError(f\"Unknown filter keys: {sorted(bad)}\")","typeGuard":"VALID_FILTER_KEYS = {\"excluded_plugins\", \"included_plugins\", \"excluded_functions\", \"included_functions\"}\n\ndef filters_use_valid_keys(b: object) -> bool:\n    f = getattr(b, \"filters\", None)\n    return f is None or set(map(str, f)).issubset(VALID_FILTER_KEYS)","tryCatchPattern":null,"preventionTips":["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."],"tags":["azure-ai-agent","function-choice-behavior","filters","configuration"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}