Building Powerful AI Agents with smolagents: A Minimalist Approach

Andreas Nigg
Andreas Nigg · Co-Founder, Pondhouse Data
Published Updated 7 min read
Building Powerful AI Agents with smolagents: A Minimalist Approach
On this page

smolagents is a minimal Python library from Hugging Face for building AI agents in a few lines of code. Its core agent logic fits in about 1,000 lines, and its CodeAgent writes its actions as Python code instead of JSON tool calls. This post shows how to run a first smolagents agent, how code agents work, how to sandbox their code, and which practices and settings make agents more reliable.

If you've followed our previous posts on AI agents, you know we think frameworks often add unnecessary complexity to what should be a straightforward process. We've shown how to build agents from scratch without frameworks, but sometimes a minimal abstraction layer saves you from writing the same boilerplate over and over. That's the gap smolagents fills.

Update (November 2026): The code below targets smolagents 1.11 (March 2025). Since then, HfApiModel was renamed to InferenceClientModel in 1.14 and the old name has been removed, OpenAIServerModel is now called OpenAIModel (the old name still works as an alias), and DuckDuckGoSearchTool needs the toolkit extra: pip install "smolagents[openai,toolkit]". Claude 3 Opus, used in the model example, was retired on January 5, 2026, so put a current model ID there. The smolagents releases list all changes.

What makes smolagents different

Many frameworks hide the core agent functionality behind layers of abstraction. smolagents keeps things simple. The entire agent logic fits in ~1,000 lines of code, so you can inspect it and understand what's happening under the hood.

Code execution is a first-class feature: agents write actions as Python code snippets rather than structured tool calls (more on that below). smolagents is model-agnostic and works with virtually any LLM from OpenAI, Anthropic, Hugging Face, or local models. It handles text, vision, video and even audio inputs, similar to what we explored in our analyzing images with GPT-4o guide. And it can use tools from LangChain (which you can generate from any Python SDK), Anthropic's MCP (see our guide on building an MCP server with FastMCP), or even Hugging Face Spaces.

Let's see in practice how smolagents balances simplicity and power.

Getting started with smolagents

To warm up, let's run a simple agent.

First, install the package with the OpenAI extra:

1pip install "smolagents[openai]"

Then define your agent, give it the tools it needs, and run it:

1import os
2
3from smolagents import CodeAgent, DuckDuckGoSearchTool
4from smolagents import OpenAIServerModel
5
6model = OpenAIServerModel(
7 model_id="gpt-4o",
8 api_base="https://api.openai.com/v1",
9 api_key=os.environ["OPENAI_API_KEY"],
10)
11
12agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)
13
14answer = agent.run("What's the population in New York? What was it in 1980?")
15print(answer)

That's it! The agent will:

  1. Parse the question
  2. Decide to search for New York's population today and in 1980
  3. Write and execute Python code to calculate the answer
  4. Return a complete, well-reasoned response

Note: By default, smolagents prints a lot of debug information, which helps you understand what's happening at each step. You can turn it down by setting verbosity_level=LogLevel.ERROR in the agent constructor.

How smolagents code agents work, and why they beat JSON tool calls

Traditional agents use structured JSON for tool calls. The smolagents CodeAgent writes its actions as Python code snippets instead. Code is particularly handy when an agent works with complex data structures, like the ones we dealt with when creating knowledge graphs with Neo4j. For example, if your question was about the speed of a leopard and the length of the Pont des Arts bridge in Paris, the agent might generate code like this:

1# The agent might generate code like this:
2requests_to_search = ["leopard top speed", "pont des arts length paris"]
3for request in requests_to_search:
4 print(f"Searching for: {request}")
5 results = web_search(request)
6 print(f"Results: {results}")
7
8# Then calculate the answer
9leopard_speed = 58 # km/h from search results
10bridge_length = 155 # meters from search results
11seconds_to_cross = (bridge_length / 1000) / (leopard_speed / 3600)
12print(f"A leopard would cross Pont des Arts in {seconds_to_cross:.2f} seconds")

Research shows that code actions:

  • Use 30% fewer steps (and thus 30% fewer LLM calls)
  • Achieve higher performance on difficult benchmarks
  • Provide more flexibility in how tools are used

See here ("Executable Code Actions Elicit Better LLM Agents"), here ("DynaSaur: Large Language Agents Beyond Predefined Actions") and here ("If LLM Is the Wizard, Then Code Is the Wand", a survey on how code empowers LLM agents).

