Smolagents

smolagents

Verified against huggingface/smolagents @ 30bb1161 (1.27.0.dev0, main) and tag v1.26.0 — the API surface below is identical in both. Agents are synchronous; there is no arun. Offload to a thread (anyio.to_thread.run_sync(agent.run, task)) inside async servers.

Extras gate everything: [toolkit] for WebSearchTool/VisitWebpageTool and add_base_tools=True; [litellm] [openai] [transformers] [vllm] [mlx-lm] [bedrock] for the matching model class; [e2b] [docker] [modal] [blaxel] for sandboxes; [mcp] for MCPClient; [telemetry] for OTel. pip install 'smolagents[all]' for everything.

API currency — check these before trusting any tutorial

Most third-party smolagents material predates these renames. Names in the left column do not exist; importing them raises ImportError.

Still exported and current: OpenAIServerModel, AzureOpenAIServerModel, AmazonBedrockServerModel — these are plain aliases of OpenAIModel / AzureOpenAIModel / AmazonBedrockModel. Either name works; prefer the short one in new code.

Pick the agent class

Default to CodeAgent when steps compose; use ToolCallingAgent when each step is one API call and you want no code execution in the loop at all.

from smolagents import CodeAgent, InferenceClientModel, WebSearchTool

agent = CodeAgent(
    tools=[WebSearchTool()],
    model=InferenceClientModel(),          # defaults to Qwen/Qwen3-Next-80B-A3B-Thinking
    additional_authorized_imports=["pandas"],
    max_steps=20,                          # default
    planning_interval=3,                   # re-plan every 3 steps; omit to disable planning
)
result = agent.run("...", additional_args={"df": df})   # additional_args land in the exec namespace

Model backends

All take model_id plus arbitrary completion kwargs (temperature, max_tokens, …) forwarded to the provider. REMOVE_PARAMETER as a value strips a parameter the library would otherwise send.

Tools

Two forms. @tool for a plain function; subclass Tool when setup is expensive (setup() runs lazily on first call, not at init).

from smolagents import tool, Tool

@tool
def most_downloaded(task: str) -> str:      # return type hint is MANDATORY
    """Return the most-downloaded Hub model for a task.

    Args:
        task: pipeline tag, e.g. "text-classification".
    """                                      # every arg needs an Args: line
    ...

class ModelDownloadTool(Tool):
    name = "model_download_tool"             # must be a valid Python identifier
    description = "..."                      # baked into the system prompt — write it for the LLM
    inputs = {"task": {"type": "string", "description": "..."}}
    output_type = "string"
    def forward(self, task: str) -> str: ...

Validation runs at instantiation, not class definition, so a broken Tool subclass fails at ModelDownloadTool(). Loading external tools: Tool.from_hub(..., trust_remote_code=True) and ToolCollection.from_mcp({"url": ..., "transport": "streamable-http"}, trust_remote_code=True) — both execute code they fetch; treat trust_remote_code=True as running an untrusted package.

Tool quality dominates agent quality. Put the argument format in the description ('%m/%d/%y %H:%M:%S', not "a date"), print() diagnostics inside forward, and raise errors that say how to fix the call — the traceback goes into the agent's memory and is what it self-corrects from. Merging two tools that are always called together removes an LLM round trip and a failure point.

Sandboxing — the part that matters

CodeAgent runs LLM-generated Python. LocalPythonExecutor (the default) is an AST interpreter, not a sandbox — its own docstring says so: "It is not a security sandbox: for isolated execution of untrusted code, use a remote executor." What it does block, verified:

Default allowlist is 11 stdlib modules: collections datetime itertools math queue random re stat statistics time unicodedata. Submodules are not implied — authorize numpy.random explicitly, or numpy.* for the whole subtree. What it does not stop: resource exhaustion through an import you allowed (Pillow writing a million images), or a novel escape. Anything reachable from the process — env vars, ~/.aws, the network, the repo you are standing in — is in blast radius.

The moment the agent reads the open web, an issue tracker, or user-supplied documents, prompt injection is a live path to code execution — move off "local".

with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="e2b") as agent:
    agent.run("...")      # the context manager (or agent.cleanup()) tears the sandbox down

Remote executors only sandbox the code snippets, not the agent. Secrets are deliberately not shipped to the sandbox, which is why executor_type != "local" + managed_agents raises Exception: Managed agents are not yet supported with remote code execution. To isolate a multi-agent system, run the whole program inside the sandbox instead and pass HF_TOKEN in as an env var.

Multi-agent

A managed agent is any agent with name and description — the manager sees it as a tool.

web_agent = CodeAgent(tools=[WebSearchTool()], model=model,
                      name="web_search_agent",
                      description="Runs web searches. Give it your query as an argument.")
manager = CodeAgent(tools=[], model=model, managed_agents=[web_agent])

name must be a valid Python identifier, and names must be unique across tools and managed agents. Missing either attribute raises AssertionError: All managed agents need both a name and a description!. Set provide_run_summary=True on the child to return its reasoning, not just its answer. Separate memories are the point — keep scraped page content out of the manager's context.

Memory, steps, control

agent.memory.steps is a list of TaskStep | ActionStep | PlanningStep; ActionStep carries model_output, code_action, observations, observations_images, error.

Failure modes

Scope boundaries

This skill does not claim generic "build me an agent" requests — it fires on smolagents specifically.

References

• https://huggingface.co/docs/smolagents/ + guided_tour · tutorials/secure_code_execution · tutorials/building_good_agents · tutorials/tools · tutorials/memory · tutorials/inspect_runs · examples/multiagents · reference/{agents,models,tools,python_executors}
• Source of truth for every claim above — https://github.com/huggingface/smolagents: src/smolagents/{agents,models,tools,local_python_executor,remote_executors}.py and docs/source/en/