Smolagents: How Code Agents Work and When to Use Them

Choose smolagents when your Python agent needs to combine tools and calculations dynamically, and you can give that code a controlled place to run. Hugging Face provides 2 agent classes, CodeAgent and ToolCallingAgent; the choice is whether the model expresses its next action as Python or as a structured tool call. Its minimalism helps a bounded problem solver, but does not remove your responsibility for durable workflows, permissions or isolation.

Verified against the live Hugging Face, LangChain and OpenAI documentation on 31 October 2026. The recommendations below compare action composition, workflow control and execution boundaries. They are architectural judgments, not performance benchmarks.

What smolagents Does With Python

smolagents is Hugging Face's open-source Python library for building agents whose actions can be executable code. An agent is a model-driven loop that chooses an action, observes what happened and decides what to do next. CodeAgent uses Python to express that action; ToolCallingAgent uses structured tool calls. Both accept a model and a toolbox. Hugging Face agent reference.

Think of CodeAgent as a researcher allowed to write a short script between observations. It can ask a permitted tool for records, transform the returned data and calculate an answer. You supply the capabilities and constraints; the model supplies some of the glue connecting them.

That is different from an assistant whose finished product is a code file for you to review. Here, the generated code is how the agent takes its next action.

The useful comparison is which part of your application needs flexibility:

The latter two rows describe the documented emphasis of LangGraph and the OpenAI Agents SDK, not exclusive capabilities. The decision turns on where you want the framework to provide structure.

smolagents CodeAgent: Let the Model Compose Actions

CodeAgent earns its place when the intermediate work is easier to express in Python than in a fixed menu of calls. Hugging Face documents loops, conditionals and combinations of tools as strengths, alongside the need to handle syntax errors, exceptions and unexpected behavior. Guided tour.

For example, imagine a developer investigating inconsistent inventory records. A read-only lookup tool returns candidate records. The agent may need to normalize names, group similar entries and total a field before deciding which records need another lookup. Python is a natural language for those intermediate operations.

The execution result becomes evidence for the next model decision. A failed calculation is an observation the agent can respond to, not proof it will successfully repair itself.

ToolCallingAgent: Keep Actions Within a Defined Menu

ToolCallingAgent is the better starting point when your operations already have clear contracts. It emits structured JSON calls with tool names and arguments rather than synthesizing Python actions. Hugging Face's comparison.

A support helper that looks up an order and retrieves a policy may need nothing more. Let ordinary application code do the predictable transformations. Introducing generated Python for a workflow that already fits clean functions creates another failure mode without an obvious payoff.

Structured calls still need authorization. A correctly shaped request to cancel an order can be the wrong action for that customer. The schema tells your program what was requested; your application decides whether it is allowed.

Tools and Models Are Separate Choices

Keep the toolbox narrow and choose the model independently. That separation is the practical appeal of smolagents: you can change how the agent reasons without redefining every business capability.

Tools Are Functions With a Usable Contract

A smolagents tool wraps a function with a name, description, input metadata and output type. The @tool decorator suits simple functions with type hints and a useful docstring. For a more involved tool, subclass Tool and put its execution logic in forward. Tools guide.

For an inventory assistant, prefer a capability such as “look up records in the permitted catalog” to unrestricted database access. Put tenant checks, query restrictions and response limits inside the implementation. A persuasive prompt cannot replace those checks.

Tools can also come from Model Context Protocol, or MCP, a standard interface for exposing tools to model applications, as well as adapters for LangChain tools and Hugging Face Spaces. Reusing a tool does not establish that its implementation is trustworthy. Hugging Face explicitly requires trust_remote_code=True when loading Hub tools because they run custom code. Tool integration and loading documentation.

That is a code-review decision. Inspect the tool's implementation and dependencies before making it available to an agent.

Model Backends Do Not Determine the Sandbox

The current model reference documents several routes:

• InferenceClientModel connects through Hugging Face Inference Providers.
• LiteLLMModel uses LiteLLM's provider integration layer.
• TransformersModel runs a Transformers model locally.
• OpenAIModel connects to an OpenAI-compatible model server.

