microsoft/autogen · error · ValueError

Tool 'local_shell' is only supported with model 'codex-mini-

Error message

Tool 'local_shell' is only supported with model 'codex-mini-latest', but current model is '{self._model}'. This tool is available exclusively through the Responses API and has severe limitations. Consider using autogen_ext.tools.code_execution.PythonCodeExecutionTool with autogen_ext.code_executors.local.LocalCommandLineCodeExecutor for shell execution instead.

What it means

OpenAIAgent._add_builtin_tool gates the local_shell built-in behind a hard model check: it only works with 'codex-mini-latest', because the local_shell tool type exists only in OpenAI's Responses API and only on that model. Any other model name raises immediately at construction time, with a pointer to the local code-execution alternative.

Source

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

                    # Handle configured built-in tools
                    self._tools.append(cast(dict[str, Any], tool))
                else:
                    raise ValueError(f"Unsupported tool type: {type(tool)}")

    def _add_builtin_tool(self, tool_name: str) -> None:
        """Add a built-in tool by name."""
        # Skip if an identical tool has already been registered (idempotent behaviour)
        if any(td.get("type") == tool_name for td in self._tools):
            return  # Duplicate – ignore rather than raise to stay backward-compatible
        # Only allow string format for tools that don't require parameters
        if tool_name == "web_search_preview":
            self._tools.append({"type": "web_search_preview"})
        elif tool_name == "image_generation":
            self._tools.append({"type": "image_generation"})
        elif tool_name == "local_shell":
            # 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:

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Set model="codex-mini-latest" if you specifically want the Responses-API local_shell tool.
2. Prefer the suggested alternative: autogen_ext.tools.code_execution.PythonCodeExecutionTool with LocalCommandLineCodeExecutor for portable shell/Python execution on any model.
3. Remove "local_shell" from the tools list when using non-codex models.

Example fix

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

# after
from autogen_ext.code_executors.local import LocalCommandLineCodeExecutor
from autogen_ext.tools.code_execution import PythonCodeExecutionTool
from autogen_core.tools import FunctionTool

executor = LocalCommandLineCodeExecutor(timeout=60)
tool = FunctionTool(PythonCodeExecutionTool(executor).run, description="Run Python locally")
# register `tool` via your runtime/agent tool mechanism instead of tools=["local_shell"]

def supports_local_shell(model: str) -> bool:
    return model == "codex-mini-latest"

tools = [t for t in tools if t != "local_shell"] if not supports_local_shell(model) else tools

When it happens

Trigger: OpenAIAgent(model="gpt-4o", ..., tools=["local_shell"]) — any model string other than exactly "codex-mini-latest".

Common situations: Reusing a tools list across agents where one targets codex-mini-latest and another gpt-4o/gpt-4.1; renaming or aliasing the model (e.g. a deployment name) so the exact-string check fails; wanting shell access without realizing local_shell is not a general-purpose tool.

Related errors

• Unsupported tool type: {type(tool)}
• Tool '{tool_name}' requires specific parameters and cannot b
• Unsupported built-in tool type: {tool_name}
• Unsupported tool type: {type(tool)}
• No tools are available.

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