{"record":{"id":"4d7135cd2c96ca9f","repo":"microsoft/semantic-kernel","slug":"unknown-filter-key-s-sorted-unknown-keys-val-4d7135","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":"exception","errorClass":"AgentInvokeException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/open_ai/assistant_thread_actions.py","lineNumber":907,"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: \"OpenAIAssistantAgent\",\n        kernel: \"Kernel\",\n        tools_override: \"list[AssistantToolParam] | None\" = None,\n        function_choice_behavior: FunctionChoiceBehavior | None = None,\n    ) -> list[dict[str, str]]:\n        \"\"\"Get the list of tools for the assistant.\n\n        Args:\n            agent: The assistant agent.\n            kernel: The kernel to use for function metadata.\n            tools_override: When provided, overrides agent.definition.tools (SDK-level tools only).","sourceCodeStart":889,"sourceCodeEnd":925,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/open_ai/assistant_thread_actions.py#L889-L925","documentation":"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.","triggerScenarios":"Passing filters with a misspelled or unsupported key, e.g. {'include_functions': [...]} (missing 'd'), {'plugins': [...]}, or a deprecated key name from an older API.","commonSituations":"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.","solutions":["Use only the valid keys: excluded_plugins, included_plugins, excluded_functions, included_functions.","Copy the exact key names from the error message's valid set to avoid typos.","If constructing filters dynamically, validate keys against the valid set before building the behavior."],"exampleFix":"// before\nfcb = FunctionChoiceBehavior.Auto(filters={'include_functions': ['math.add']})\nawait assistant.invoke(kernel=kernel, function_choice_behavior=fcb, thread_id=tid)\n\n// after\nfcb = FunctionChoiceBehavior.Auto(filters={'included_functions': ['math.add']})\nawait assistant.invoke(kernel=kernel, function_choice_behavior=fcb, thread_id=tid)","handlingStrategy":"validation","validationCode":"VALID = {\"excluded_plugins\", \"included_plugins\", \"excluded_functions\", \"included_functions\"}\n\ndef filters_keys_valid(fcb) -> bool:\n    if fcb is None or getattr(fcb, 'filters', None) is None:\n        return True\n    return set(map(str, fcb.filters)) <= VALID","typeGuard":"VALID = {\"excluded_plugins\", \"included_plugins\", \"excluded_functions\", \"included_functions\"}\n\ndef has_only_valid_filter_keys(fcb) -> bool:\n    if fcb is None or getattr(fcb, 'filters', None) is None:\n        return True\n    return set(map(str, fcb.filters)) <= VALID","tryCatchPattern":null,"preventionTips":["Use only excluded_plugins, included_plugins, excluded_functions, included_functions.","When constructing filters from user input, validate keys against the known set first.","Copy key names verbatim from the error message to avoid typos."],"tags":["openai","assistant","function-choice-behavior","filters","validation"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}