smolagents is Hugging Face's small, intentionally minimal Python library for building agentic systems that think in code. It gives you a multi-step loop, tools, and models without a forest of abstractions, keeping the core under roughly two thousand lines in src/smolagents/agents.py. If you want fast iteration on real agents - with secure execution options and first-class support for code-written actions - this repo is a sharp instrument.
huggingface
Organization
The Problem and the Solution
Real applications rarely fit a fixed decision tree. The moment your workflow needs to branch based on new information - search results, an API response, a file structure - a single LLM call is not enough.
You need a loop: plan, decide, act, observe, repeat.
smolagents provides that loop while avoiding heavy framework overhead. It supports two complementary action styles: a CodeAgent that writes executable Python snippets for precise, composable actions, and a ToolCallingAgent for the more common JSON/text tool calling paradigm. The CodeAgent approach is backed by research showing code actions can reduce steps and improve accuracy on difficult benchmarks.
Key Features
- Simplicity: Core logic fits in about a thousand lines in agents.py, keeping abstractions thin and hackable.
- Code-first actions:
CodeAgentwrites actions as Python functions and loops, enabling natural composition and state. ClassicToolCallingAgentis available too.- Model-agnostic: Use Hugging Face Inference providers, LiteLLM (OpenAI/Anthropic and many others), Transformers, vLLM, or local runtimes like Ollama.
- Secure execution: Run action code locally or in sandboxes via Docker, E2B, Modal, or Pyodide/Deno Wasm; see secure code execution.
- Tooling ecosystem: Build tools with the
@tooldecorator or import from MCP servers, LangChain tools, or even a Hub Space; see tools.py.- CLI and examples: Try agents quickly with
smolagentand the vision-enabledwebagent. Explore examples like RAG, text-to-SQL, and multi-agent orchestration in the docs.
Why it Stands Out
Three things make this project feel practical.
- First, it is small - the core run loop, memory, planning, and tool wiring live together in a readable file.
- Second, it is model-agnostic with clean adapters, so you can swap between Transformers, vLLM, Ollama, LiteLLM-backed providers, HF Inference, or OpenAI-compatible APIs with minimal code.
- Third, it takes security seriously: code execution can be isolated via Docker, E2B, Modal, or a Pyodide/Deno WebAssembly sandbox, so you are not forced to run arbitrary code in your process. The README and docs are concise, and the CLI lets you try agents quickly (Docs, 2025; Hugging Face, 2024).
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
model = InferenceClientModel() # Uses a default HF Inference provider model
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)
agent.run("How many seconds would it take for a leopard at full speed to cross Pont des Arts?")
Under the hood
The heart of the system is agents.py, which implements a minimal multi-step loop (think ReAct) with planning, memory, tool calls, and a final answer step. The base MultiStepAgent handles the loop and logging; CodeAgent generates code blocks, parses them, and executes via a selected executor; ToolCallingAgent parses structured tool calls and can run them in parallel.
Memory is serialized as steps with timing and token usage. The models layer abstracts providers and supports streaming, stop sequences, and structured outputs. The executors include local and remote sandboxes (CodeAgent.create_python_executor), and the tools module provides a base Tool class, validation, and helpers for MCP and Hub integration (tools.py).
The project is pure Python with a small, well-chosen dependency set: rich for logs and CLI UX, jinja2 for templating prompts, huggingface-hub for sharing agents and tools, and optional extras for vision, Litellm, Transformers, vLLM, MCP, OpenAI-compatible servers, and telemetry. You can see these extras in pyproject.toml.
Use cases
If your workflow must reason and act in multiple steps, smolagents gives you the building blocks. Typical scenarios include:
Agentic RAG pipelines that search, retrieve, call a re-ranker, and synthesize a final answer; text-to-SQL assistants that explore schema, write queries, and verify outputs; multi-agent orchestrations where a planner delegates to specialists and aggregates results.
The docs include step-by-step examples for text-to-SQL, RAG, and multi-agent workflows. For browsing, the webagent uses Selenium/Helium to navigate pages with visual feedback.
Community and contributing
The repository ships with clear docs and examples, and issues and pull requests show active iteration. You can explore the source, propose features, or report bugs on GitHub. See README.md and the docs site to get oriented, and check CONTRIBUTING.md if you plan to open PRs.
Usage and license terms
smolagents is released under the Apache-2.0 license, a permissive license that allows commercial use, modification, distribution, and patent grant with attribution. You should include a copy of the license and notices in redistributions and avoid using brand names or trademarks in ways not permitted by the license. See LICENSE for the full text.
Impact potential
By keeping agents small and code-centric, smolagents lowers the barrier to practical, dependable automation. The code-as-action pattern makes it easier for models to express loops, conditionals, and data handling, reducing brittle JSON parsing and yielding fewer steps on average.
The model-agnostic approach means teams can adopt open models or switch providers without re-architecting. Expect tighter integrations with MCP and richer structured outputs in the near term, plus more examples and tooling around secure execution and observability.
About Hugging Face
Hugging Face maintains smolagents and a wide ecosystem of open-source libraries and platforms for machine learning, including Transformers, Datasets, Spaces, and the Inference Endpoints. If you deploy agents, the Hub and Spaces make it straightforward to share tools and complete agents as reproducible apps. Learn more at huggingface.co.
Conclusion
If you want to build real, multi-step agents without getting buried in framework layers, start here. Read the overview, try the CLI, and scan agents.py to see how the loop works. Then plug in tools, pick a model, and test your workflow end-to-end. For background, the launch post gives a crisp primer on when agents help and why code actions matter (Hugging Face, 2024).
Smolagents: Code-first, Multi-step AI agents