huggingface/smolagents · error · AgentToolExecutionError

Error executing tool '{tool_name}' with arguments {str(argum

Error message

Error executing tool '{tool_name}' with arguments {str(arguments)}: {type(e).__name__}: {e}

What it means

If validate_tool_arguments raises anything other than ValueError/TypeError (e.g. an introspection error while building the JSON schema for the tool's signature), execute_tool_call wraps it into AgentToolExecutionError with a message naming the tool, arguments, and exception type. It signals the tool itself is not cleanly introspectable rather than the arguments being wrong.

Source

Thrown at src/smolagents/agents.py:1481

        # Check if the tool exists
        available_tools = {**self.tools, **self.managed_agents}
        if tool_name not in available_tools:
            raise AgentToolExecutionError(
                f"Unknown tool {tool_name}, should be one of: {', '.join(available_tools)}.", self.logger
            )

        # Get the tool and substitute state variables in arguments
        tool = available_tools[tool_name]
        arguments = self._substitute_state_variables(arguments)
        is_managed_agent = tool_name in self.managed_agents

        try:
            validate_tool_arguments(tool, arguments)
        except (ValueError, TypeError) as e:
            raise AgentToolCallError(str(e), self.logger) from e
        except Exception as e:
            error_msg = f"Error executing tool '{tool_name}' with arguments {str(arguments)}: {type(e).__name__}: {e}"
            raise AgentToolExecutionError(error_msg, self.logger) from e

        try:
            # 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"

View on GitHub (pinned to 30bb116109)

Solutions

1. Read the exception type in the message; simplify the tool signature to plain builtin types (str, int, bool, list, dict).
2. Resolve forward references or move custom type imports to module level so introspection succeeds.
3. Wrap the raw function in smolagents' @tool decorator with simple annotations.

Example fix

# before
def process(items: list[MyCustomType]) -> str: ...

# after
def process(items_json: str) -> str:
    items = json.loads(items_json)
    ...

import inspect
from smolagents.tool_validation import validate_tool_arguments

try:
    validate_tool_arguments(tool, sample_args)
except Exception as e:
    if not isinstance(e, (ValueError, TypeError)):
        print('tool signature not introspectable:', inspect.signature(tool))

from smolagents.exceptions import AgentToolExecutionError

try:
    result = agent.run(task)
except AgentToolExecutionError as e:
    if 'Error executing tool' in str(e):
        # inspect type name in message; fix tool signature if introspection-related
        raise

When it happens

Trigger: Passing a tool whose signature contains types that break schema generation (unresolvable forward references, exotic annotations) — the exception escapes validation as a non-ValueError/TypeError.

Common situations: Tools defined with `from __future__ import annotations` and unresolved string annotations; tools using custom classes as parameter types; version mismatches in the inspection layer.

Related errors

• Error during jinja template rendering: {type(e).__name__}: {
• Cannot specify both 'messages' and 'steps' parameters. Use '
• The 'system_prompt' property is read-only. Use 'self.prompt_
• Agent name '{name}' must be a valid Python identifier and no
• Each tool or managed_agent should have a unique name! You pa

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