SmolAgents by Hugging Face: Build AI Agents in Less than 30 Lines

Happy New Year to the readers! As the first month of 2025 began, my curiosity to learn about AI Agents deepened, leading me to explore their vast potential and applications. Today, I have tried the SmolAgents open-source framework by Hugging Face. Let’s get started!

The year 2025 is said to be the year of AI Agents and Hugging Face recently launched the SmolAgents library. As the name suggests, it is quite small and by this I mean, it allows you to run powerful agents in a few lines of code. Its simplicity, Hub integrations, support for any LLMs and more make it the best fit for agentic workflows.

What is SmolAgents by Hugging Face?

SmolAgents is an innovative library designed to simplify the creation and execution of powerful agents. Developed by Hugging Face, it stands out for its minimalist approach, with the entire agent logic encapsulated in approximately 1,000 lines of code. This streamlined design ensures ease of use while maintaining robust functionality.

The library excels in supporting “Code Agents,” specialized agents capable of generating and executing code to accomplish user-defined tasks. For enhanced security, it facilitates execution within sandboxed environments like E2B. SmolAgents also offers traditional ToolCallingAgents, which utilize JSON or text-based actions.

With extensive integrations, SmolAgents works seamlessly with any large language model (LLM). It supports Hugging Face’s inference API, OpenAI, Anthropic, and others through LiteLLM. Additionally, it provides access to a shared tool repository via the Hugging Face Hub, making it versatile and adaptable for various applications. SmolAgents is a user-friendly gateway to advanced agent-based automation. 

Is it overwhelming for you? To understand the SmolAgents better, let’s see what Agents are:

What are Agents?

By definition, AI Agents are systems or programs capable of performing autonomous tasks on behalf of a user or another system. They achieve this by designing the workflows and utilizing external tools such as web searches, coding utilities, and more. 

At the core, AI Agents are powered by large language models (LLMs) that leverage tool integration on the backend to deliver real-time and up-to-date information. 

Essentially, agentic programs serve as the bridge between LLMs and the outside world, the ability to act and make decisions within a system. In simple terms, AI agents are programs where the outputs of an LLM determine how tasks are carried out.

When a system uses LLMs, it integrates their outputs into its workflow or code. The extent to which the LLM’s inputs influence decisions and actions within the system defines its agency agency.

Importantly, the agency isn’t an all-or-nothing concept. It exists on a spectrum—systems can give LLMs varying degrees of control, from minimal influence to near-complete autonomy.

Example of a Multi-step agent by Hugging Face

In a nutshell, an agent is a system that can perform complex tasks by leveraging multiple tools and adapting dynamically to various scenarios.

For instance, a multi-step agent can access a weather API to provide forecasts, a Google Maps API to calculate travel distances, an employee availability dashboard to check schedules, and more to pull relevant information from your knowledge base.

Until recently, traditional computer programs were limited to rigid, pre-defined workflows, relying heavily on layered if/else logic to manage complexity. These programs were designed for narrow tasks, like “the sum of these numbers.” However, most real-world problems—like planning a trip as in the example above—don’t neatly fit into these predetermined workflows.

Agentic systems break this limitation by enabling programs to handle the complexity and unpredictability of real-world tasks. They represent a major leap forward, allowing software to operate in dynamic and adaptable ways, much closer to how humans approach problem-solving.

Also read: Top 4 Agentic AI Design Patterns for Architecting AI Systems

Now, let’s talk about SmolAgents:

Key Features of SmolAgents

For simple agent tasks, writing your own code is often the best approach—it provides greater control and understanding of the system.

However, for more complex behaviours, like letting an LLM call tools (tool calling) or manage loops (multi-step agents), the additional structure becomes necessary:

• Tool calling: The agent’s output must follow a clear format (e.g., “Thought: I should call tool ‘get_weather’. Action: get_weather(Paris).”), which a parser processes. The system prompt should inform the LLM about this format.
• Multi-step agents: For tasks involving loops, the LLM needs tailored prompts based on previous iterations, which requires memory to maintain context.

Building such systems involves several key components working together seamlessly. First, an LLM serves as the core engine powering the agent’s decision-making and actions. Next, the agent requires a predefined list of accessible tools it can use to perform tasks. A parser is essential to process the LLM’s outputs, especially for extracting and executing tool calls. To ensure smooth communication, designers must carefully craft the system prompt to align with the parser and give the LLM clear instructions about the expected output format. Additionally, memory is crucial for maintaining context across multiple iterations, especially in multi-step processes. Finally, since LLMs can make mistakes, robust error logging and retry mechanisms are necessary to ensure the system remains reliable and efficient.

