smolagents
Hugging Face's barebones library for agents that think in code
- Source repo
- huggingface/smolagents
- Stars
- ★ 30k
- Last updated
- 15d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 42/100 · Major gaps
At a glance
- How it runs
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- Typical use
- Need a lightweight, small-codebase agent framework that's easy to audit rather than a heavyweight platform
- Not a fit if
- Users who want a no-code graphical interface
- Teams running model-generated code locally without a sandbox
- Source review
- 42/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
smolagents is a lightweight agent library from Hugging Face whose defining feature is having agents express their actions in code rather than plain text (CodeAgent), with the core logic kept to roughly 1,000 lines. It's model-agnostic — usable with local transformers/ollama models or any provider like OpenAI and Anthropic — and modality-agnostic, supporting text, vision, video, and audio input, with model-generated code executable inside sandboxes like Blaxel, E2B, Modal, or Docker for safety.
Lets a developer define an agent in a few lines of Python, give it tools (e.g. web search), and bind a model; the agent plans and executes actions by writing code rather than emitting text that's parsed into tool calls afterward, paired with sandboxed execution to reduce the risk of running arbitrary code directly. It can also pull in ready-made tools from MCP servers, LangChain, or a Hugging Face Space.
- Need a lightweight, small-codebase agent framework that's easy to audit rather than a heavyweight platform
- Want to reuse existing tools from the Hugging Face Hub, or share an agent you've built
- Agent scenarios involving multi-modal input — vision, video, or audio
- Cases with real code-execution safety requirements that need sandboxed isolation for model-generated code
How do you install or deploy this agent?
pip install "smolagents[toolkit]" installs the default toolset; a leaner install without extra tools is also available — see the official docs for details.
How do you use this agent?
Runs in a few lines of code:
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)
agent.run("your task description")You can also share a built agent to the Hugging Face Hub with agent.push_to_hub(...).
What are this agent's strengths and limitations?
- Small core codebase (~1,000 lines), easy to audit and understand rather than being a black-box platform
- Officially documents concrete sandbox options (Blaxel/E2B/Modal/Docker) — unusually transparent security design for a project in this category
- Model-agnostic and modality-agnostic, and can directly reuse tools from MCP servers, LangChain, and Hugging Face Spaces
- Backed by Hugging Face with tight Hub integration, making agents easy to share and reuse
- Targets developers with a Python engineering background — no graphical interface for no-code users
- CodeAgent fundamentally executes model-generated code; running it locally without one of the documented sandboxes carries risk
- This review did not verify actual runtime behavior under any specific sandbox configuration
How does this agent compare with similar options?
Unlike multi-agent orchestration frameworks such as CrewAI or LangGraph that focus on process orchestration, smolagents concentrates on how a single agent executes actions — expressing tool calls as code rather than text/JSON, closer to a lightweight library than a heavyweight platform. If you need to orchestrate multiple collaborating agents, CrewAI or LangGraph fits better; if you need a simple, auditable, model-agnostic single-agent base, smolagents is more direct.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| smolagents This agent | 42 · Major gaps | Library / SDKFree + model costs | ★ 30k | 15d ago | Python | — |
| CaveAgent | 62 · Some gaps | Library / SDKFree + model costs | ★ 204 | 1mo ago | Python | OpenAI API · Claude API |
| Daytona: Secure Elastic Infrastructure for AI Code | 44 · Major gaps | Library / SDKFreemium | ★ 72k | 3mo ago | — | — |
| Pydantic AI Skills | 86 · Good | Library / SDKFree + model costs | ★ 380 | 6d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README explicitly warns that LocalPythonExecutor is not a security boundary and recommends sandboxes (E2B, Docker, etc.), reflecting consideration of least privilege, but no default permission restrictions or user confirmation mechanisms are provided. Data flow: README describes the code execution flow but does not detail how data is processed or transmitted. Sensitive data handling: SECURITY.md mentions credential handling but provides no specific measures. Dependency security: pyproject.toml pins some dependency versions and mentions CVE-2023-4863 fix, but no comprehensive audit. External effects: README mentions code execution may have external effects but provides no rollback mechanism. Source attribution: README and CONTRIBUTING.md provide author info, but publisher identity is unverified. Deductions: lack of user confirmation, rollback, and insufficient detail on data flow and sensitive data handling.
Evidence shows: README and CONTRIBUTING.md provide clear installation and testing instructions, but no specific examples of failure messages. Dependency availability: pyproject.toml lists dependencies but no version compatibility matrix. Self-consistency: documentation is largely consistent with code structure, but no detailed error handling docs. Deductions: insufficient failure messages and dependency availability info.
Evidence shows: README provides multiple usage scenarios (e.g., CLI, different model providers) and clarifies capability boundaries (e.g., LocalPythonExecutor not a security boundary). Trigger precision: documentation describes differences between CodeAgent and ToolCallingAgent but lacks detailed trigger conditions. Environment fit: supports multiple deployment environments (Docker, E2B, etc.) but lacks detailed configuration guides. Deductions: trigger precision not precise enough.
Evidence shows: Information architecture is clear; README provides quick start, CLI usage, security notes. Install notes are detailed with pip and uv commands. Naming stability: version defined in pyproject.toml but no changelog. Examples and FAQ: README provides multiple examples but no FAQ. Known limitations: README clearly states LocalPythonExecutor limitations. License is Apache-2.0. Versioning has version number but no changelog. Maintenance responsibility: CONTRIBUTING.md explains maintenance process. Deductions: missing changelog and FAQ.
Evidence shows: Output usability: README provides clear output examples (e.g., CLI output). Marginal value: documentation emphasizes advantages of code agents (e.g., fewer steps). Cost-benefit: no performance benchmarks or cost analysis. Deductions: insufficient cost-benefit info.
Evidence shows: Claims in README (e.g., code agent performance) cite papers but lack specific data. Cross-source corroboration: documentation references external resources (e.g., papers) but no independent verification. Fact-inference separation: documentation distinguishes facts (e.g., code line count) from inferences (e.g., performance advantage) but not clearly. Deductions: claims lack concrete data support, cross-source verification insufficient.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity is unverified; treat as unknown and do not rely on brand trust.
- LocalPythonExecutor is not a security boundary; do not use it to run untrusted code.
- Lack of user confirmation and rollback mechanisms; ensure proper approval before executing code.
- Dependency versions are pinned but no full security audit; check for vulnerabilities before use.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * Bump dev version: v1.26.0.dev0 by @albertvillanova in https://github.com/huggingface/smolagents/pull/2273 * Add new possible error message to test of LiteLLM providers w/o key by @albertvillanova in https://github.com/huggingface/smolagents/pull/2275 * Fix typo cleanups across docs, examples, and tests by @luojiyin1987 in https://github.com/huggingface/smolagents/pull/2208 * fix: correct f-string escaping in ToolSerializer.dumps error message by @Ricardo-M-L in https://github.com/huggingface/smolagents/pull/2134 …View on GitHub ↗ -
Release notes excerpt
What's Changed * Bump dev version: v1.25.0.dev0 by @albertvillanova in https://github.com/huggingface/smolagents/pull/1939 * Fix import of TokenUsage by @albertvillanova in https://github.com/huggingface/smolagents/pull/1943 * Add MLflow integration doc by @B-Step62 in https://github.com/huggingface/smolagents/pull/1884 * Refactor agent/model deserialization: Replace importlib with registry pattern by @albertvillanova in https://github.com/huggingface/smolagents/pull/1944 …View on GitHub ↗ -
Release notes excerpt
What's Changed * Bump version to 1.24 by @aymeric-roucher in https://github.com/huggingface/smolagents/pull/1871 * Fix: Add backward compatibility for deprecated HfApiModel by @MohammadKassas143 in https://github.com/huggingface/smolagents/pull/1863 * Fix typo in secure_code_execution.md by @jonathanagustin in https://github.com/huggingface/smolagents/pull/1892 * Update no-stop-sequence model list to support gpt-5.2* by @aymeric-roucher in https://github.com/huggingface/smolagents/pull/1895 …View on GitHub ↗