{"record":{"id":"d6186b5635980c46","repo":"microsoft/autogen","slug":"tool-local-shell-is-only-supported-with-model-c","errorCode":null,"errorMessage":"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.","messagePattern":"Tool 'local_shell' is only supported with model 'codex-mini-latest', but current model is '(.+?)'\\. 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\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py","lineNumber":448,"sourceCode":"                    # Handle configured built-in tools\n                    self._tools.append(cast(dict[str, Any], tool))\n                else:\n                    raise ValueError(f\"Unsupported tool type: {type(tool)}\")\n\n    def _add_builtin_tool(self, tool_name: str) -> None:\n        \"\"\"Add a built-in tool by name.\"\"\"\n        # Skip if an identical tool has already been registered (idempotent behaviour)\n        if any(td.get(\"type\") == tool_name for td in self._tools):\n            return  # Duplicate – ignore rather than raise to stay backward-compatible\n        # Only allow string format for tools that don't require parameters\n        if tool_name == \"web_search_preview\":\n            self._tools.append({\"type\": \"web_search_preview\"})\n        elif tool_name == \"image_generation\":\n            self._tools.append({\"type\": \"image_generation\"})\n        elif tool_name == \"local_shell\":\n            # Special handling for local_shell - very limited model support\n            if self._model != \"codex-mini-latest\":\n                raise ValueError(\n                    f\"Tool 'local_shell' is only supported with model 'codex-mini-latest', \"\n                    f\"but current model is '{self._model}'. \"\n                    f\"This tool is available exclusively through the Responses API and has severe limitations. \"\n                    f\"Consider using autogen_ext.tools.code_execution.PythonCodeExecutionTool with \"\n                    f\"autogen_ext.code_executors.local.LocalCommandLineCodeExecutor for shell execution instead.\"\n                )\n            self._tools.append({\"type\": \"local_shell\"})\n        elif tool_name in [\"file_search\", \"code_interpreter\", \"computer_use_preview\", \"mcp\"]:\n            # These tools require specific parameters and must use dict configuration\n            raise ValueError(\n                f\"Tool '{tool_name}' requires specific parameters and cannot be added using string format. \"\n                f\"Use dict configuration instead. Required parameters for {tool_name}: \"\n                f\"{self._get_required_params_help(tool_name)}\"\n            )\n        else:\n            raise ValueError(f\"Unsupported built-in tool type: {tool_name}\")\n\n    def _get_required_params_help(self, tool_name: str) -> str:","sourceCodeStart":430,"sourceCodeEnd":466,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py#L430-L466","documentation":"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.","triggerScenarios":"OpenAIAgent(model=\"gpt-4o\", ..., tools=[\"local_shell\"]) — any model string other than exactly \"codex-mini-latest\".","commonSituations":"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.","solutions":["Set model=\"codex-mini-latest\" if you specifically want the Responses-API local_shell tool.","Prefer the suggested alternative: autogen_ext.tools.code_execution.PythonCodeExecutionTool with LocalCommandLineCodeExecutor for portable shell/Python execution on any model.","Remove \"local_shell\" from the tools list when using non-codex models."],"exampleFix":"# before\nagent = OpenAIAgent(name=\"a\", model=\"gpt-4o\", client=client, tools=[\"local_shell\"])\n\n# after\nfrom autogen_ext.code_executors.local import LocalCommandLineCodeExecutor\nfrom autogen_ext.tools.code_execution import PythonCodeExecutionTool\nfrom autogen_core.tools import FunctionTool\n\nexecutor = LocalCommandLineCodeExecutor(timeout=60)\ntool = FunctionTool(PythonCodeExecutionTool(executor).run, description=\"Run Python locally\")\n# register `tool` via your runtime/agent tool mechanism instead of tools=[\"local_shell\"]","handlingStrategy":"validation","validationCode":"def supports_local_shell(model: str) -> bool:\n    return model == \"codex-mini-latest\"\n\ntools = [t for t in tools if t != \"local_shell\"] if not supports_local_shell(model) else tools","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat local_shell as codex-mini-latest-only; default to PythonCodeExecutionTool.","Parameterize the model per agent config so tool lists can be filtered automatically.","Watch for exact-string matching: deployment aliases will fail the check."],"tags":["openai","tools","model-support","local-shell"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}