feat(agent_utils.py): add FallbackToolExecutionError exception to handle fallback tool execution failures

fix(ciayn_agent.py): improve error message template for tool call errors to provide clearer guidance
refactor(ciayn_agent.py): update comment for clarity regarding fallback tool invocation
fix(output.py): clarify that CiaynAgent handles tool execution errors internally
fix(fallback_handler.py): raise FallbackToolExecutionError for better error handling in fallback scenarios

ra_aid/agent_utils.py

@@ -32,7 +32,11 @@ from ra_aid.agents_alias import RAgents
 from ra_aid.config import DEFAULT_MAX_TEST_CMD_RETRIES, DEFAULT_RECURSION_LIMIT
 from ra_aid.console.formatting import print_error, print_stage_header
 from ra_aid.console.output import print_agent_output
-from ra_aid.exceptions import AgentInterrupt, ToolExecutionError
+from ra_aid.exceptions import (
+    AgentInterrupt,
+    ToolExecutionError,
+    FallbackToolExecutionError,
+)
 from ra_aid.fallback_handler import FallbackHandler
 from ra_aid.logging_config import get_logger
 from ra_aid.models_params import DEFAULT_TOKEN_LIMIT, models_params
@@ -900,8 +904,6 @@ def run_agent_with_retry(
                     logger.debug("Agent run completed successfully")
                     return "Agent run completed successfully"
                 except ToolExecutionError as e:
-                    print("except ToolExecutionError in AGENT UTILS")
-                    logger.debug("AGENT UTILS ToolExecutionError called!")
                     if not fallback_handler:
                         continue
 
@@ -912,9 +914,11 @@ def run_agent_with_retry(
                                 SystemMessage(str(msg)) for msg in fallback_response
                             ]
                             msg_list.extend(msg_list_response)
-                        else:
-                            pass
                     continue
+                except FallbackToolExecutionError as e:
+                    msg_list.append(
+                        SystemMessage(f"FallbackToolExecutionError:{str(e)}")
+                    )
                 except (KeyboardInterrupt, AgentInterrupt):
                     raise
                 except (

ra_aid/agents/ciayn_agent.py

@@ -112,6 +112,7 @@ class CiaynAgent:
         self.sys_message = SystemMessage(
             "Execute efficiently yet completely as a fully autonomous agent."
         )
+        self.error_message_template = "Your tool call caused an error: {e}\n\nPlease correct your tool call and try again."
 
     def _build_prompt(self, last_result: Optional[str] = None) -> str:
         """Build the prompt for the agent including available tools and context."""
@@ -173,7 +174,7 @@ class CiaynAgent:
             return ""
 
         msg = f"Fallback tool handler has triggered after consecutive failed tool calls reached {DEFAULT_MAX_TOOL_FAILURES} failures.\n"
-        # Passing the fallback invocation may confuse our llm, as invocation methods may differ.
+        # Passing the fallback raw invocation may confuse our llm, as invocation methods may differ.
         # msg += f"<fallback llm raw invocation>{fallback_response[0]}</fallback llm raw invocation>\n"
         msg += f"<fallback tool name>{e.tool_name}</fallback tool name>"
         msg += f"<fallback tool call result>{fallback_response[1]}</fallback tool call result>"

ra_aid/console/output.py

@@ -46,6 +46,8 @@ def print_agent_output(
                     )
                 )
                 tool_name = getattr(msg, "name", None)
+
+                # CiaynAgent handles this internally
                 if agent_type == "React":
                     raise ToolExecutionError(
                         err_msg, tool_name=tool_name, base_message=msg

ra_aid/exceptions.py

@@ -31,3 +31,9 @@ class ToolExecutionError(Exception):
         super().__init__(message)
         self.base_message = base_message
         self.tool_name = tool_name
+
+
+class FallbackToolExecutionError(Exception):
+    """Exception raised when a fallback tool execution fails."""
+
+    pass

ra_aid/fallback_handler.py

@@ -13,7 +13,7 @@ from ra_aid.config import (
     RETRY_FALLBACK_COUNT,
 )
 from ra_aid.console.output import cpm
-from ra_aid.exceptions import ToolExecutionError
+from ra_aid.exceptions import ToolExecutionError, FallbackToolExecutionError
 from ra_aid.llm import initialize_llm, validate_provider_env
 from ra_aid.logging_config import get_logger
 from ra_aid.tool_configs import get_all_tools
@@ -197,7 +197,9 @@ class FallbackHandler:
                 )
             else:
                 failed_tool_call_name = "Tool execution error"
-                raise Exception("Fallback failed: Could not extract failed tool name.")
+                raise FallbackToolExecutionError(
+                    "Fallback failed: Could not extract failed tool name."
+                )
 
         return failed_tool_call_name
 
@@ -217,8 +219,8 @@ class FallbackHandler:
             )
         if tool_to_bind is None:
             # TODO: Would be nice to try fuzzy match or levenstein str match to find closest correspond tool name
-            raise Exception(
-                f"Fallback failed: {failed_tool_call_name} not found in all tools."
+            raise FallbackToolExecutionError(
+                f"Fallback failed failed_tool_call_name: '{failed_tool_call_name}' not found in any available tools."
             )
         return tool_to_bind