QWE AI Academy Here’s the bit most “minimal agent framework” write-ups skip: after you pip install Hugging Face’s smolagents, the default CodeAgent runs model-written Python through LocalPythonExecutor – and the maintainers themselves say that executor is not a security boundary. Install day is when you pick best-effort local AST limits or pull the docker / e2b / blaxel extras for real isolation. Secure-execution guidance lives in the official secure code execution tutorial.
smolagents 1.26.0 is the pin this guide deploys (PyPI / GitHub stable as of the May 29, 2026 release). Goal: a verified agent process on your machine – not another multi-agent architecture tour. Repo: github.com/huggingface/smolagents.
System requirements before you touch pip
Per the official installation docs, the hard gate is simple: Python 3.10 or newer, plus pip or uv. That’s the library bar.
| Resource | Minimum (API-backed agent) | Notes |
|---|---|---|
| OS | Linux, macOS, Windows | Same pip path; use a venv on all three |
| Python | 3.10+ | PyPI metadata: Requires-Python >=3.10 |
| RAM / CPU | Ordinary laptop for toolkit + remote models | No official RAM floor published for core |
| GPU / disk | Not required for InferenceClient / LiteLLM | Local transformers / vllm extras change everything – weights dominate |
| Network | Needed for Hub inference & web tools | Offline local models need separate weight downloads |
I treat “minimal” as one venv, toolkit extras, remote model. Local 7B+ weights are a different job – VRAM math, not smolagents packaging.
Official download source
Ship only from PyPI or the GitHub repo – no random mirrors. Package pin: smolagents==1.26.0. Docs: huggingface.co/docs/smolagents. Release notes for this cut (Wasm removal, Exa search option): tag v1.26.0 on the same GitHub releases page.
Install the minimal agent framework (step-by-step)
Pin on first deploy. Silent minor bumps have a habit of moving model class names. Toolkit extra pulls the default tool set (web search and friends).
- Create and activate a clean venv (docs push this hard).
- Upgrade packaging tools lightly, then install the pin.
- Add only extras you will use this week.
# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate
# Windows (PowerShell)
# python -m venv .venv
# ..venvScriptsActivate.ps1
python -m pip install --upgrade pip
pip install "smolagents[toolkit]==1.26.0"
# Alt package manager (called out in docs)
# uv venv && source .venv/bin/activate
# uv pip install "smolagents[toolkit]==1.26.0"
Extras matrix you will actually choose later – skip [all] on day one:
litellm/openai– cloud APIs beyond Hub inferencetransformers/vllm/mlx-lm– local models (heavy)docker,e2b,blaxel– sandboxed code executiongradio,telemetry,vision,audio,mcp– UI, tracing, multimodal, MCP tools
Sandbox path once demos leave your laptop:
pip install "smolagents[toolkit,docker]==1.26.0"
# or: pip install "smolagents[toolkit,e2b]==1.26.0"
First-time configuration that unblocks a run
The catch is credentials, not pip. A clean wheel still dies on first agent.run if Hub inference has no token. Create a fine-grained Hugging Face token that can call serverless inference, then export it or log in once.
export HF_TOKEN="hf_..." # shell session
# or
huggingface-cli login
Class names match current docs: InferenceClientModel. Stale 2025 posts still say HfApiModel – that mismatch is a version problem, not broken docs.
from smolagents import CodeAgent, InferenceClientModel
model = InferenceClientModel() # default model via Hub inference
agent = CodeAgent(tools=[], model=model)
result = agent.run("Calculate the sum of numbers from 1 to 10")
print(result)
Empty tools on purpose. This is an install smoke test, not a tools tutorial. If toolkit is present and you want one network hop:
from smolagents import CodeAgent, InferenceClientModel, WebSearchTool
agent = CodeAgent(
tools=[WebSearchTool()],
model=InferenceClientModel(),
stream_outputs=True,
)
print(agent.run("What is the capital of Portugal?"))
Pro tip: Pick the executor extra at install time. Default local execution is fine for trusted demos on a locked-down machine. Internet-facing or multi-user setups should install
docker/e2b/blaxelbefore you treat the green version print as “done.”
Verify the install works
Three checks. Version. Import surface. One agent step.
python -c "import smolagents; print(smolagents.__version__)"
# expect: 1.26.0
# CLI entry points ship with the package
smolagent --help
# interactive runner (no boilerplate script)
# smolagent
If __version__ prints 1.26.0 and the sum task returns a sensible number, the deploy stuck. webagent is a separate CLI entry point – install/verify only if browsing agents are your target.
Common install errors and fixes
GitHub issues and HF forum threads show these more than glossy quickstarts do.
error: metadata-generation-failedwhile installingsmolagents[transformers]– reported on Mac when the heavy extra pulls awkward build deps (issue #940). Path that works: install core/toolkit first (pip install "smolagents[toolkit]==1.26.0"), confirm the smoke script, then retry transformers – or stay on remoteInferenceClientModeland skip local weights.ImportError: cannot import name 'InferenceClientModel'– almost always an older wheel still sitting in the venv.pip install -U "smolagents[toolkit]==1.26.0", then re-printsmolagents.__version__.- Auth / 401-style failures on first
agent.run– token missing or lacking inference permission. SetHF_TOKENor runhuggingface-cli login; mint a fine-grained token with serverless inference access if the old one is read-only. - Scripts still calling remote WasmExecutor after upgrade – v1.26.0 removed remote WasmExecutor. There is no flag to revive it. Move to Docker / E2B / Blaxel / Modal paths from the secure-execution docs.
Upgrade and uninstall
One command for a pinned bump. Read release notes when executors or model class names move.
# upgrade in place
pip install --upgrade "smolagents[toolkit]==1.26.0"
# full remove
pip uninstall smolagents -y
# Hub caches are separate from the wheel
# rm -rf ~/.cache/huggingface
Why bother with a library this small? Core agent logic sits around ~1,000 lines in agents.py, yet the glue – prompt, parser, and executor format staying consistent for code actions – is still easy to get wrong by hand. Work like CodeAct (arXiv:2402.01030) is a big reason this stack exists; install is the boring prerequisite that still trips teams.
FAQ
Do I need Docker to install smolagents?
No. Core and toolkit install with plain pip. Docker, E2B, Blaxel, or Modal only matter when agent-written code must leave LocalPythonExecutor.
What’s the lightest install for a first API-backed agent?
Venv, then pip install "smolagents[toolkit]==1.26.0", export a valid HF_TOKEN, run the empty-tools sum script above. Leave transformers / vllm alone until you deliberately go local. Flaky café Wi-Fi? Retry the pin once before blaming the package – PyPI blips and real dependency conflicts look identical in the traceback.
Is LocalPythonExecutor “good enough” after install?
People often start there for personal experiments with trusted models on a machine they control: imports are restricted and loops are capped. That still is not a security sandbox. Prompt injection, a hostile page a browsing tool fetches, or a bad model output can push past best-effort limits – the docs are blunt. If the agent can touch production data or untrusted inputs, install a sandbox extra and wire executor_type before you celebrate the green version check.
Next: activate the venv, pin smolagents[toolkit]==1.26.0, print smolagents.__version__, set HF_TOKEN, run the sum-of-1-to-10 agent once. Clean return? You’re deployed. Open the guided tour only after that path is boring.