Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

fix(openai): route responses-only models instead of failing with 404 (#6656)

alex-clawdb64c92c87b74
diff --git a/lib/crewai/src/crewai/llms/providers/openai/completion.py b/lib/crewai/src/crewai/llms/providers/openai/completion.py
index 78e8d23e8..2cd07e863 100644
--- a/lib/crewai/src/crewai/llms/providers/openai/completion.py
+++ b/lib/crewai/src/crewai/llms/providers/openai/completion.py
@@ -51,6 +51,13 @@ if TYPE_CHECKING:
from crewai.tools.base_tool import BaseTool
+# Models learned at runtime to be unavailable on /v1/chat/completions, keyed by
+# the model string as configured. Populated from the 404 by
+# `_remember_responses_only_model` so the wasted round trip is paid once per model
+# per process rather than on every call.
+_LEARNED_RESPONSES_ONLY_MODELS: set[str] = set()
+
+
class WebSearchResult(TypedDict, total=False):
"""Result from web search built-in tool."""
@@ -453,7 +460,7 @@ class OpenAICompletion(BaseLLM):
):
raise ValueError("LLM call blocked by before_llm_call hook")
- if self.api == "responses":
+ if self._effective_api() == "responses":
return self._call_responses(
messages=formatted_messages,
tools=tools,
@@ -489,27 +496,52 @@ class OpenAICompletion(BaseLLM):
from_agent: BaseAgent | None = None,
response_model: type[BaseModel] | None = None,
) -> str | Any:
- """Call OpenAI Chat Completions API."""
+ """Call OpenAI Chat Completions API.
+
+ Falls back to the Responses API when the model turns out not to be served
+ by chat completions, which OpenAI reports as a 404 distinct from a genuine
+ unknown model.
+ """
completion_params = self._prepare_completion_params(
messages=messages, tools=tools
)
- if self._effective_stream():
- return self._handle_streaming_completion(
+ try:
+ if self._effective_stream():
+ return self._handle_streaming_completion(
+ params=completion_params,
+ available_functions=available_functions,
+ from_task=from_task,
+ from_agent=from_agent,
+ response_model=response_model,
+ )
+
+ return self._handle_completion(
params=completion_params,
available_functions=available_functions,
from_task=from_task,
from_agent=from_agent,
response_model=response_model,
)
-
- return self._handle_completion(
- params=completion_params,
- available_functions=available_functions,
- from_task=from_task,
- from_agent=from_agent,
- response_model=response_model,
- )
+ except Exception as e:
+ if self.custom_openai or not self._is_responses_only_error(
+ e.__cause__ or e
+ ):
+ raise
+ self._remember_responses_only_model()
+ logging.debug(
+ "Retrying %r on the Responses API: not served by "
+ '/v1/chat/completions. Set api="responses" to skip this.',
+ self.model,
+ )
+ return self._call_responses(
+ messages=messages,
+ tools=tools,
+ available_functions=available_functions,
+ from_task=from_task,
+ from_agent=from_agent,
+ response_model=response_model,
+ )
async def acall(
self,
@@ -548,7 +580,7 @@ class OpenAICompletion(BaseLLM):
formatted_messages = self._format_messages(messages)
- if self.api == "responses":
+ if self._effective_api() == "responses":
return await self._acall_responses(
messages=formatted_messages,
tools=tools,
@@ -584,27 +616,46 @@ class OpenAICompletion(BaseLLM):
from_agent: BaseAgent | None = None,
response_model: type[BaseModel] | None = None,
) -> str | Any:
- """Async call to OpenAI Chat Completions API."""
+ """Async call to OpenAI Chat Completions API.
+
+ Falls back to the Responses API for models not served by chat completions,
+ mirroring :meth:`_call_completions`.
+ """
completion_params = self._prepare_completion_params(
messages=messages, tools=tools
)
- if self._effective_stream():
- return await self._ahandle_streaming_completion(
+ try:
+ if self._effective_stream():
+ return await self._ahandle_streaming_completion(
+ params=completion_params,
+ available_functions=available_functions,
+ from_task=from_task,
+ from_agent=from_agent,
+ response_model=response_model,
+ )
+
+ return await self._ahandle_completion(
params=completion_params,
available_functions=available_functions,
from_task=from_task,
from_agent=from_agent,
response_model=response_model,
)
-
- return await self._ahandle_completion(
- params=completion_params,
- available_functions=available_functions,
- from_task=from_task,
- from_agent=from_agent,
- response_model=response_model,
- )
+ except Exception as e:
+ if self.custom_openai or not self._is_responses_only_error(
+ e.__cause__ or e
+ ):
+ raise
+ self._remember_responses_only_model()
+ return await self._acall_responses(
+ messages=messages,
+ tools=tools,
+ available_functions=available_functions,
+ from_task=from_task,
+ from_agent=from_agent,
+ response_model=response_model,
+ )
def _call_responses(
self,
@@ -1557,6 +1608,65 @@ class OpenAICompletion(BaseLLM):
"""
return [item for item in response.output if item.type == "reasoning"]
+ @staticmethod
+ def _is_responses_only_error(error: BaseException) -> bool:
+ """Whether a 404 means the model exists but isn't on chat completions.
+
+ OpenAI distinguishes the two 404s it returns here:
+
+ responses-only param="model", "only supported in v1/responses"
+ or "This is not a chat model"
+ genuine typo code="model_not_found", "does not exist"
+
+ Matching the former lets a newly Responses-only model be recovered without
+ needing to be listed in this file.
+ """
+ if not isinstance(error, NotFoundError):
+ return False
+ body = getattr(error, "body", None)
+ inner = body.get("error") if isinstance(body, dict) else None
+ if isinstance(inner, dict) and inner.get("code") == "model_not_found":
+ return False
+ text = str(getattr(error, "message", "") or error).lower()
+ return "only supported in v1/responses" in text or "not a chat model" in text
+
+ def _remember_responses_only_model(self) -> None:
+ """Record that this model must use the Responses API."""
+ _LEARNED_RESPONSES_ONLY_MODELS.add(self.model)
+
+ def _model_not_found_message(self, error: Exception) -> str:
+ """Build a 404 message that says what to do about it.
+
+ OpenAI's own wording ("This is not a chat model") doesn't make the fix
+ obvious, so point at ``api="responses"`` when that's what it means.
+ """
+ if self._is_responses_only_error(error):
+ return (
+ f"Model {self.model} is not available on /v1/chat/completions. "
+ f'Use api="responses" (LLM(model="{self.model}", api="responses")) '
+ f"to reach it: {error}"
+ )
+ return f"Model {self.model} not found: {error}"
+
+ def _effective_api(self) -> str:
+ """Which OpenAI API to actually use for this model.
+
+ Honours an explicit ``api`` setting, but upgrades to ``"responses"`` for
+ models already known -- from a previous 404 in this process -- not to be
+ served by chat completions.
+
+ Never overrides ``custom_openai=True``: an OpenAI-compatible server may
+ serve any model name on /v1/chat/completions and most don't implement
+ /v1/responses at all, so the user's choice stands.
+ """
+ if (
+ self.api == "completions"
+ and not self.custom_openai
+ and self.model in _LEARNED_RESPONSES_ONLY_MODELS
+ ):
+ return "responses"
+ return self.api
+
def _prepare_completion_params(
self, messages: list[LLMMessage], tools: list[dict[str, BaseTool]] | None = None
) -> dict[str, Any]:
@@ -1786,7 +1896,7 @@ class OpenAICompletion(BaseLLM):
params["messages"], content, from_agent
)
except NotFoundError as e:
- error_msg = f"Model {self.model} not found: {e}"
+ error_msg = self._model_not_found_message(e)
logging.error(error_msg)
self._emit_call_failed_event(
error=error_msg, from_task=from_task, from_agent=from_agent
@@ -2209,7 +2319,7 @@ class OpenAICompletion(BaseLLM):
if usage.get("total_tokens", 0) > 0:
logging.info(f"OpenAI API usage: {usage}")
except NotFoundError as e:
- error_msg = f"Model {self.model} not found: {e}"
+ error_msg = self._model_not_found_message(e)
logging.error(error_msg)
self._emit_call_failed_event(
error=error_msg, from_task=from_task, from_agent=from_agent
diff --git a/lib/crewai/tests/llms/openai/test_responses_only_models.py b/lib/crewai/tests/llms/openai/test_responses_only_models.py
new file mode 100644
index 000000000..b46d5d787
--- /dev/null
+++ b/lib/crewai/tests/llms/openai/test_responses_only_models.py
@@ -0,0 +1,209 @@
+"""Tests for models that /v1/chat/completions doesn't serve at all.
+
+The pro tier exists but is Responses-API-only. OpenAI reports it as a 404 that is
+distinguishable from a genuine unknown model:
+
+ responses-only param="model", "only supported in v1/responses"
+ or "This is not a chat model"
+ genuine typo code="model_not_found", "does not exist"
+
+Measured 2026-07 against the live endpoints: gpt-5-pro, gpt-5.2-pro, gpt-5.4-pro,
+gpt-5.5-pro, o1-pro and o3-pro all 404 on chat completions and work on
+/v1/responses. Rather than hardcoding that list, the 404 is caught and the call is
+retried on the Responses API, then the model is remembered so the wasted round trip
+is paid once per process.
+"""
+
+import httpx
+import pytest
+from openai import NotFoundError
+
+from crewai.llms.providers.openai import completion as completion_module
+from crewai.llms.providers.openai.completion import OpenAICompletion
+
+
+MESSAGES = [{"role": "user", "content": "hi"}]
+
+RESPONSES_ONLY_MESSAGES = (
+ "This model is only supported in v1/responses and not in /v1/chat/completions.",
+ "This is not a chat model and thus not supported in the v1/chat/completions "
+ "endpoint. Did you mean to use v1/completions?",
+)
+
+
+def build(model: str, **kwargs) -> OpenAICompletion:
+ return OpenAICompletion(model=model, api_key="sk-test", **kwargs)
+
+
+def make_not_found(message: str, code: str | None = None) -> NotFoundError:
+ body = {
+ "error": {
+ "message": message,
+ "type": "invalid_request_error",
+ "param": None if code else "model",
+ "code": code,
+ }
+ }
+ response = httpx.Response(
+ status_code=404,
+ json=body,
+ request=httpx.Request("POST", "https://api.openai.com/v1/chat/completions"),
+ )
+ return NotFoundError(message, response=response, body=body)
+
+
[email protected](autouse=True)
+def _clear_learned_models():
+ """Keep the process-wide learned set from leaking between tests."""
+ completion_module._LEARNED_RESPONSES_ONLY_MODELS.clear()
+ yield
+ completion_module._LEARNED_RESPONSES_ONLY_MODELS.clear()
+
+
+class TestErrorClassification:
+ @pytest.mark.parametrize("message", RESPONSES_ONLY_MESSAGES)
+ def test_detects_responses_only_404(self, message: str):
+ assert OpenAICompletion._is_responses_only_error(make_not_found(message))
+
+ def test_ignores_genuine_unknown_model(self):
+ """A real typo must keep failing, not get retried on another endpoint."""
+ error = make_not_found(
+ "The model `gpt-5.99-fake` does not exist or you do not have access "
+ "to it.",
+ code="model_not_found",
+ )
+ assert not OpenAICompletion._is_responses_only_error(error)
+
+ def test_ignores_unrelated_exceptions(self):
+ assert not OpenAICompletion._is_responses_only_error(RuntimeError("boom"))
+
+
+class TestFallback:
+ def test_retries_on_responses_and_remembers_the_model(self, monkeypatch):
+ llm = build("gpt-5-pro")
+ calls: list[str] = []
+
+ def fail_completion(**kwargs):
+ calls.append("completions")
+ raise ValueError("wrapped") from make_not_found(
+ RESPONSES_ONLY_MESSAGES[0]
+ )
+
+ monkeypatch.setattr(llm, "_handle_completion", fail_completion)
+ monkeypatch.setattr(
+ llm, "_call_responses", lambda **kwargs: calls.append("responses") or "ok"
+ )
+
+ assert llm._call_completions(MESSAGES) == "ok"
+ assert calls == ["completions", "responses"]
+ # Second call must skip the doomed chat-completions attempt.
+ assert llm._effective_api() == "responses"
+
+ def test_does_not_retry_genuine_unknown_model(self, monkeypatch):
+ llm = build("gpt-5.99-fake")
+ calls: list[str] = []
+
+ def fail_completion(**kwargs):
+ calls.append("completions")
+ raise ValueError("wrapped") from make_not_found(
+ "The model does not exist.", code="model_not_found"
+ )
+
+ monkeypatch.setattr(llm, "_handle_completion", fail_completion)
+ monkeypatch.setattr(
+ llm, "_call_responses", lambda **kwargs: calls.append("responses") or "ok"
+ )
+
+ with pytest.raises(ValueError):
+ llm._call_completions(MESSAGES)
+
+ assert calls == ["completions"]
+ assert not completion_module._LEARNED_RESPONSES_ONLY_MODELS
+
+ def test_custom_endpoint_never_falls_back(self, monkeypatch):
+ """An OpenAI-compatible server may not implement /v1/responses at all.
+
+ Most (vLLM, LiteLLM proxies, Ollama) don't, so a self-hosted model must
+ keep the endpoint the user chose rather than being silently rerouted.
+ """
+ llm = build(
+ "o1-pro", custom_openai=True, base_url="https://my-vllm.internal/v1"
+ )
+ calls: list[str] = []
+
+ def fail_completion(**kwargs):
+ calls.append("completions")
+ raise ValueError("wrapped") from make_not_found(
+ RESPONSES_ONLY_MESSAGES[0]
+ )
+
+ monkeypatch.setattr(llm, "_handle_completion", fail_completion)
+ monkeypatch.setattr(
+ llm, "_call_responses", lambda **kwargs: calls.append("responses") or "ok"
+ )
+
+ with pytest.raises(ValueError):
+ llm._call_completions(MESSAGES)
+
+ assert calls == ["completions"]
+
+ @pytest.mark.asyncio
+ async def test_async_path_falls_back_too(self, monkeypatch):
+ llm = build("gpt-5-pro")
+ calls: list[str] = []
+
+ async def fail_completion(**kwargs):
+ calls.append("completions")
+ raise ValueError("wrapped") from make_not_found(
+ RESPONSES_ONLY_MESSAGES[0]
+ )
+
+ async def ok_responses(**kwargs):
+ calls.append("responses")
+ return "ok"
+
+ monkeypatch.setattr(llm, "_ahandle_completion", fail_completion)
+ monkeypatch.setattr(llm, "_acall_responses", ok_responses)
+
+ assert await llm._acall_completions(MESSAGES) == "ok"
+ assert calls == ["completions", "responses"]
+
+
+class TestEffectiveApi:
+ def test_defaults_to_completions_for_unknown_models(self):
+ """Nothing is assumed up front; the 404 is what teaches us."""
+ assert build("gpt-5-pro")._effective_api() == "completions"
+
+ def test_explicit_responses_is_honoured(self):
+ assert build("gpt-5.5", api="responses")._effective_api() == "responses"
+
+ def test_learned_model_routes_directly(self):
+ llm = build("gpt-5-pro")
+ llm._remember_responses_only_model()
+
+ assert llm._effective_api() == "responses"
+
+ def test_learned_model_still_respects_custom_endpoint(self):
+ llm = build(
+ "gpt-5-pro", custom_openai=True, base_url="https://my-vllm.internal/v1"
+ )
+ completion_module._LEARNED_RESPONSES_ONLY_MODELS.add("gpt-5-pro")
+
+ assert llm._effective_api() == "completions"
+
+
+class TestNotFoundMessage:
+ @pytest.mark.parametrize("message", RESPONSES_ONLY_MESSAGES)
+ def test_points_at_responses_api(self, message: str):
+ msg = build("gpt-5.5")._model_not_found_message(make_not_found(message))
+
+ assert 'api="responses"' in msg
+ assert "not available on /v1/chat/completions" in msg
+
+ def test_keeps_plain_not_found_for_real_typos(self):
+ msg = build("gpt-5.5")._model_not_found_message(
+ make_not_found("The model does not exist.", code="model_not_found")
+ )
+
+ assert "not found" in msg
+ assert 'api="responses"' not in msg