microsoft/autogen · error · ValueError

Unsupported built-in tool type: {tool_name}

Error message

Unsupported built-in tool type: {tool_name}

What it means

OpenAIAgent._add_builtin_tool ends in a final else: any tool string that is not one of the known built-ins (web_search_preview, image_generation, local_shell, file_search, code_interpreter, computer_use_preview, mcp) is rejected. This catches typos and tool names the installed OpenAI API layer does not recognize as string-configurable.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py:464

            # Special handling for local_shell - very limited model support
            if self._model != "codex-mini-latest":
                raise ValueError(
                    f"Tool 'local_shell' is only supported with model 'codex-mini-latest', "
                    f"but current model is '{self._model}'. "
                    f"This tool is available exclusively through the Responses API and has severe limitations. "
                    f"Consider using autogen_ext.tools.code_execution.PythonCodeExecutionTool with "
                    f"autogen_ext.code_executors.local.LocalCommandLineCodeExecutor for shell execution instead."
                )
            self._tools.append({"type": "local_shell"})
        elif tool_name in ["file_search", "code_interpreter", "computer_use_preview", "mcp"]:
            # These tools require specific parameters and must use dict configuration
            raise ValueError(
                f"Tool '{tool_name}' requires specific parameters and cannot be added using string format. "
                f"Use dict configuration instead. Required parameters for {tool_name}: "
                f"{self._get_required_params_help(tool_name)}"
            )
        else:
            raise ValueError(f"Unsupported built-in tool type: {tool_name}")

    def _get_required_params_help(self, tool_name: str) -> str:
        """Get help text for required parameters of a tool."""
        help_text = {
            "file_search": "vector_store_ids (List[str])",
            "code_interpreter": "container (str | dict)",
            "computer_use_preview": "display_height (int), display_width (int), environment (str)",
            "mcp": "server_label (str), server_url (str)",
        }
        return help_text.get(tool_name, "unknown parameters")

    def _convert_message_to_dict(self, message: OpenAIMessage) -> Dict[str, Any]:
        """Convert an OpenAIMessage to a Dict[str, Any]."""
        return dict(message)

    @property
    def produced_message_types(
        self: "OpenAIAgent",

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Correct the name to one of the supported built-ins: web_search_preview, image_generation, local_shell, file_search, code_interpreter, computer_use_preview, mcp.
2. For custom or function tools, register them through the model client / agent runtime rather than the built-in tools list.
3. If you believe the name is a valid newer OpenAI tool type, pass it as a dict with a "type" key, or upgrade autogen-ext to a version that whitelists it.

Example fix

# before
agent = OpenAIAgent(name="a", model="gpt-4o", client=client, tools=["web_search"])

# after
agent = OpenAIAgent(name="a", model="gpt-4o", client=client, tools=["web_search_preview"])

KNOWN_BUILTINS = {"web_search_preview", "image_generation", "local_shell",
                   "file_search", "code_interpreter", "computer_use_preview", "mcp"}
unknown = [t for t in tools if isinstance(t, str) and t not in KNOWN_BUILTINS]
assert not unknown, f"Unknown built-in tools: {unknown}"

def is_known_builtin(name: str) -> bool:
    return name in {"web_search_preview", "image_generation", "local_shell",
                    "file_search", "code_interpreter", "computer_use_preview", "mcp"}

When it happens

Trigger: tools=["web_search"] (the actual built-in is web_search_preview), tools=["code_executor"], or any other unrecognized string.

Common situations: Typos and abbreviated names (web_search vs web_search_preview); using newer OpenAI built-in tool names not yet supported by the installed autogen-ext version; confusing autogen-core tool names with OpenAI built-in tool types.

Related errors

• Unsupported tool type: {type(tool)}
• Tool '{tool_name}' requires specific parameters and cannot b
• Unsupported tool type: {type(tool)}
• Model does not support function calling
• tool_choice specified but no tools provided

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/2da55f0938cbd8c7. Report an issue: GitHub.