feat(llm): add native Groq provider and fix cache_breakpoint for non-Anthropic models

lib/crewai/src/crewai/agents/crew_agent_executor.py

@@ -80,6 +80,7 @@
     aexecute_tool_and_check_finality,
     execute_tool_and_check_finality,
 )
+from crewai.utilities.tool_errors import format_tool_error
 from crewai.utilities.training_handler import CrewTrainingHandler
 
 
@@ -1006,7 +1007,7 @@ def _execute_single_native_tool_call(
 
                 result = format_native_tool_output_for_agent(output_tool, raw_result)
             except Exception as e:
-                result = f"Error executing tool: {e}"
+                result = format_tool_error(e)
                 raw_tool_result = result
                 if self.task:
                     self.task.increment_tools_errors()

lib/crewai/src/crewai/experimental/agent_executor.py

@@ -108,6 +108,7 @@
 )
 from crewai.utilities.step_execution_context import StepExecutionContext, StepResult
 from crewai.utilities.string_utils import sanitize_tool_name
+from crewai.utilities.tool_errors import format_tool_error
 from crewai.utilities.tool_utils import execute_tool_and_check_finality
 from crewai.utilities.training_handler import CrewTrainingHandler
 from crewai.utilities.types import LLMMessage
@@ -1615,9 +1616,10 @@ def execute_tool_action(self) -> Literal["tool_completed", "tool_result_is_final
             if self.task:
                 self.task.increment_tools_errors()
 
-            error_observation = f"\nObservation: Error executing tool: {e}"
+            structured_error = format_tool_error(e)
+            error_observation = f"\nObservation: {structured_error}"
             action.text += error_observation
-            action.result = str(e)
+            action.result = structured_error
             self._append_message_to_state(action.text)
 
             reasoning_prompt = I18N_DEFAULT.slice("post_tool_reasoning")
@@ -1736,7 +1738,7 @@ def execute_native_tool(
                         ordered_results[idx] = {
                             "call_id": call_id,
                             "func_name": func_name,
-                            "result": f"Error executing tool: {e}",
+                            "result": format_tool_error(e),
                             "from_cache": False,
                             "original_tool": None,
                         }
@@ -1999,7 +2001,7 @@ def _execute_single_native_tool_call(self, tool_call: Any) -> dict[str, Any]:
                         output_tool, raw_result
                     )
                 except Exception as e:
-                    result = f"Error executing tool: {e}"
+                    result = format_tool_error(e)
                     raw_tool_result = result
                     if self.task:
                         self.task.increment_tools_errors()

lib/crewai/src/crewai/llm.py

@@ -52,6 +52,7 @@
 from crewai.utilities.logger_utils import suppress_warnings
 from crewai.utilities.string_utils import sanitize_tool_name
 from crewai.utilities.token_counter_callback import TokenCalcHandler
+from crewai.utilities.tool_errors import format_tool_error
 
 
 try:
@@ -342,6 +343,7 @@ def _ensure_litellm() -> bool:
     "cerebras",
     "dashscope",
     "snowflake",
+    "groq",
 ]
 
 
@@ -431,6 +433,7 @@ def __new__(cls, model: str, is_litellm: bool = False, **kwargs: Any) -> LLM:
                 "cerebras": "cerebras",
                 "dashscope": "dashscope",
                 "snowflake": "snowflake",
+                "groq": "groq",
             }
 
             canonical_provider = provider_mapping.get(prefix.lower())
@@ -553,6 +556,12 @@ def _matches_provider_pattern(cls, model: str, provider: str) -> bool:
         if provider == "snowflake":
             return True
 
+        if provider == "groq":
+            return any(
+                model_lower.startswith(prefix)
+                for prefix in ["llama", "gemma", "mixtral", "whisper", "deepseek"]
+            )
+
         return False
 
     @classmethod
@@ -664,6 +673,7 @@ def _get_native_provider(cls, provider: str) -> type | None:
             "hosted_vllm",
             "cerebras",
             "dashscope",
