Hugging Face smolagents Release

Hugging Face has introduced smolagents, a simple library designed to unlock agentic capabilities for language models. The library's primary innovation is the promotion of "Code Agents"—agents that write their actions as executable code—which provides superior composability, object management, and generality compared to traditional JSON-based tool calling.

The Spectrum of AI Agency

Agency in AI systems is defined as the level of influence an LLM's output has on the program's workflow. This exists on a continuous spectrum rather than a binary state:

  • Simple Processor: LLM output has no impact on program flow.
  • Router: LLM output determines basic control flow (e.g., if/else).
  • Tool Call: LLM output determines which function to execute and with what arguments.
  • Multi-step Agent: LLM output controls iteration and program continuation via a loop.
  • Multi-Agent: One agentic workflow can trigger another agentic workflow.

When to Use Agentic Workflows

Agentic systems are most effective when a task's workflow cannot be determined in advance. While deterministic workflows (hard-coded logic) are more reliable and should be preferred for simple, predictable tasks, agents provide the necessary flexibility for complex, real-world requests that hinge on multiple variable factors.

Code Agents vs. JSON Tool Calling

Traditional agent frameworks often require LLMs to output actions as JSON snippets, which are then parsed and executed. smolagents prioritizes writing actions in code because programming languages are specifically designed to express computer actions more efficiently than JSON.

Writing actions in code offers several technical advantages:

  • Composability: Code allows for nested actions and the definition of reusable functions.
  • Object Management: Code provides a native way to store and manipulate the output of previous actions.
  • Generality: Code can express any operation a computer is capable of performing.
  • Training Data Alignment: LLMs are already heavily trained on high-quality code, making them naturally proficient at this format.

Key Features of smolagents

smolagents is the successor to transformers.agents and is built with several core objectives:

  • Simplicity: The core logic is kept minimal, fitting within a few thousand lines of code.
  • First-class Code Agent Support: Dedicated support for agents that write code, including secure execution in sandboxed environments via E2B.
  • Hub Integration: Tools can be shared to and loaded from the Hugging Face Hub.
  • Model Agnostic: The library supports models hosted on the Hub (via transformers or the Inference API), as well as models from OpenAI and Anthropic via LiteLLM integration.

Building and Deploying Agents

Creating an agent requires two primary components: a list of tools and a model (the LLM engine).

Tools are created by defining a Python function with type hints and docstrings, then applying the @tool decorator. These tools can then be pushed to the Hugging Face Hub for sharing. For example, a CodeAgent can be equipped with a Google Maps tool to plan complex travel itineraries by iteratively gathering travel times and performing calculations.

Performance of Open Models

Benchmarks indicate that open-source models can now compete with the best closed models in agentic workflows. Specifically, the data shows that "code agents" consistently outperform "tool calling agents" across a variety of challenges, validating the approach of using executable code as the primary action format.

Sources