smolagents

Hugging Face's minimal Python agent library built around code actions: a CodeAgent writes Python that an AST-walking interpreter or a remote sandbox runs, with a ToolCallingAgent for JSON tool calls, any model backend, MCP and Hub tools, and hierarchical managed agents.

Contents

smolagents is Hugging Face’s open-source (Apache-2.0) Python library for building agents. It is deliberately small: the core agent logic is about a thousand lines (guided tour, README). Its defining idea is the code agent. Instead of emitting a JSON tool call each step, the model writes a Python snippet that calls tools as functions, and an interpreter runs it. smolagents launched on 2024-12-31 as the replacement for the deprecated transformers.agents (launch post). As of 2026-11-14 the latest release is 1.26.0 (2026-05-29, Python 3.10+) (PyPI). The API reference still labels it experimental and subject to change (reference). It sits inside the Hugging Face ecosystem: you can share tools and agents on the Hub and run models through Inference Providers, but it is model-agnostic.

Why code actions

The case for code comes from the CodeAct paper. Across 17 LLMs, writing actions as executable Python gave up to 20% higher success than JSON or text formats. It also let the agent self-debug from interpreter errors (CodeAct). Hugging Face’s docs give four reasons code beats JSON: you can compose tools (loops, conditionals, nesting), you can keep objects such as images or dataframes in variables, code is more general, and code is heavily represented in training data (intro guide). The README cites about 30% fewer steps, and so fewer LLM calls (README).

The strongest public evidence is Hugging Face’s Open Deep Research reproduction. A CodeAgent scored 55.15% on GAIA validation (benchmarks). The same agent with JSON actions averaged about 33%, and OpenAI Deep Research reported 67.36% (Open Deep Research). See deep research agents.

Microsoft Agent Framework later adopted the same pattern as an opt-in execute_code tool (MAF CodeAct); see Microsoft Agent Framework. smolagents differs by making code the native action format.

The docs also argue against agents where they aren’t needed. They describe an agency spectrum: processor, then router, tool call, multi-step agent, multi-agent, and finally code agent. If a fixed workflow covers the requests, write it as plain code (intro guide). This matches the guidance on agent design patterns.

Architecture: the MultiStepAgent loop

Every agent subclasses MultiStepAgent, which runs a ReAct loop over a step-structured memory (intro guide):

flowchart TD
  T["run(task)"] --> M["Memory: SystemPromptStep + TaskStep"]
  M --> P{"planning_interval reached?"}
  P -- "yes" --> PL["PlanningStep: update facts + plan"] --> W
  P -- "no" --> W["write_memory_to_messages()"]
  W --> L["Model call"]
  L --> X{"Agent type"}
  X -- "CodeAgent" --> C["Parse code block -> executor runs it (tools = Python functions)"]
  X -- "ToolCallingAgent" --> J["Parse JSON tool call(s) -> run tools (parallel up to max_tool_threads)"]
  C --> A["ActionStep: code/tool calls, observations, errors"]
  J --> A
  A --> CB["step_callbacks(step, agent)"]
  CB --> F{"final_answer called and final_answer_checks pass?"}
  F -- "yes" --> R["Return answer"]
  F -- "no, and step < max_steps" --> P

Diagram follows the loop described in the intro guide and API reference.

Two details matter in practice:

  • Termination happens when the model calls final_answer(...) or the run hits max_steps (default 20). final_answer_checks are validators that can reject a final answer and keep the loop going (guided tour). This is a cheap built-in hook for verification.
  • Errors are observations. A code error is logged on the ActionStep and fed back to the model, which usually fixes it on the next step (inspect runs). This is the self-debugging behaviour CodeAct describes.

Key APIs and parameters

AreaAPI / parameterNotes
AgentsCodeAgent, ToolCallingAgent (both MultiStepAgent)ToolCallingAgent uses native function calling
Loop controlmax_steps=20, planning_interval, instructions, final_answer_checks, step_callbacksreturn_full_result returns token/step details
Code executionadditional_authorized_imports, executor_type (local default, e2b, docker, modal, blaxel), executor_kwargs, max_print_outputs_lengthSubmodules must be authorised explicitly or with pkg.*
Generationstream_outputs, use_structured_outputs_internally, code_block_tagsStructured generation per step is optional (structured outputs)
Runrun(task, stream, reset, images, additional_args, max_steps)additional_args injects Python objects (e.g. a dataframe) into the run; reset=False continues memory
Multi-agentmanaged_agents=[...] + name/description on sub-agentsHierarchical only
Sharingsave(), push_to_hub(), from_hub(..., trust_remote_code=True)Saves agent.json, prompt.yaml, tools, app.py

Sources: API reference, guided tour.

Models. The model classes are InferenceClientModel (HF Inference Providers), LiteLLMModel (100+ providers), OpenAIModel, AzureOpenAIModel, AmazonBedrockModel, and the local backends TransformersModel and MLXModel. Extra keyword arguments pass through to the completion call. Local models served by Ollama via LiteLLM need a context larger than Ollama’s 2048-token default (guided tour). See local LLMs and context window.

