smolagents: Hugging Face's Minimal Code-First Agent Library

What smolagents Does and Who It Is For

smolagents is designed for developers who want to build AI agents with a minimal abstraction layer. The README states that the agent logic fits in approximately 1,000 lines of code in `src/smolagents/agents.py`, which the maintainers present as a deliberate design constraint rather than a coincidence. This makes the library easy to read, fork, and modify.

The primary audience is developers who need an agent that can reason through a multi-step task and take actions. smolagents is model-agnostic: it connects to any LLM through several provider wrappers, and the README lists local transformers models, Ollama, OpenAI, Anthropic, Azure, Amazon Bedrock, Together AI, OpenRouter, DeepSeek, and 100+ more through the LiteLLM integration.

The project is open source under Apache-2.0 and hosted on GitHub at huggingface/smolagents. Full documentation is at huggingface.co/docs/smolagents.

The CodeAgent Design: Reasoning in Python

The central design choice in smolagents is the CodeAgent class. Most agent frameworks express tool calls as structured JSON: the model emits a JSON object naming a tool and its arguments, the framework parses it, and executes the corresponding function. CodeAgent instead instructs the model to write Python code as its action step. The code is executed, the output is observed, and the agent continues from there.

The README presents this as the first-class approach, describing the CodeAgent as an agent that writes its actions in code, as opposed to agents being used to write code. The practical effect is that the agent can compose multiple tool calls in a single step, use Python's control flow, and express complex reasoning without requiring a rigid schema for every possible action.

The alternative class, ToolCallingAgent, uses the conventional JSON tool call format for models or environments where code execution is not appropriate.

Because CodeAgent executes Python code, sandboxed execution is strongly recommended for any input that is not fully trusted. The library integrates with E2B, Modal, Blaxel, and Docker for isolated execution environments.

Installing smolagents and Running a First Agent

Install with a default set of tools:

pip install "smolagents[toolkit]"

The `toolkit` extra adds the DuckDuckGo search tool (`ddgs`) and a webpage visit tool (`markdownify`). The base package installs `huggingface-hub`, `requests`, `rich`, `jinja2`, `pillow`, and `python-dotenv`.

Define an agent and run it:

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

The `InferenceClientModel` is the default gateway for all inference providers supported on the Hugging Face Hub. To switch providers, pass a different model class. For a local transformers model:

from smolagents import TransformersModel

model = TransformersModel(
    model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
    max_new_tokens=4096,
    device_map="auto"
)

Agents can be pushed to the Hugging Face Hub as Space repositories with `agent.push_to_hub("m-ric/my_agent")` and reloaded later with `agent.from_hub("m-ric/my_agent")`.

Provider Support: From LiteLLM to Amazon Bedrock

smolagents wraps provider access in typed model classes. For LiteLLM, which covers 100+ LLMs:

from smolagents import LiteLLMModel

model = LiteLLMModel(
    model_id="anthropic/claude-4-sonnet-latest",
    temperature=0.2,
    api_key=os.environ["ANTHROPIC_API_KEY"]
)

For OpenAI-compatible servers, the `OpenAIModel` class accepts an `api_base` override:

from smolagents import OpenAIModel

model = OpenAIModel(
    model_id="deepseek-ai/DeepSeek-R1",
    api_base="https://api.together.xyz/v1/",
    api_key=os.environ["TOGETHER_API_KEY"]
)

For Azure models, the `AzureOpenAIModel` class accepts `azure_endpoint`, `api_key`, and `api_version` from environment variables. For Amazon Bedrock, the `AmazonBedrockModel` class reads the model ID from an environment variable. The pyproject.toml shows that each provider has its own optional dependency group: `litellm`, `openai`, `bedrock`, `mlx-lm`, `vllm`, and others.

Tool Support: MCP, LangChain, and Hub Spaces

smolagents accepts tools from multiple sources. The README lists MCP servers (through `ToolCollection.from_mcp`), LangChain tools (through `Tool.from_langchain`), and Hugging Face Hub Spaces (through `Tool.from_space`). This means an agent can call any MCP-compatible server or any Space deployed on the Hub without writing a custom wrapper.

The CLI provides two entry points: `smolagent` for running a multi-step CodeAgent from the command line, and `webagent` for browser-based web navigation tasks. The `smolagent` command accepts a prompt, model type, model ID, additional Python imports, and a list of tools:

smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7."  --model-type "InferenceClientModel" --model-id "Qwen/Qwen3-Next-80B-A3B-Thinking" --imports pandas numpy --tools web_search

The `examples/` directory contains demonstrations including multi-agent orchestration, Gradio-based UI integration, RAG with ChromaDB, text-to-SQL, and open deep research workflows.

Limitations: Production Readiness and Python Version Requirements

smolagents requires Python 3.10 or higher, as specified in pyproject.toml. Projects running Python 3.8 or 3.9 cannot use the library without upgrading.

The library is described in the README as barebones by design. That is a strength for customization but a limitation for teams that need built-in retry logic, rate limiting, cost tracking, or observability out of the box. Telemetry support is available as an optional dependency (`smolagents[telemetry]`) that integrates with Arize Phoenix and OpenTelemetry, but it requires separate configuration.

Code execution with CodeAgent creates a security boundary that must be explicitly managed. The README documents four sandbox backends (Blaxel, E2B, Modal, Docker), but sandbox setup requires external credentials or a running Docker daemon. Local execution without a sandbox runs the agent's generated Python in the same process as the host application, which is not appropriate for untrusted inputs.

The latest release, v1.26.0, was published on 2026-05-29. The current development version in pyproject.toml is 1.27.0.dev0, which has not been released yet.

smolagents versus LangChain and CrewAI

LangChain is the most widely adopted Python agent framework. It provides a large ecosystem of integrations, chains, retrievers, and memory backends. Its abstraction layer is significantly thicker than smolagents: a LangChain agent involves chains, runnables, and a callback system. smolagents trades that breadth for simplicity. The README's claim of 1,000 lines of core code is a real constraint: there is less to configure, and also less built in.

CrewAI targets multi-agent role-based workflows where agents are assigned personas and collaborate on tasks. smolagents' multi-agent support exists through its multi-agent orchestration examples, but the library does not enforce role assignment or crew structure. For teams building a workflow with specific agent roles and inter-agent communication protocols, CrewAI provides more scaffolding. For teams that want to inspect and modify the agent's reasoning logic directly, smolagents' minimal codebase is easier to audit.

Editorial conclusion

smolagents suits developers who want a lightweight agent framework where the agent's reasoning is expressed as Python code rather than structured JSON tool calls. The CodeAgent class is the distinguishing design choice: it writes executable Python as its action steps, which avoids the round-trip cost of JSON schema negotiation. That same design makes sandboxing non-optional for untrusted inputs; the library supports E2B, Modal, Blaxel, and Docker as sandbox backends. Teams building agents that will process untrusted inputs in production should configure one of those sandboxes before deploying. The library targets Python 3.10 or higher, and the pyproject.toml records version 1.27.0.dev0 as the development head after v1.26.0 was released on 2026-05-29.

Frequently asked questions

Official sources

1. huggingface/smolagents on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases