smolagents is a small Python library from Hugging Face for building agentic systems, with its core agent logic kept under about 1,000 lines of code. Its defining idea is the CodeAgent, an agent that writes its actions as Python code snippets rather than emitting a JSON list of tool calls to invoke; tool calls become ordinary Python function calls, so an agent can, for example, loop over several searches in a single action. It follows a ReAct-style loop, generating code from the model, executing it, storing results in memory, and continuing until the agent calls a final_answer tool. A more conventional ToolCallingAgent that emits JSON/text actions is also provided for cases where that style fits better.
The library is deliberately model-, modality-, and tool-agnostic:
- Models: any LLM via local transformers or Ollama, Hugging Face inference providers, LiteLLM (100+ models), OpenAI-compatible endpoints, Azure OpenAI, and Amazon Bedrock
- Modalities: text, vision, video, and audio inputs
- Tools: tools from MCP servers, LangChain, or Hugging Face Hub Spaces, plus a built-in default toolkit
- Hub integration: push and pull tools and agents to and from the Hugging Face Hub for sharing
It ships two CLI entry points: smolagent to run a general multi-step CodeAgent (with an interactive setup wizard), and webagent, a browser-driving agent built on helium. The project cites its own benchmarks arguing code-writing agents use roughly 30% fewer steps and score higher on hard tasks than JSON tool-calling agents.
Because CodeAgents execute model-generated code, the documentation stresses running that code in a sandbox. It supports managed cloud sandboxes (E2B, Blaxel, Modal) and self-hosted Docker isolation, and explicitly warns that the built-in LocalPythonExecutor is best-effort only and must not be treated as a security boundary for untrusted code.