Tools. You can define a tool in two ways: the @tool decorator, which needs type hints and an Args: docstring, or a Tool subclass with name, description, inputs, output_type and forward. Tool metadata is rendered into the system prompt (guided tour, tools docs). Tools can also come from other sources (tools docs):

  • MCP servers, through MCPClient or ToolCollection.from_mcp, over stdio or Streamable HTTP (the docs’ multi-server example also passes an SSE URL). MCPClient accepts a list of servers.
  • Gradio Spaces, through Tool.from_space.
  • LangChain, through Tool.from_langchain.
  • The Hub, through load_tool(..., trust_remote_code=True).

With structured_output=True, MCP outputSchema is injected into the CodeAgent prompt so the model knows the shape of a tool’s result before it writes code against it. This is off by default today, and the docs say the default will change later. See MCP in practice.

Memory and observability. Memory is a list of step objects (agent.memory.steps) that you can read and edit. Callbacks can prune it, for example by dropping old browser screenshots to cut tokens. agent.step() lets you drive the loop yourself (memory docs). That is the hook for hand-rolled context engineering. Synthesis: none of the docs cited here describe a persistence layer (no checkpointer or session store), so memory lives in-process unless you serialise memory.steps yourself. Tracing uses OpenTelemetry: the OpenInference SmolagentsInstrumentor sends spans to Phoenix or Langfuse, and MLflow offers its own one-line mlflow.smolagents.autolog() (inspect runs).

Security model and failure modes

The default executor is the LocalPythonExecutor. It does not run exec(). It walks the AST one operation at a time and enforces these limits (secure execution):

  • imports are blocked unless authorised, and submodules are blocked unless authorised separately;
  • the total number of operations is capped;
  • undefined operations raise errors.

Both the docs and the README say plainly that it is not a security sandbox (README). Authorised packages can still be abused; an image library, for example, could fill a disk. The docs list four threats: plain model error, a compromised model, prompt injection from browsed content, and abuse of publicly exposed agents (secure execution).

There are two remote options:

Snippets in sandbox (executor_type="e2b"/"docker"/"modal"/"blaxel")Whole agent in sandbox
What goes remoteOnly generated code; model calls stay localAgent loop, model calls, tools
SecretsStay outside the sandboxAPI keys must enter the sandbox
Multi-agentNot supported (no managed agents)Supported
SetupOne parameterMore setup

Source: secure execution. Call cleanup() or use the agent as a context manager so sandboxes are torn down. E2B runs each sandbox in its own Firecracker microVM with egress controls (E2B). See code execution sandboxes.

Other failure modes:

  • Code agents are less predictable. They produce syntax and runtime errors, and only the code they actually run can be audited. The docs recommend ToolCallingAgent for atomic dispatch where validated arguments matter (guided tour).
  • Approval is coarse. As MAF’s CodeAct docs note for the same pattern, approval covers a whole program rather than each side effect (MAF CodeAct). smolagents has no built-in per-tool human-in-the-loop interrupt; the closest is agent.interrupt() or a callback (guided tour).
  • Hub loading runs remote code. from_hub and load_tool need trust_remote_code=True (the docs’ ToolCollection.from_mcp examples pass it too), and stdio MCP servers run code on your machine (tools docs).
  • Too many tools overwhelm weaker models (tools docs).
  • Maintenance signal. As of 2026-11-14 there had been no PyPI release since 2026-05-29 (commits were still landing), with about 430 open issues and 650 open PRs (README). Synthesis: pin versions and expect to fork or patch.

Comparison

smolagentsLangGraphOpenAI Agents SDKClaude Agent SDKMicrosoft Agent FrameworkMastra
LanguagePythonPython, JSPython, TSPython, TS.NET, PythonTypeScript
Native actionPython code (or JSON)Tool calls in graph nodesTool calls, handoffsClaude Code tools (bash, files)Tool calls; CodeAct opt-inTool calls
State / durabilityIn-memory step listCheckpointersSessionsSessionsWorkflow checkpoints, sessionsStorage-backed memory, suspendable workflows
Multi-agentManaged agents (hierarchy)Arbitrary graphsHandoffs, agents-as-toolsSubagentsWorkflows + orchestrationsSupervisor agents, workflows
ModelsAny (HF, LiteLLM, local)AnyOpenAI-firstClaudeAny chat clientAny (AI SDK)

Sources: smolagents sources above, LangChain/LangGraph 1.0, OpenAI Agents SDK docs, Claude Agent SDK overview. Synthesis for the table’s framing: smolagents optimises for a small, readable loop and fewer steps per task. The heavier frameworks optimise for durable state, typed orchestration and enterprise controls.

When to use it, and when not

Synthesis, grounded in the sources above:

  • Use it for research prototypes, data-analysis or deep-research agents where one step needs to chain many tool calls and transform results; for running open or local models (code actions narrowed the gap to closed models in Hugging Face’s tests, per the launch post); and for teaching, because the whole loop is readable.
  • Avoid it, or wrap it, when you need durable, resumable runs (durable agent execution), per-action approval, multi-tenant production with strict audit, or TypeScript/.NET stacks. In those cases LangGraph, MAF, Mastra or the vendor SDKs fit better. If you keep it, run it in a remote sandbox, pin the version, and add tracing from the first day.

Sources

Suggest changes →