Security options for code execution in smolagents

Executing LLM-generated code can be (well, is) a security concern, so smolagents gives you several options:

  1. A secure Python interpreter that runs code more safely in your own environment. Hugging Face wrote a new, restricted Python interpreter that only allows importing whitelisted modules, and even only whitelisted submodules. This is the default behavior.
  2. Sandboxed environments using E2B or Docker, which execute the agent code in remote, more isolated environments. You pick one with the executor_type argument.
  3. The ability to review code before execution.
1# Using a sandboxed environment
2# Requires `pip install "smolagents[e2b]"` and an E2B API key
3from smolagents import CodeAgent, DuckDuckGoSearchTool
4
5agent = CodeAgent(
6 tools=[DuckDuckGoSearchTool()],
7 model=model,
8 executor_type="e2b"
9)

smolagents compared with raw implementations and large frameworks

If you've read our previous post on building agents from scratch, you might wonder why use a framework at all. It comes down to balance:

ApproachProsCons
Raw ImplementationComplete control, No dependenciesRepetitive boilerplate, Reinventing the wheel
smolagentsMinimal abstraction, Transparent code, FlexibleSmall learning curve
Large FrameworksMany pre-built componentsComplex abstractions, Hard to debug, Less flexible

smolagents handles the non-trivial parts (like keeping code formats consistent across the system prompt, the parser and the execution) and keeps everything else transparent and accessible.

The Microsoft Agent Framework sits at the other end of the scale: more structure, plus OpenTelemetry tracing, durable workflows and Entra ID authentication for enterprise deployments.

Model compatibility of smolagents

smolagents works with virtually any LLM. Anthropic and Ollama models go through LiteLLMModel, which needs pip install "smolagents[litellm]":

1# Using OpenAI
2from smolagents import CodeAgent, OpenAIServerModel
3agent = CodeAgent(tools=[...], model=OpenAIServerModel(model_id="gpt-4o"))
4
5# Using Anthropic via LiteLLM
6from smolagents import CodeAgent, LiteLLMModel
7agent = CodeAgent(tools=[...], model=LiteLLMModel(model_id="anthropic/claude-3-opus-20240229"))
8
9# Using local models via Ollama and LiteLLM
10from smolagents import CodeAgent, LiteLLMModel
11agent = CodeAgent(tools=[...], model=LiteLLMModel(model_id="ollama_chat/llama3", api_base="http://localhost:11434"))
12
13# Using 100+ LLMs via LiteLLM
14from smolagents import CodeAgent, LiteLLMModel
15agent = CodeAgent(tools=[...], model=LiteLLMModel(model_id="gpt-4o"))

Sharing smolagents agents on the Hugging Face Hub

One of the most useful features of smolagents is that you can share your agents on the Hugging Face Hub:

1# Save your agent to Hub
2agent.push_to_hub("username/my_agent")
3
4# Load an agent from Hub
5from smolagents import CodeAgent
6# trust_remote_code=True is required, because loading the agent runs code from the Hub
7agent = CodeAgent.from_hub("username/my_agent", trust_remote_code=True)

The smolagents command line interface

smolagents also ships two CLI commands, smolagent for general-purpose agents and webagent for web browsing:

1# Run a general-purpose agent
2smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7." \
3--model-type "HfApiModel" --model-id "Qwen/Qwen2.5-Coder-32B-Instruct" \
4--imports pandas numpy --tools web_search
5
6# Run a specialized web browsing agent
7webagent "go to xyz.com/men, get to sale section, click the first clothing item you see. Get the product details, and the price, return them." \
8--model-type "LiteLLMModel" --model-id "gpt-4o"

Note: To run the web agent, you need to install the helium package.

Best practices for building effective agents with smolagents

A few principles make a big difference in how well smolagents agents perform. We cover more of them in building high-quality AI agent systems.

Simplify your agent workflow

The best agentic systems are often the simplest ones. Giving an LLM agency introduces some risk of errors, so keep the workflow simple.

Reduce the number of LLM calls. Whenever possible, group multiple tools into one: instead of separate "travel distance API" and "weather API" calls, create a single "return_spot_information" function.

Prefer deterministic functions over agentic decisions where you can. That lowers costs, latency and error risk at the same time.

