fix(agent): stop treating a failed tool as a provider failure

tool_execution_retry raises AgentToolExecutionError once a tool has exhausted
tool_retry_attempts (agent.py:4398). That call sits inside the try whose
handler catches BadRequestError, InternalServerError, AuthenticationError and
bare Exception, so the tool error landed there, was recorded as
Agent.llm_error, and the whole generation was retried.

Re-running the model cannot fix a broken tool. Measured on the unfixed source
with a tool that always raises: "a tool failure re-ran the model 3 times", and
the run ends with "Failed to generate a valid response after retry attempts",
which points at the provider rather than the tool.

Catch AgentToolExecutionError ahead of the generation handler: flush any tool
results recorded before the failure, report it as Agent.tool_error rather than
Agent.llm_error, write what happened into short_memory, and leave the retry
loop. The run continues, so the next loop lets the model read the failure and
choose differently.

Closes kyegomez#1924

Author: ayaangazali

swarms/structs/agent.py

@@ -1650,6 +1650,36 @@ def _run(
                                 loop_count=loop_count
                             )
 
+                    except AgentToolExecutionError as e:
+                        # A tool that already exhausted its own retries is not
+                        # a provider failure. Re-running the model cannot fix
+                        # it and costs another completion, so record it and
+                        # leave the retry loop instead of falling into the
+                        # generation handler below.
+                        if use_transcript and turn_calls:
+                            transcript.flush_tool_results(
+                                turn_calls, turn_results
+                            )
+
+                        capture_error(
+                            e,
+                            self,
+                            name="Agent.tool_error",
+                            loop=loop_count,
+                        )
+
+                        self.short_memory.add(
+                            role="Tool Executor",
+                            content=(
+                                f"Tool execution failed after "
+                                f"{self.tool_retry_attempts} attempts: {e}"
+                            ),
+                        )
+
+                        # Exit the retry loop, not the run: the next loop lets
+                        # the model read the failure and choose differently.
+                        success = True
+
                     except (
                         BadRequestError,
                         InternalServerError,

tests/structs/test_agent.py

@@ -1194,6 +1194,53 @@ def test_a_zero_or_none_attempt_count_still_runs_once(self):
             ), f"attempts={attempts!r} should still run once"
 
 
+class TestToolFailureIsNotAnLLMError:
+    """#1924: a tool that exhausted its own retries raised into the generation
+    handler, which logged it as Agent.llm_error and re-ran the model, so one
+    broken tool cost up to retry_attempts extra completions.
+    """
+
+    @staticmethod
+    def _broken_tool(query: str) -> str:
+        """Always fails.
+
+        Args:
+            query: anything at all.
+        """
+        raise RuntimeError("tool is broken")
+
+    def test_a_failing_tool_does_not_re_run_the_model(self):
+        agent = _patched_agent(
+            "ToolFailAgent",
+            model_name="gpt-5.4",
+            dynamic_tools=False,
+            tools=[self._broken_tool],
+            retry_attempts=3,
+        )
+
+        llm_calls = []
+
+        def fake_call_llm(task=None, *args, **kwargs):
+            llm_calls.append(task)
+            return [
+                {
+                    "type": "function",
+                    "id": "call-1",
+                    "function": {
+                        "name": "_broken_tool",
+                        "arguments": '{"query": "x"}',
+                    },
+                }
+            ]
+
+        agent.call_llm = fake_call_llm
+        agent.run("use the tool")
+
+        assert (
+            len(llm_calls) == 1
+        ), f"a tool failure re-ran the model {len(llm_calls)} times"
+
+
 class TestConcurrentExecutionPool:
     """#1793: both concurrent entry points referenced self.executor, which
     __init__ never assigned — run_concurrent_tasks swallowed the AttributeError