smolagents Documentation & Guided Tour

smolagents is Hugging Face's deliberately minimal agent library — the core agent logic is roughly a thousand lines in a single agents.py — and its documentation is structured as a quickstart, a guided tour, tutorials, conceptual guides, examples and an API reference. The central idea is the CodeAgent, which writes its actions as Python snippets rather than JSON tool calls, so it can loop, branch, nest calls and transform results natively; the docs are unusually direct about the trade-off, listing the limitations (syntax errors and exceptions to handle, less predictable output, requires a secure execution environment) right beside the strengths, and pairing it with ToolCallingAgent for the conventional structured-JSON paradigm when reliability matters more than expressivity. The guided tour walks through choosing an agent type, then the CodeAgent's security model: imports are denied by default and widened only through additional_authorized_imports, submodule access is separately gated, and there is an explicit warning that the built-in LocalPythonExecutor is not a security sandbox — with executor_type switching execution into E2B, Modal, Blaxel or Docker instead. It then covers model backends (InferenceClientModel across Hub inference providers, LiteLLMModel for 100+ APIs, TransformersModel and MLXModel for local inference, AzureOpenAIModel, AmazonBedrockModel), forwarding completion parameters and the REMOVE_PARAMETER sentinel, final_answer_checks for custom termination conditions, inspecting agent.logs and write_memory_to_messages after a run, building tools with the @tool decorator or by subclassing Tool, the default toolbox (DuckDuckGo search, Python interpreter, a Whisper-Turbo transcriber), loading tool collections from any MCP server or from LangChain, hierarchical multi-agent systems via managed_agents, a GradioUI with interrupt support, and push_to_hub for sharing agents. Apache-2.0, 28.7k stars, 2.8k forks.

Topic

Agentic

Level

Intermediate

Format

Documentation

Cost

Free

Duration

~2-3 hours for the quickstart and guided tour; ongoing as reference

Provider

Hugging Face

Hands-on

Yes — code/exercises

Certificate

None

• ✓Decide between a code-writing CodeAgent and a JSON ToolCallingAgent for a given task
• ✓Lock down code execution with additional_authorized_imports and a sandboxed executor_type
• ✓Swap model backends across Hub inference providers, LiteLLM, local Transformers, MLX, Azure and Bedrock
• ✓Write custom tools with the @tool decorator, or subclass Tool when you need heavy initialisation
• ✓Pull tool collections from any MCP server or from LangChain directly into an agent
• ✓Build hierarchical multi-agent systems by passing managed_agents to a manager agent
• ✓Debug a run by inspecting agent.logs and write_memory_to_messages after execution
• ✓Ship an agent behind a GradioUI and push it to the Hugging Face Hub for reuse

• •The whole agent loop is about 1,000 lines in one file, so you can read the framework rather than trust it
• •Honest about danger: the docs state plainly that LocalPythonExecutor is not a security sandbox
• •Four real sandbox backends are documented (E2B, Modal, Blaxel, Docker), not just a warning to be careful
• •Model-agnostic and modality-agnostic — the same agent code runs on Hub, OpenAI, Anthropic, Bedrock, Ollama or local MLX
• •First-class MCP support through ToolCollection.from_mcp, so agents consume the wider MCP server ecosystem
• •Backed by real results: the multi-agent example topped the GAIA leaderboard and the open-deep-research example took 395 points on Hacker News

This page was written from 4 sources, 2 on domains other than huggingface.co.

1. 1.huggingface.co — indexvendor
2. 2.huggingface.co — guided tourvendor
3. 3.github.com — smolagents
4. 4.hn.algolia.com — hn.algolia.com