{"record":{"id":"167eaababd1a7d3f","repo":"microsoft/semantic-kernel","slug":"functionchoicebehavior-filters-must-not-be-empty","errorCode":null,"errorMessage":"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.","messagePattern":"FunctionChoiceBehavior filters must not be empty\\. Provide at least one filter key from (.+?), or omit filters entirely to include all kernel functions\\.","errorType":"validation","errorClass":"AgentInvokeException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/azure_ai/agent_thread_actions.py","lineNumber":1010,"sourceCode":"            raise AgentInvokeException(\n                f\"FunctionChoiceBehavior with type '{function_choice_behavior.type_}' is not supported for agent \"\n                \"invocations. Use FunctionChoiceBehavior.Auto(filters=...) to control which kernel functions \"\n                \"are available.\"\n            )\n        if not function_choice_behavior.auto_invoke_kernel_functions:\n            raise AgentInvokeException(\n                \"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,","sourceCodeStart":992,"sourceCodeEnd":1028,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/azure_ai/agent_thread_actions.py#L992-L1028","documentation":"Raised when FunctionChoiceBehavior.Auto is given a filters dict that is present but empty (e.g. {}). An empty filter object is almost certainly a mistake — it neither includes nor excludes anything and signals the developer forgot to populate it.","triggerScenarios":"Passing FunctionChoiceBehavior.Auto(filters={}) or an empty FunctionChoiceBehaviorFilters instance to an AzureAIAgent invocation.","commonSituations":"Developer builds filters dynamically from config and ends up with an empty dict when no keys are set; or copies a filter template without filling keys.","solutions":["Omit the filters argument entirely to include all kernel functions.","Populate at least one valid key: included_plugins, excluded_plugins, included_functions, or excluded_functions."],"exampleFix":"// before\nbehavior = FunctionChoiceBehavior.Auto(filters={})\n\n// after\n# omit filters entirely to include all functions\nbehavior = FunctionChoiceBehavior.Auto()","handlingStrategy":"validation","validationCode":"def sanitize_filters(behavior):\n    if behavior is not None and behavior.filters is not None and not behavior.filters:\n        behavior.filters = None  # omit to include all\n    return behavior","typeGuard":"def has_nonempty_filters(b: object) -> bool:\n    f = getattr(b, \"filters\", None)\n    return f is None or len(f) > 0","tryCatchPattern":null,"preventionTips":["When building filters from config, set filters=None instead of {} when no keys apply.","Add a schema check (e.g. Pydantic validator) that empty dicts resolve to None."],"tags":["azure-ai-agent","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"}