smolagents

1.24.0 verified Tue May 12 auth: no python install: stale quickstart: verified

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).

pip install smolagents

Common errors

error ModuleNotFoundError: No module named 'smolagents.agents' ↓

cause The primary agent classes like `CodeAgent` and `ToolCallingAgent` are designed to be imported directly from the top-level `smolagents` package, not from a submodule.

fix

from smolagents import CodeAgent, ToolCallingAgent

error AttributeError: 'CodeAgent' object has no attribute 'predict' ↓

cause The `CodeAgent` (or `ToolCallingAgent`) uses a method like `run` or `invoke` to execute its logic, not `predict`, which is a method common in other machine learning contexts but not part of the `smolagents` API.

fix

agent = CodeAgent(model=...) agent.run(prompt="...")

error OSError: Error while trying to load model google/gemma-2b. Model name 'google/gemma-2b' was not found in model name list. ↓

cause The specified HuggingFace model ID is incorrect, the model is private or gated requiring authentication, or there's a network issue preventing the model from being downloaded.

fix

Verify the model ID (e.g., 'google/gemma-2b') is correct on HuggingFace Hub, ensure you are logged in with huggingface-cli login if it's a private or gated model, and check your network connection.

error json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0) ↓

cause The Language Model output for the `ToolCallingAgent` was malformed and could not be parsed as valid JSON, causing Python's built-in JSON decoder to fail.

fix

Review the raw LLM output to understand why it's not valid JSON, and adjust the ToolCallingAgent's prompt to be more explicit about the required JSON format and structure for the LLM.

Warnings

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

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

breaking DuckDuckGoSearchTool renamed to WebSearchTool in recent versions. Import fails on newer installs. ↓

fix from smolagents import WebSearchTool

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

fix pip install 'smolagents[transformers]'

gotcha huggingface-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.

gotcha ManagedAgent is deprecated. Multi-agent orchestration now uses managed_agents parameter directly on CodeAgent. ↓

fix Pass managed_agents=[sub_agent] directly to CodeAgent constructor.

gotcha CodeAgent 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.

gotcha API 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

breaking smolagents requires Python >= 3.10. Installation fails on older Python versions. ↓

fix Upgrade Python to 3.10 or newer.

Install

pip install 'smolagents[transformers]'

pip install 'smolagents[litellm]'

pip install 'smolagents[openai]'

Install compatibility stale last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) litellm - - 1.38s 230.2M

3.10 alpine (musl) openai - - 1.35s 103.6M

3.10 alpine (musl) transformers - - - -

3.10 alpine (musl) smolagents - - 1.38s 76.5M

3.10 slim (glibc) litellm - - 1.03s 214M

3.10 slim (glibc) openai - - 1.02s 103M

3.10 slim (glibc) transformers - - 1.13s 4.8G

3.10 slim (glibc) smolagents - - 1.00s 78M

3.11 alpine (musl) litellm - - 2.08s 247.4M

3.11 alpine (musl) openai - - 2.09s 111.4M

3.11 alpine (musl) transformers - - - -

3.11 alpine (musl) smolagents - - 2.04s 82.3M

3.11 slim (glibc) litellm - - 1.74s 231M

3.11 slim (glibc) openai - - 1.68s 111M

3.11 slim (glibc) transformers - - 1.96s 4.9G

3.11 slim (glibc) smolagents - - 1.71s 83M

3.12 alpine (musl) litellm - - 1.99s 235.9M

3.12 alpine (musl) openai - - 1.90s 101.9M

3.12 alpine (musl) transformers - - - -

3.12 alpine (musl) smolagents - - 1.96s 73.4M

3.12 slim (glibc) litellm - - 1.94s 220M

3.12 slim (glibc) openai - - 1.93s 102M

3.12 slim (glibc) transformers - - 2.15s 4.9G

3.12 slim (glibc) smolagents - - 1.95s 75M

3.13 alpine (musl) litellm - - 1.87s 235.6M

3.13 alpine (musl) openai - - 1.85s 101.6M

3.13 alpine (musl) transformers - - - -

3.13 alpine (musl) smolagents - - 1.91s 73.0M

3.13 slim (glibc) litellm - - 1.90s 219M

3.13 slim (glibc) openai - - 1.87s 101M

3.13 slim (glibc) transformers - - 2.09s 4.9G

3.13 slim (glibc) smolagents - - 1.82s 74M

3.9 alpine (musl) litellm - - - -

3.9 alpine (musl) openai - - - -

3.9 alpine (musl) transformers - - - -

3.9 alpine (musl) smolagents - - - -

3.9 slim (glibc) litellm - - - -

3.9 slim (glibc) openai - - - -

3.9 slim (glibc) transformers - - - -

3.9 slim (glibc) smolagents - - - -

Imports

CodeAgent

wrong

from smolagents import CodeAgent, HfApiModel
model = HfApiModel()

correct

from smolagents import CodeAgent, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[], model=model)
agent.run('What is 2+2?')

HfApiModel was removed and replaced by InferenceClientModel. Causes ImportError on smolagents >= 1.x. All LLM tutorials and docs from early 2025 use the old name.

LiteLLMModel

wrong

from smolagents import LiteLLMModel
model = LiteLLMModel(model_id='claude-sonnet-4-5')

correct

from smolagents import LiteLLMModel
model = LiteLLMModel(model_id='anthropic/claude-sonnet-4-5', api_key='...')

LiteLLM requires provider-prefixed model IDs. Use 'anthropic/claude-...' not 'claude-...' alone.

ToolCallingAgent

wrong

from smolagents import ToolCallingAgent, HfApiModel

correct

from smolagents import ToolCallingAgent, InferenceClientModel

model = InferenceClientModel()
agent = ToolCallingAgent(tools=[], model=model)

Same HfApiModel rename applies here. ToolCallingAgent uses JSON tool calls instead of Python code.

Quickstart verified last tested: 2026-05-12

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)