The guided tour also covers Ollama for local inference. These are backend choices, not promises that every model will handle code generation or tool selection equally well.

Keep two questions separate: where does the model run, and where does its generated Python run? A hosted model can drive a Docker executor. A local model can still generate unsafe actions. Moving inference onto your machine does not establish an execution boundary.

For reproducibility, configure your model explicitly once you move beyond the demonstration. Hugging Face notes that InferenceClientModel's default model can change. Model configuration.

A Small Worked Example From the Docs

Use the docs' arithmetic task to understand the execution path before adding tools. Hugging Face's introductory example asks for the sum of the numbers from 1 to 10 with an empty toolbox. The version below keeps that task and adds the Docker context-manager pattern from its sandbox guide. Original example, Docker execution setup.

1. 1

   Prepare the environment

   The installation guide requires Python 3.10 or newer and recommends a virtual environment. Docker must also be installed and running for this example. Installation guide.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Set HF_TOKEN in your environment using a Hugging Face token with permission to call Inference Providers. InferenceClientModel can read that variable automatically. Do not put the token in the script. Authentication behavior.

2. 2

   Run the documented task in Docker

   Save this as sum_agent.py:

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   Then run:

   python sum_agent.py

   The context manager handles sandbox cleanup when the block exits. This is an adaptation of the documentation, not an execution result from a test performed for this article.

3. 3

   Check the result and the boundary

   The expected mathematical answer is 55, calculated as 10 × 11 ÷ 2. The model chooses the Python it generates, so do not assume an exact transcript or identical wording on every run.

   tools=[] means no custom tools were supplied. It does not mean CodeAgent has lost the ability to execute Python. The executor setting is what moves that generated code into Docker.

For this fixed calculation, ordinary Python is the sensible application code. The example exists to expose the agent's mechanics. Add an agent when choosing the intermediate steps is part of the problem, not merely because the calculation can be described in English.

Code-Executing Agents Need a Sandbox

Treat generated Python as untrusted code and give it an explicit sandbox before exposing it to untrusted inputs. The default local executor is a restricted interpreter, not a guarantee that your host is isolated. Hugging Face identifies model mistakes, prompt injection and adversarial requests as risks. Secure code execution.

The local interpreter evaluates Python's abstract syntax tree, the parsed structure of the program, operation by operation. It restricts imports and submodules and caps operations. Those controls reduce exposure, but the dedicated security guide warns that local execution still carries risk. Authorizing an additional package expands what the generated program can reach.

The Sandbox Options Hugging Face Names

The current executor API supports Blaxel, E2B, Modal and Docker alongside the local executor. The configuration names below match the CodeAgent reference and the executor reference.

Choose the provider and credentials separately from these settings. The installation documentation lists the optional dependencies; installing an extra alone does not configure a deployment.

For an internal experiment, Docker can give you a concrete execution boundary to inspect. For a service handling untrusted requests, select the environment around the isolation, lifecycle and operational controls you need. The broader AI agent code sandbox comparison covers that infrastructure decision.

Sandboxing Snippets Is Not Sandboxing the Whole Agent

Decide what lives inside the boundary before adding more agents. Hugging Face distinguishes running generated snippets in a sandbox from running the entire agent system there. Its security guide warns that the snippet-only approach does not support managed agents, meaning agents that another agent calls as helpers. Moving the whole system inside requires more setup and may require supplying credentials. Sandbox approaches.

The consequence is architectural. If a future specialist needs to call a model from inside the execution environment, the original “send code, receive result” arrangement may no longer be enough. Review credential placement and tool dependencies when you change the deployment shape.

For a customer-facing service, define permitted files, network destinations and callable operations before the agent starts. Give each run only the access its task requires. Plan for timeout, cancellation and cleanup as ordinary execution paths, including when the model fails to finish.

When Minimalism Wins, and When It Does Not

Choose the framework around the hardest control problem in your application. A short initializer is useful, but the code you must write around it matters more.

smolagents vs LangGraph: Dynamic Actions or Durable Control

