huggingface/smolagents · error · AgentToolExecutionError

Error executing tool

Error message

Error executing tool '{tool_name}' with arguments {str(arguments)}: {type(e).__name__}: {e}
Please try again or use another tool

What it means

The general tool-failure path in execute_tool_call: when actually invoking the tool raises, the exception is wrapped in AgentToolExecutionError with a 'Please try again or use another tool' hint. smolagents appends this observation to the agent's memory so the model can retry with corrected arguments or a different tool.

Solutions

Identify the underlying exception from the message (type and text) and fix the tool's own error handling.
Make the tool return a descriptive error string instead of raising, so the agent can adapt.
For transient failures (network, rate limits), retry agent.run or add internal retries/backoff in the tool.

Example fix

# before
@tool
def fetch_url(url: str) -> str:
    return requests.get(url).text  # raises on non-200

# after
@tool
def fetch_url(url: str) -> str:
    resp = requests.get(url, timeout=10)
    if not resp.ok:
        return f"Error fetching {url}: HTTP {resp.status_code}"
    return resp.text

Defensive patterns

Strategy: fallback

Try / catch

from smolagents.exceptions import AgentToolExecutionError

try:
    result = agent.run(task)
except AgentToolExecutionError:
    # observation with 'Please try again or use another tool' is in agent memory;
    # continue/retry the run so the model picks a different strategy
    result = agent.run(task)

Prevention

Design tools to return error strings instead of raising.
Add timeouts and retries inside tools that call external APIs.
Handle expected edge cases (missing files, empty results) in tool code.

When it happens

Trigger: A tool's body raises at runtime — HTTP errors in a web_search wrapper, KeyError from unexpected arguments, file-not-found in a filesystem tool — during process_single_tool_call within agent.run.

Common situations: Third-party API tools hitting rate limits or auth errors; tools with unhandled edge cases; transient network failures while the agent is mid-run.

Related errors

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/4ea58959a8846310. Report an issue: GitHub.

Appendix: source

Thrown at src/smolagents/agents.py:1502

            # Call tool with appropriate arguments
            if isinstance(arguments, dict):
                return tool(**arguments) if is_managed_agent else tool(**arguments, sanitize_inputs_outputs=True)
            else:
                return tool(arguments) if is_managed_agent else tool(arguments, sanitize_inputs_outputs=True)

        except Exception as e:
            # Handle execution errors
            if is_managed_agent:
                error_msg = (
                    f"Error executing request to team member '{tool_name}' with arguments {str(arguments)}: {e}\n"
                    "Please try again or request to another team member"
                )
            else:
                error_msg = (
                    f"Error executing tool '{tool_name}' with arguments {str(arguments)}: {type(e).__name__}: {e}\n"
                    "Please try again or use another tool"
                )
            raise AgentToolExecutionError(error_msg, self.logger) from e


class CodeAgent(MultiStepAgent):
    """
    In this agent, the tool calls will be formulated by the LLM in code format, then parsed and executed.

    Args:
        tools (`list[Tool]`): [`Tool`]s that the agent can use.
        model (`Model`): Model that will generate the agent's actions.
        prompt_templates ([`~agents.PromptTemplates`], *optional*): Prompt templates.
        additional_authorized_imports (`list[str]`, *optional*): Additional authorized imports for the agent.
        planning_interval (`int`, *optional*): Interval at which the agent will run a planning step.
        executor ([`PythonExecutor`], *optional*): Custom Python code executor. If not provided, a default executor will be created based on `executor_type`.
        executor_type (`Literal["local", "blaxel", "e2b", "modal", "docker"]`, default `"local"`): Type of code executor.
        executor_kwargs (`dict`, *optional*): Additional arguments to pass to initialize the executor.
        max_print_outputs_length (`int`, *optional*): Maximum length of the print outputs.
        stream_outputs (`bool`, *optional*, default `False`): Whether to stream outputs during execution.
        use_structured_outputs_internally (`bool`, default `False`): Whether to use structured generation at each action step: improves performance for many models.

View on GitHub (pinned to 30bb116109)