smolagents

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

Install

• pip install smolagents Python (core)
• pip install 'smolagents[transformers]' Python (local model support)
• pip install 'smolagents[litellm]' Python (LiteLLM 100+ providers)
• pip install 'smolagents[openai]' Python (OpenAI provider)

Imports

• CodeAgent

  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

  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

  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

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)