LangGraph is the stronger starting point when your process must persist, pause and resume through explicit business states. It is a low-level orchestration runtime for stateful workflows, with persistence and human-in-the-loop support. It can mix deterministic steps with model-driven ones, and does not require LangChain. LangGraph overview.

Consider a purchasing workflow that gathers evidence, waits for a manager and resumes after approval. The central problem is preserving the process and enforcing the permitted transition. Start with LangGraph if those requirements define the product.

Its wall is the workflow design you now own: states, transitions, persistence and the meaning of retrying a step. That effort is justified for the purchasing process. It can be unnecessary structure for a bounded research helper that reads data, computes an answer and stops.

Choose smolagents when the uncertainty is mainly which Python operations solve this task. Choose LangGraph when it is mainly how this process moves safely through durable states. This is a design recommendation, not a claim that either framework can only do one kind of work.

OpenAI Agents SDK: Handoffs, Checks and Traces

OpenAI Agents SDK is a better default when the application's center is specialist coordination and operational checks. Its handoffs transfer conversation ownership to another agent; its agents-as-tools pattern lets a manager retain responsibility for the response. Orchestration documentation.

For a customer-support assistant, a billing specialist taking over a conversation can be a clearer abstraction than a general Python problem solver. Built-in tracing records model calls, tool calls, handoffs and guardrails. Guardrails provide automated checks, while human-review mechanisms pause sensitive actions for a decision. Tracing, guardrails and review.

Its wall is still your application policy: deciding what deserves approval, implementing the tool correctly and handling interrupted work. These primitives do not write that policy for you. The SDK also documents sandbox-agent patterns, so smolagents does not have an exclusive claim to code execution.

Choose smolagents over it when Python action composition is the feature you need and a small loop is enough. Choose the Agents SDK when its coordination and review primitives match the application you are building. “Lightweight” alone does not settle that comparison.

For a wider shortlist, use the AI agent framework comparison. If you want an agent application to install rather than a library to build around, start with the open-source AI agent guide.

What Is Overhyped About Code Agents

A small framework does not make an unpredictable task predictable. Python's expressiveness is useful, but it cannot establish that the model selected the correct records, interpreted a unit correctly or respected a business rule.

Do not turn composability into a universal speed claim. Combining operations can change the shape of a run; the model, task, tool behavior and execution environment still determine the outcome. Measure your own task before choosing on performance.

There is also a concrete limit worth understanding: max_steps defaults to 20 in the current agent API. It bounds agent steps, not the resources consumed by an individual Python action. The API also exposes callbacks, managed agents and final-answer checks, so minimalism should not be confused with the absence of controls. Agent reference.

The operational conclusion is to set execution time and resource limits separately. A step ceiling cannot stand in for a sandbox policy, and a sandbox cannot stand in for a correct result.

What to Build Next Week

Start with a bounded, read-only task whose answer you can check independently. A Python developer evaluating smolagents could use a sanitized inventory export and a narrowly scoped lookup tool, then compare the agent's proposed discrepancies with known examples.

Record whether it selected the right records, used tools correctly, recovered from expected failures and stopped within your limits. Keep a deterministic baseline. If the task always follows the same path, write that path as ordinary code; Hugging Face's own guidance favors deterministic functions wherever possible. Building good agents.

Move ahead with CodeAgent when dynamic Python composition earns its complexity. Use ToolCallingAgent when a defined tool menu suffices. Wait on migration if your existing workflow already meets its requirements. Revisit the framework choice when persistent approvals or specialist handoffs become central.

Installation and Compatibility

Smolagents pip

Install the core library with pip install smolagents. Add the extras needed for your tools, models or execution environment. The worked example uses smolagents[docker].

HfApiModel smolagents

For new code, follow the current documentation's InferenceClientModel interface. Check old examples against the live model reference before copying their imports.

Smolagents docker

Install and start Docker, install the Docker extra, and select executor_type="docker". Configure the execution boundary for your workload; the setting alone is not a complete security policy.

Get practical AI build notes in the newsletter.