+            "groq",
         }
         if provider in openai_compatible_providers:
             from crewai.llms.providers.openai_compatible.completion import (
@@ -1755,11 +1765,12 @@ def _handle_tool_call(
                 return result
             except Exception as e:
                 fn = available_functions.get(function_name, lambda: None)
+                structured_error = format_tool_error(e)
                 logging.error(f"Error executing function '{function_name}': {e}")
                 crewai_event_bus.emit(
                     self,
                     event=LLMCallFailedEvent(
-                        error=f"Tool execution error: {e!s}",
+                        error=structured_error,
                         from_task=from_task,
                         from_agent=from_agent,
                         call_id=get_current_call_id(),
@@ -1770,7 +1781,7 @@ def _handle_tool_call(
                     event=ToolUsageErrorEvent(
                         tool_name=function_name,
                         tool_args=function_args,
-                        error=f"Tool execution error: {e!s}",
+                        error=structured_error,
                         from_task=from_task,
                         from_agent=from_agent,
                     ),
@@ -2286,6 +2297,17 @@ def _format_messages_for_provider(
                     "Invalid message format. Each message must be a dict with 'role' and 'content' keys"
                 )
 
+        # Strip cache_breakpoint from messages for non-Anthropic providers.
+        # This key is only meaningful for Anthropic's prompt caching API;
+        # other providers (Groq, OpenAI-compatible) reject unknown fields.
+        if not self.is_anthropic:
+            from crewai.llms.cache import CACHE_BREAKPOINT_KEY
+
+            messages = [
+                {k: v for k, v in msg.items() if k != CACHE_BREAKPOINT_KEY}
+                for msg in messages
+            ]  # type: ignore[assignment]
+
         if "o1" in self.model.lower():
             formatted_messages = []
             for msg in messages:

lib/crewai/src/crewai/llms/providers/openai_compatible/completion.py

@@ -89,6 +89,12 @@ class ProviderConfig:
         base_url_env="DASHSCOPE_BASE_URL",
         api_key_required=True,
     ),
+    "groq": ProviderConfig(
+        base_url="https://api.groq.com/openai/v1",
+        api_key_env="GROQ_API_KEY",
+        base_url_env="GROQ_BASE_URL",
+        api_key_required=True,
+    ),
 }
 
 

lib/crewai/src/crewai/utilities/agent_utils.py

@@ -37,6 +37,7 @@
 from crewai.utilities.pydantic_schema_utils import generate_model_description
 from crewai.utilities.string_utils import sanitize_tool_name
 from crewai.utilities.token_counter_callback import TokenCalcHandler
+from crewai.utilities.tool_errors import format_tool_error
 from crewai.utilities.types import LLMMessage
 
 
@@ -1546,7 +1547,7 @@ def execute_single_native_tool_call(
 
                 result = format_native_tool_output_for_agent(output_tool, raw_result)
             except Exception as e:
-                result = f"Error executing tool: {e}"
+                result = format_tool_error(e)
                 raw_tool_result = result
                 if task:
                     task.increment_tools_errors()

lib/crewai/src/crewai/utilities/tool_errors.py

@@ -0,0 +1,29 @@
+"""Structured tool error formatting for agent consumption.
+
+When a tool raises an exception, the agent needs structured information
+to decide whether to retry, fix its input, or skip the tool entirely.
+This module provides a consistent error format across all executors.
+"""
+
+import json
+import traceback
+
+RETRYABLE_EXCEPTIONS = (TimeoutError, ConnectionError, OSError)
+
+
+def format_tool_error(exception: Exception, include_traceback: bool = False) -> str:
+    """Format a tool execution error as structured JSON for the agent.
+
+    Returns a string with the "Error executing tool:" prefix (for backward
+    compatibility with existing parsing) followed by a JSON object containing
+    the exception type, message, and retryability hint.
+    """
+    error_data = {
+        "error": True,
+        "type": type(exception).__name__,
+        "message": str(exception),
+        "retryable": isinstance(exception, RETRYABLE_EXCEPTIONS),
+    }
+    if include_traceback:
+        error_data["traceback"] = traceback.format_exc(limit=3)
+    return f"Error executing tool: {json.dumps(error_data)}"

lib/crewai/tests/llms/test_groq_provider.py

@@ -0,0 +1,98 @@
+"""Tests for native Groq provider support and cache_breakpoint stripping."""
+
+import pytest
+
+
+class TestGroqNativeRouting:
+    """Test that Groq models route to the native OpenAI-compatible provider."""
+
+    def test_groq_in_supported_providers(self):
+        from crewai.llm import SUPPORTED_NATIVE_PROVIDERS
+
+        assert "groq" in SUPPORTED_NATIVE_PROVIDERS
+
+    def test_groq_provider_config_exists(self):
+        from crewai.llms.providers.openai_compatible.completion import (
+            OPENAI_COMPATIBLE_PROVIDERS,
+        )
+
+        assert "groq" in OPENAI_COMPATIBLE_PROVIDERS
+        config = OPENAI_COMPATIBLE_PROVIDERS["groq"]
+        assert config.base_url == "https://api.groq.com/openai/v1"
+        assert config.api_key_env == "GROQ_API_KEY"
+        assert config.api_key_required is True
+
+    def test_groq_model_pattern_matching(self):
+        from crewai.llm import LLM
+
+        assert LLM._matches_provider_pattern("llama-3.3-70b-versatile", "groq") is True
+        assert LLM._matches_provider_pattern("mixtral-8x7b-32768", "groq") is True
+        assert LLM._matches_provider_pattern("gemma-7b-it", "groq") is True
+        assert LLM._matches_provider_pattern("whisper-large-v3", "groq") is True
+        assert (
+            LLM._matches_provider_pattern("deepseek-r1-distill-llama-70b", "groq")
+            is True
+        )
+        assert LLM._matches_provider_pattern("gpt-4o", "groq") is False
+
+    def test_groq_routes_to_openai_compatible(self):
+        from crewai.llm import LLM
+        from crewai.llms.providers.openai_compatible.completion import (
+            OpenAICompatibleCompletion,
+        )
+
+        provider_class = LLM._get_native_provider("groq")
+        assert provider_class is OpenAICompatibleCompletion
+
+
+class TestCacheBreakpointStripping:
+    """Test that cache_breakpoint is stripped for non-Anthropic providers."""
+
+    def test_strip_cache_breakpoint_for_non_anthropic(self):
+        from crewai.llm import LLM
+
+        llm = LLM.__new__(LLM, model="groq/llama-3.3-70b-versatile")
+        llm.model = "groq/llama-3.3-70b-versatile"
+        llm.is_anthropic = False
+
+        messages = [
+            {"role": "system", "content": "You are helpful.", "cache_breakpoint": True},
+            {"role": "user", "content": "Hello", "cache_breakpoint": True},
+        ]
+
+        result = llm._format_messages_for_provider(messages)
+
+        for msg in result:
+            assert "cache_breakpoint" not in msg
+
+    def test_preserve_cache_breakpoint_for_anthropic(self):
+        from crewai.llm import LLM
+
+        llm = LLM.__new__(LLM, model="anthropic/claude-sonnet-4-20250514")
+        llm.model = "anthropic/claude-sonnet-4-20250514"
+        llm.is_anthropic = True
+
+        messages = [
+            {"role": "user", "content": "Hello", "cache_breakpoint": True},
+        ]
+
+        result = llm._format_messages_for_provider(messages)
+
+        assert result[0].get("cache_breakpoint") is True
+
+    def test_strip_does_not_remove_role_or_content(self):
+        from crewai.llm import LLM
+
+        llm = LLM.__new__(LLM, model="groq/llama-3.3-70b-versatile")
+        llm.model = "groq/llama-3.3-70b-versatile"
+        llm.is_anthropic = False
+
+        messages = [
+            {"role": "user", "content": "Test message", "cache_breakpoint": True},
+        ]
+
+        result = llm._format_messages_for_provider(messages)
+
+        assert result[0]["role"] == "user"
+        assert result[0]["content"] == "Test message"
+        assert "cache_breakpoint" not in result[0]