Authority AI Editorial
smolagents: Hugging Face's minimal agent library
smolagents is a small Python library from Hugging Face for building AI agents without pulling in a large framework. The whole agent loop is around 1,000 lines of code, which the maintainers treat as a feature: you can read the entire thing in an afternoon and know exactly what your agent is doing. It's aimed at developers who want an agent embedded directly in their own Python code, not a hosted platform or a visual builder. The library's defining idea is having the model write its actions as real Python code rather than JSON that a runner then interprets, which the project argues is a better fit for how these models already work.
What it does
smolagents gives you two agent types. The CodeAgent, its signature design, has the model write each step as an executable Python snippet: instead of returning a JSON object naming a tool and its arguments, the model writes the actual function call, which can nest calls, reuse variables, and express logic a flat JSON schema can't. The ToolCallingAgent is the more conventional alternative, using JSON or text-based tool calls for cases where that pattern fits better or a downstream system expects it. Both are model-agnostic: the library works with local models, Hugging Face's own inference providers, OpenAI, Anthropic, and more than 100 other providers through LiteLLM, and it accepts tools sourced from MCP servers, LangChain, or Hugging Face Spaces.
How you use it
You install the library, define or import a set of tools, and instantiate a CodeAgent or ToolCallingAgent with a model and those tools attached. Because the CodeAgent's actions are Python, running one means executing model-written code, so smolagents supports sandboxed execution through E2B, Blaxel, Modal, or Docker for anything beyond a trusted local experiment. The README is direct that the built-in LocalPythonExecutor is not a security boundary. It's meant for development and controlled settings, not for running untrusted or adversarial input. Hugging Face's announcement post frames the underlying goal as giving the model "agency": letting its own output decide what happens next in a workflow, instead of hand-coding an if-else branch for every case you can anticipate.
What to know before adopting it
smolagents is Apache 2.0 licensed and written in Python, which keeps it easy to fold into an existing codebase rather than standing up separately. As of 2026-09-27 the repository shows 29.5k stars and 1,056 commits, younger and smaller than some of the more established agent frameworks but actively maintained. Cost is entirely a function of whichever model you plug in; the library itself doesn't add hosting fees. Hugging Face's own announcement reports that CodeAgent's approach needs roughly 30% fewer LLM calls than a JSON tool-calling loop on its benchmark suite, and that code agents outperformed tool-calling agents across that same suite. These are the maintainers' own reported figures, not an independently reproduced result, so treat them as a starting claim worth testing on your own workload rather than a settled number.
Where it sits next to similar tools
smolagents competes on being small and code-first rather than on breadth of built-in integrations. If you want a visual workflow builder that non-engineers can edit, or an agent that needs to drive a real browser, this isn't that tool: it's a library you write around, not a platform you configure. Where it earns its place is inside an existing Python application where you want an agent with a codebase small enough to fully understand, and where writing actions as code rather than assembling JSON schemas actually reduces the amount of glue you maintain. Since the library expects you to supply your own tools, teams often want a larger starting set of capabilities to hand an agent instead of writing every one from scratch. The AI Ultimate Skill Collection packages 3,029 ready-made skills in 12 packs that your agent follows step by step, which helps teams who would rather not write every method by hand.