Integrating all these elements can be challenging, but SmolAgents offers a streamlined solution. SmolAgents provides foundational building blocks designed to tightly integrate these components, enabling developers to easily create efficient, reliable, and dynamic agentic systems without reinventing the wheel.

What SmolAgents Offers?

SmolAgents by Hugging Face offers:

Code Agents

LLMs expressing their tool actions as code is far superior to the current industry standard of using JSON snippets for tool calls. Here’s why:

1. Purpose-Built: Programming languages are designed to express computer actions efficiently. If JSON snippets were better, we’d write software directly in them—and the absurdity of that thought highlights the point.
2. Composability: Code allows nesting, abstraction, and reuse (e.g., defining functions), which JSON lacks. Try managing complex workflows in JSON—it’s a mess.
3. Object Management: Storing and manipulating outputs, like a generate_image result, is straightforward in code. JSON doesn’t natively support such handling.
4. Generality: Code expresses virtually anything you can make a computer do, whereas JSON is limited to predefined structures.
5. Training Corpus Compatibility: High-quality code already exists in LLM training datasets. Leveraging this wealth of knowledge aligns with how LLMs learn best.

Simply put, code is clearer, more flexible, and better suited for describing actions than JSON.

Local Python Interpreter

The CodeAgent operates by executing LLM-generated code within a custom environment. Instead of relying on the default Python interpreter, it utilizes a purpose-built LocalPythonInterpreter designed with security at its core. This custom interpreter ensures safety by implementing the following measures:

1. Controlled Imports: Only imports explicitly authorized by the user are permitted, reducing exposure to untrusted libraries.
2. Operation Limits: The interpreter enforces strict caps on the number of operations to prevent infinite loops or excessive resource consumption.
3. Predefined Actions Only: It restricts execution to a predefined set of operations, ensuring that no unexpected or unsafe code can be run.

These safeguards create a secure and predictable environment for running LLM-generated code.

E2B Code Executor

For enhanced security, SmolAgents integrates with E2B, a remote execution service that runs code in a sandboxed environment. This setup ensures that all code executes within an isolated container, preventing any impact on the local environment and providing robust protection.

Here’s how you can do it:

from smolagents import CodeAgent, VisitWebpageTool, HfApiModel
agent = CodeAgent(
    tools = [VisitWebpageTool()],
    model=HfApiModel(),
    additional_authorized_imports=["requests", "markdownify"],
    use_e2b_executor=True
)
agent.run("What was Abraham Lincoln's preferred pet?")

SmolAgents Hands-on Implementation

Here are 2 ways I have used SmolAgents:

Demo 1: Reasearch Agent Using SmolAgents

Here I am demonstrating how to set up and use a lightweight AI agent for task automation. The agent leverages a large language model (LLM) and a search tool to perform tasks requiring both computational understanding and external data lookup. By configuring different models and tools, the agent becomes adaptable for various applications, such as research, content generation, and question-answering. In this specific case, the agent is tasked with retrieving information about Analytics Vidhya, showcasing its ability to integrate AI reasoning with real-time data from the web.

!pip install smolagents

This command installs the SmolAgents library, which provides tools for building lightweight, efficient AI agents.

from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiModel
from smolagents.agents import ToolCallingAgent
from smolagents import tool, TransformersModel, LiteLLMModel
from typing import Optional

These imports bring in the core components of the SmolAgents library, including models, tools, and the CodeAgent class. Additionally, specific models (TransformersModel, LiteLLMModel, and HfApiModel) and tools like DuckDuckGoSearchTool are imported.

# Choose which LLM engine to use!
model = LiteLLMModel(model_id="gpt-4o", api_key = "Your API Key")

The code provides options for using different LLM engines, such as Hugging Face (HfApiModel), Transformers, or LiteLLMModel. In this instance, LiteLLMModel is selected with the GPT-4o model and an API key for authentication.

agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)
agent.run("Tell me about Analytics Vidhya")

The agent is assigned to gather information about “Analytics Vidhya.” It utilizes a chosen Large Language Model (LLM) in combination with the DuckDuckGo search tool to execute this task. By analyzing the externally retrieved data, the AI synthesizes and delivers a comprehensive response.

Output