Improve the information flow to the LLM

Think of your LLM engine as an intelligent robot trapped in a room, with notes passed under the door as its only contact with the outside world. It won't know anything you don't explicitly tell it.

For example, here's a poorly designed weather tool:

1def get_weather_api(location: str, date_time: str) -> str:
2 """Returns the weather report."""
3 lon, lat = convert_location_to_coordinates(location)
4 date_time = datetime.strptime(date_time, '%m/%d/%y %H:%M:%S')
5 return str(get_weather_report_at_coordinates((lon, lat), date_time))

And here's a better version:

1def get_weather_api(location: str, date_time: str) -> str:
2 """
3 Returns the weather report.
4
5 Args:
6 location: the name of the place, formatted as "Place, City, Country"
7 date_time: the date and time, formatted as '%m/%d/%y %H:%M:%S'
8 """
9 lon, lat = convert_location_to_coordinates(location)
10 try:
11 date_time = datetime.strptime(date_time, '%m/%d/%y %H:%M:%S')
12 except Exception as e:
13 raise ValueError("Date format error: " + str(e))
14 temperature, rain_risk, wave_height = get_weather_report_at_coordinates((lon, lat), date_time)
15 return f"Weather for {location}: {temperature}°C, rain risk {rain_risk*100:.0f}%, waves {wave_height}m"

The improved version states the expected input formats, handles errors better and returns a structured output.

Tips when working with smolagents

Enable planning mode

smolagents has a planning feature that lets agents reflect on their progress and plan their next steps:

1agent = CodeAgent(
2 tools=[search_tool, image_generation_tool],
3 model=HfApiModel(model_id="Qwen/Qwen2.5-72B-Instruct"),
4 planning_interval=3 # Activate planning every 3 steps
5)

This adds a planning step in which the LLM updates its knowledge and reflects on the next steps, without making any tool calls.

Reduce logging output

By default, smolagents logs a lot of information to help you understand what's happening at each step. If that's too much, reduce the verbosity level:

1from smolagents import LogLevel
2
3agent = CodeAgent(
4 tools=[search_tool, image_generation_tool],
5 model=model,
6 verbosity_level=LogLevel.ERROR
7)

Console logs help during development. In production, Langfuse's smolagents integration records each agent step as a trace; our Langfuse guide covers setting up Langfuse itself.

Change the final answer output format

A smolagents agent uses the FinalAnswerTool to generate the final, user-facing answer. By default, this tool tries to produce a natural language answer. However, we found that the LLM sometimes answered with a JSON object.

Changing the output format is easy:

1agent = CodeAgent(
2 tools=[DuckDuckGoSearchTool()],
3 model=model,
4)
5
6# Make sure to include the `{{task}}` placeholder
7agent.prompt_templates["final_answer"][
8 "post_messages"
9] = "Based on the above, please provide an answer to the following user task: {{task}}. Always answer in user-readable text, don't use json."

Streaming the agent output

LLM outputs are generally slow, so chat applications often stream the answer as it is generated. The user sees a response immediately, even though the full answer isn't available yet.

smolagents can stream the output too. Set the stream parameter to True and you get a generator that yields each step (planning and action steps) as soon as it finishes, followed by the final answer:

1result = agent.run("What's the population in New York? What was it in 1980?", stream=True)
2for step in result:
3 print(step)

Interested in building high-quality AI agent systems?

We prepared a comprehensive guide based on cutting-edge research for how to build robust, reliable AI agent systems that actually work in production. This guide covers:

  • Understanding the 14 systematic failure modes in multi-agent systems
  • Evidence-based best practices for agent design
  • Structured communication protocols and verification mechanisms

Conclusion

smolagents strikes a good balance between simplicity and power. It handles the tricky parts of agent development, such as prompt, parser and execution formats, while keeping everything transparent.

Its code-based actions make agents more flexible and efficient than structured tool calls, with fewer steps and higher success rates on hard benchmarks.

If larger frameworks frustrate you, or you're tired of writing the same boilerplate for every agent project, smolagents is worth a try. Start with the CodeAgent example above, then add planning and a sandbox once the agent does real work.

Further reading

Andreas Nigg

About the author

Andreas Nigg

Co-Founder, Pondhouse Data

Andreas has spent more than eight years building data applications. At Pondhouse Data he designs and ships AI systems and integrates them into complex, real-world environments.