smolagents

library1.26.0pypypi✓ verified 30d ago

Minimalist HuggingFace agent framework where agents write actions as Python code. ~1,000 lines of core logic. Released December 2024. Current version is 1.24.0 (Mar 2026). Releases frequently — weekly cadence. Two agent types: CodeAgent (writes Python code) and ToolCallingAgent (JSON tool calls).

llm-agents ai-ml

pip install smolagents

package ↗

INSTALL

IMPORT

SIG · SMOLAGENTS

smolagents

llm-agentspythonv1.26.0

Install

20.5s avg

Import

1917ms

Disk

86MB

Pass rate

7/ 10

Env Coverage7 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ 0.03s

✓ 32.43s

py 3.11

✓ 0.03s

✓ 33.35s

py 3.12

✓ —

✓ 28.95s

py 3.13

3/4 runs

✓ 28.05s

py 3.9

✕ build_error

86MB installed

● package 86MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CodeAgent

✓ from smolagents import CodeAgent

✗ from smolagents import CodeAgent

InferenceClientModel

✓ from smolagents import InferenceClientModel

✗ from smolagents import InferenceClientModel

Minimal CodeAgent with web search using InferenceClientModel 1.24.x.

from smolagents import CodeAgent, InferenceClientModel, WebSearchTool import os # Uses HF_TOKEN env var automatically model = InferenceClientModel() agent = CodeAgent( tools=[WebSearchTool()], model=model ) result = agent.run('How many seconds would it take a leopard at full speed to cross the Pont des Arts?') print(result)

Debug

Known issues

breakingHfApiModel is removed in smolagents >= 1.0. Use InferenceClientModel instead. Causes ImportError: cannot import name 'HfApiModel'.

fix

Replace HfApiModel() with InferenceClientModel(). Same constructor signature.

affects: >= 1.0.0

breakingDuckDuckGoSearchTool renamed to WebSearchTool in recent versions. Import fails on newer installs.

fix

from smolagents import WebSearchTool

affects: >= 1.10.0

gotchaTransformersModel requires torch and transformers installed separately. pip install smolagents alone is not enough for local model inference.

fix

pip install 'smolagents[transformers]'

affects: all

gotchahuggingface-hub is pinned to <1.0.0 in smolagents. Installing huggingface-hub>=1.0.0 separately breaks the tokenizer build.

fix

Let smolagents manage huggingface-hub version. Do not pin huggingface-hub independently.

affects: >= 1.23.0

gotchaManagedAgent is deprecated. Multi-agent orchestration now uses managed_agents parameter directly on CodeAgent.

fix

Pass managed_agents=[sub_agent] directly to CodeAgent constructor.

affects: >= 1.15.0

gotchaCodeAgent executes LLM-generated Python code locally by default. Use E2B, Docker, or Modal sandboxing in production.

fix

Pass use_e2b_executor=True or configure docker/modal sandbox on agent init.

affects: all

gotchaAPI marked experimental — breaking changes ship without major version bumps. Weekly release cadence. Pin version in production.

fix

Pin with smolagents==1.24.0 in requirements.txt

affects: all

breakingsmolagents requires Python >= 3.10. Installation fails on older Python versions.

fix

Upgrade Python to 3.10 or newer.

affects: all

Upgrade

Version history

1.26.0latest on PyPI · released May 29, 2026

Audit

Dependencies

torchoptionalRequired for TransformersModel local inference. Install via smolagents[transformers].

litellmoptionalRequired for LiteLLMModel supporting 100+ providers. Install via smolagents[litellm].

huggingface-hubrequiredRequired for InferenceClientModel. Pinned to <1.0.0 in recent versions due to tokenizer build issues.

Agent activity

42 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/smolagents/ ↗