Full-Code · Orchestration Frameworksactive

smolagents

Type: full-code · Vendor: Hugging Face (Paris, France) · Language: Python · License: Apache-2.0 · Status: active · Status in practice: emerging · First released: 2024-12-05

Links: homepage docs repo

Provide a barebones (~1k LoC) Python library for multi-step ReAct agents whose default action format is executable Python code rather than JSON tool calls, with first-class sandboxed execution and Hugging Face Hub sharing.

Description. smolagents is Hugging Face's Apache-2.0 Python library for 'agents that think in code'. Its distinguishing design choice is CodeAgent: the LLM writes each action as a Python code snippet that is parsed and executed by a custom AST-walking interpreter (LocalPythonExecutor) or a remote sandbox (e2b, blaxel, modal, docker, wasm), with the print output returned as the observation for the next ReAct step. Alongside CodeAgent it also ships ToolCallingAgent for the conventional JSON tool-calling shape. The framework deliberately keeps abstractions minimal — the docs claim 'The logic for agents fits in ~thousand lines of code' — and integrates with the Hugging Face Hub for sharing agents and tools.

Agent loop shape. MultiStepAgent runs a textbook ReAct loop: SystemPromptStep + TaskStep go to memory, then while budget allows the agent serialises memory to chat messages, calls the Model, parses the completion into an action (Python code for CodeAgent, JSON tool call for ToolCallingAgent), executes the action (LocalPythonExecutor or remote sandbox), and records the result as an ActionStep observation. Iteration stops on final_answer or max_steps (default 20). An optional planning_interval inserts PlanningStep revisions without performing a tool call.

Primary use cases

code-as-action agents that emit Python instead of JSON tool calls
ReAct agents with sandboxed execution (local or e2b/modal/docker)
Hub-shareable agents and tools
minimal-footprint replacements for larger frameworks

flowchart TD TASK[Task] --> MEM[(Agent memory<br/>SystemPromptStep + TaskStep)] MEM --> MS[MultiStepAgent loop] MS --> MODEL[Model call] MODEL --> PARSE{Parse completion} PARSE -->|CodeAgent| CODE[Python code snippet] PARSE -->|ToolCallingAgent| JSON[JSON tool call] CODE --> EXEC[LocalPythonExecutor<br/>or e2b/modal/docker sandbox] JSON --> TOOL[Tool function] EXEC --> OBS[ActionStep observation] TOOL --> OBS OBS --> MS MS -->|final_answer| OUT[Final answer] MS -.->|managed_agents call| SUB[Sub-agent<br/>also a MultiStepAgent] SUB -.->|returns final| MS

Key concepts

CodeAgent → code-as-action (docs) — Writes actions as Python code snippets that are parsed and executed; enables natural composability (function nesting, loops, conditionals).
ToolCallingAgent (docs) — Conventional JSON/text-based tool-calling agent for users who prefer that paradigm.
Tool / @tool → tool-use (docs) — A callable function with metadata the LLM uses; @tool decorator is the recommended way to define simple tools.
executor_type (docs) — Sandbox selector — local | blaxel | e2b | modal | docker | wasm. Default 'local' uses LocalPythonExecutor.
LocalPythonExecutor (docs) — AST-walking interpreter: imports allow-listed, op count capped; safer than exec() but not fully secure.
managed_agents → agent-as-tool-embedding (docs) — Constructor parameter that gives an agent a list of sub-agents to call like tools.

Patterns this full-code implements —

Neighbourhood

Click any neighbour to follow the lineage. Scroll to zoom, drag to pan.

Anti-patterns avoided

✕JSON-Only Action Schema
smolagents explicitly argues that JSON tool-call dicts are inferior to executable code as the action format; supported by cited research and the @tool surface.
[agent-framework-bloat]
Simplicity is a stated design value: ~1k LoC, minimal abstractions above raw code.

smolagents

Neighbourhood

Anti-patterns avoided

Alternatives & relatives

Listed as alternative by (1)

References

Provenance