Analytics Vidhya is a comprehensive platform for AI, Data Science, and Data
 Engineering professionals. It offers a range of courses, both free and paid,
 on Generative AI, Machine Learning, and more, along with structured learning
 paths and projects. It's also known for the AI & ML BlackBelt Plus
 Certification program designed to build globally recognized data scientists.
 The platform also provides a vibrant community with blogs, guides, and
 hackathons aimed at enhancing learning and networking opportunities.

Demo 2: Getting the Stock Price of Apple Inc. Using SmolAgents

Here I am demonstrating how to create a task-oriented agent using SmolAgents. The agent leverages an LLM backend to interpret a natural language query, selects the appropriate tools (like DuckDuckGoSearchTool or yfinance), and executes the query in a controlled and secure environment. The setup highlights the flexibility to switch between different LLMs and integrate external tools for diverse tasks, making it a robust framework for automated workflows.

!pip install smolagents
from smolagents import CodeAgent, DuckDuckGoSearchTool
from smolagents.agents import ToolCallingAgent
import yfinance as yf  # Ensure yfinance is imported
# Initialize the LLM model with the corrected string for the API key
model = LiteLLMModel(
   model_id="gpt-4o",
   api_key="Your_API_KEY"
)
# Define the agent with tools and imports
agent = CodeAgent(
   tools=[DuckDuckGoSearchTool()],
   additional_authorized_imports=["yfinance"],
   model=model
)
# Run the agent to fetch the stock price of Apple Inc.
response = agent.run(
   "Fetch the stock price of Apple Inc (NASDAQ: AAPL). Use the YFinance Library."
)
# Output the response
print(response)

Define the CodeAgent:

• The CodeAgent is initialized with:
  • tools: A list of tools the agent can use, here including DuckDuckGoSearchTool for web searches.
  • additional_authorized_imports: The libraries the agent can use. The yfinance library is explicitly authorized.
  • model: Specifies the selected LLM backend to power the agent.

Run the Agent:

• The run method executes a command provided as input: “Fetch the Stock price of Apple Inc (NASDAQ: AAPL). Use the YFinance Library.”
• The agent interprets the command, uses the yfinance library to fetch the required stock price, and returns the result.

Output

Let’s understand the output:

• Step 1 Failure: Using .iloc[-1] without ensuring data availability caused an error.
• Step 2 Partial Success: Attempted to retrieve data via info but didn’t succeed due to missing fields.
• Step 3 Success: Added a validation check for empty DataFrames and fetched the price correctly.

The agent generates and debugs the code to get to the final output under 10 seconds, quite impressive!!

The SmolAgents library systematically refined the code across iterations to handle errors, improve robustness, and achieve the desired result of fetching Apple Inc.’s stock price (246.21).

Conclusion

SmolAgents by Hugging Face represents a groundbreaking advancement in simplifying the creation and execution of AI-powered agents. With its minimalist design, robust integrations, and focus on user-friendliness, SmolAgents caters to developers seeking to harness the power of large language models (LLMs) for dynamic and adaptable workflows.

Key takeaways from SmolAgents include:

1. Simplicity Meets Power: Encapsulating agent logic in approximately 1,000 lines of code, SmolAgents strikes a balance between ease of use and functionality, making it accessible to developers of varying expertise levels.
2. Versatile Agent Types: It supports both traditional ToolCallingAgents and advanced Code Agents, empowering developers to create highly dynamic systems for a wide range of applications.
3. Security and Reliability: SmolAgents incorporates robust safeguards, such as a custom LocalPythonInterpreter and E2B sandboxed execution, ensuring safe and controlled code execution.
4. Code as a Medium: By embracing code over rigid JSON structures for tool actions, SmolAgents offers flexibility, composability, and a seamless alignment with LLM training corpora, enabling agents to handle complex workflows efficiently.
5. Integrated Ecosystem: With extensive support for any LLM (e.g., Hugging Face, OpenAI, Anthropic) and integration with the Hugging Face Hub, SmolAgents provides a versatile platform that adapts to various tools and tasks.

By abstracting complexities and offering foundational building blocks, SmolAgents equips developers to create scalable, reliable, and adaptable agentic systems without reinventing the wheel. This makes it a valuable resource for the growing demand for agentic solutions in 2025 and beyond.

Explore the The Agentic AI Pioneer Program to deepen your understanding of Agent AI and unlock its full potential. Join us on this journey to discover innovative insights and applications!

Pankaj Singh

Hi, I am Pankaj Singh Negi - Senior Content Editor | Passionate about storytelling and crafting compelling narratives that transform ideas into impactful content. I love reading about technology revolutionizing our lifestyle.