smolagents: Hugging Face's minimalist agent library

The idea: less abstraction, more code

Hugging Face released smolagents in late 2024 with a simple promise: an agent’s whole logic should fit in a small, readable codebase. Where many frameworks stack layer upon layer, smolagents stays close to how an AI agent actually works: the model reasons, picks an action, observes the result and repeats, following the ReAct pattern.

You get two kinds of agents:

• CodeAgent, the house specialty: at each step the model writes a short Python snippet that calls tools, does math or combines results;
• ToolCallingAgent, for classic JSON-based tool calling when that style fits better.

Tools can come from an MCP server, from LangChain, or even from an app published on the Hugging Face Hub. Several agents can also work together, with one managing the others.

Who it’s for, and what for

smolagents is a good way to learn what an agent really is, prototype quickly, or build agents for web research, data analysis and file processing. It’s a natural fit for open-weight models, since it works just as well with a local model as with a commercial API. Agents can also take image, video or audio inputs.

Up and running in minutes

After a pip install of the smolagents package (with the “toolkit” extra for default tools such as web search), you pick a model, create a CodeAgent with a list of tools and hand it a task. Ready-made commands, smolagent and webagent, even let you try it without writing a script.

Strengths and limits

Strengths: simplicity, transparency (you can read the code the agent writes), model independence and Hub integration.

Limits: running generated code calls for serious sandboxing in production; quality depends heavily on the model, since smaller models write less reliable code; and there’s no visual interface or advanced state management and resumption like heavier frameworks offer.

Alternatives

For production work with fine-grained control, look at LangGraph or Pydantic AI. For an official vendor SDK, consider the OpenAI Agents SDK or Google ADK.