smolagents

What is smolagents?

smolagents is an open-source Python library from Hugging Face for building AI agents powered by large language models, designed around simplicity and a code-first approach. Its core logic sits at roughly 1,000 lines of code, keeping abstractions minimal so developers can read, understand, and extend the library without fighting through layers of complexity. The primary agent type, CodeAgent, generates executable Python code directly as its action output rather than relying on JSON parsing, which gives agents the ability to use loops, conditionals, and nested logic when completing tasks. Smolagents is built for developers who want to prototype and deploy agent systems quickly, across use cases from web search to multimodal workflows, without committing to a heavier framework.

Key Features

• CodeAgent: The primary agent type that writes and executes actions as Python code, supporting secure sandboxed execution via E2B, Modal, Blaxel, or Docker.
• ToolCallingAgent: An alternative agent type that handles standard JSON and text-based tool calls for workflows that require that format.
• Model-Agnostic Integration: Connects to virtually any LLM through classes including InferenceClientModel for the Hugging Face Inference API, LiteLLMModel for OpenAI and Anthropic, TransformersModel for local models, OpenAIServerModel for OpenAI-compatible APIs, and AzureOpenAIServerModel for Azure.
• Hugging Face Hub Integration: Load and share agents and tools directly from Hugging Face Hub, including Gradio Spaces as usable tools.
• Tool-Agnostic Support: Works with tools sourced from MCP servers, LangChain, or Hub Spaces without requiring a specific tool format.
• Modality-Agnostic Processing: Handles text, vision, video, and audio inputs and lets agents that combine browsing, image generation, and document understanding in a single workflow.
• Multi-Agent Orchestration: Supports building systems where multiple agents coordinate, as covered in the library's official multi-agent example.

Use Cases

• Developers prototyping agent systems: Building lightweight AI applications quickly using minimal configuration, running experiments with different LLMs and tools without significant setup overhead.
• Data scientists needing real-time retrieval: Using agents equipped with tools like DuckDuckGoSearchTool to answer questions that require current web data, such as prices, weather, or recent events.
• Teams building multi-modal workflows: Combining web browsing and image generation in a single agent run, for example searching for information and producing visual content based on the results.
• Engineers building knowledge base tools: Configuring agents with retrieval tools to let users search structured or unstructured knowledge sources and synthesize answers across documents.
• Organizations deploying across LLM providers: Running the same agent logic against local models, Hugging Face-hosted models, or third-party APIs like Anthropic and OpenAI by swapping the model class.

Strengths and Weaknesses

Strengths:

• Minimal codebase of roughly 1,000 lines makes the library easy to audit, fork, and modify.
• Code-first agent design lets agents use Python's full expressiveness, avoiding the limitations of JSON-only tool calling.
• Broad model support means developers are not locked into a single LLM provider.
• Deep Hugging Face Hub integration allows tools and agents to be shared and reused as Gradio Spaces.
• Strong community interest, reflected in over 26,000 GitHub stars on the library's own repository.

Weaknesses:

• Frequent version-specific bugs have required users to downgrade, for example pinning to smolagents==1.13.0 to avoid runtime errors in some environments.
• Tool calling errors including unexpected keyword arguments in custom tools and managed agents have disrupted execution for some users.
• OpenAI API incompatibility has been reported, where the library passes unsupported parameters and triggers TypeErrors with no simple external workaround.
• A number of open GitHub issues cover areas like AgentGenerationError, multi-agent memory clearing, token overflow risks, and web search hangs, indicating the library is still maturing.

Pricing

smolagents itself is free and open-source under the Apache 2.0 license. Using it may involve costs from Hugging Face platform services such as compute or hosted inference, billed separately through Hugging Face account plans.

• Free: $0/month, includes unlimited model access, basic CPU Spaces, and ZeroGPU access.
• PRO: $9/month, includes 8x ZeroGPU quota, 25 minutes per day on H200 hardware, 1TB private storage, and 2 million inference credits.
• Team: $20/month per user, includes PRO features plus SSO, audit logs, and team collaboration tools.
• Enterprise: $50+/month (custom pricing), includes advanced security, managed billing, and dedicated support.

Inference endpoints and Spaces are billed separately at hourly rates starting from $0.03, depending on hardware selected. Free-tier users receive $0.10/month in inference credits; PRO and Team users receive $2 per seat.

FAQ

What is smolagents?

smolagents is an open-source Python library from Hugging Face for building AI agents powered by large language models. It is designed around simplicity and a code-first approach, with its core logic sitting at roughly 1,000 lines of code.

What is smolagents used for?

smolagents is used to prototype and deploy AI agent systems across use cases including web search, multimodal workflows, knowledge base retrieval, and multi-agent orchestration. It targets developers who want to build lightweight AI applications without committing to a heavier framework.

How does smolagents work?

smolagents works by connecting a large language model to tools and letting the model decide how to use them to complete a task. Its primary agent type, CodeAgent, generates executable Python code as its action output, supporting loops, conditionals, and nested logic rather than relying on JSON parsing.

What is the difference between CodeAgent and ToolCallingAgent in smolagents?

CodeAgent writes and executes actions as Python code, while ToolCallingAgent handles standard JSON and text-based tool calls. CodeAgent is the primary agent type, and ToolCallingAgent is the alternative for workflows that require that format.

What LLMs does smolagents support?

smolagents connects to virtually any LLM through dedicated classes including InferenceClientModel for the Hugging Face Inference API, LiteLLMModel for OpenAI and Anthropic, TransformersModel for local models, OpenAIServerModel for OpenAI-compatible APIs, and AzureOpenAIServerModel for Azure.

What tools can smolagents use?

smolagents works with tools sourced from MCP servers, LangChain, or Hugging Face Hub Spaces without requiring a specific tool format. It also supports loading tools directly from the Hugging Face Hub, including Gradio Spaces as usable tools.

What modalities does smolagents support?

smolagents handles text, vision, video, and audio inputs. It allows agents to combine browsing, image generation, and document understanding in a single workflow.

Does smolagents support multi-agent systems?

Yes, smolagents supports building systems where multiple agents coordinate with each other. The library includes an official multi-agent orchestration example covering this use case.

How is smolagents kept simple to use and extend?

The core logic is approximately 1,000 lines of code, keeping abstractions minimal so developers can read, understand, and extend the library without working through layers of complexity and is simple to prototype quickly and customize behavior directly.

When should you use smolagents?

smolagents is suited for developers who want to prototype agent systems quickly, run experiments with different LLMs and tools without significant setup overhead, or deploy agents across multiple LLM providers using the same agent logic.

Does smolagents support secure code execution?

Yes, CodeAgent supports secure sandboxed execution through E2B, Modal, Blaxel, or Docker, allowing code generated by the agent to run in an isolated environment.

Is smolagents free to use?

smolagents is an open-source library, meaning the library itself has no cost. Any costs associated with using it depend on the LLM provider or infrastructure you connect to it, such as Hugging Face Inference API, OpenAI, or Anthropic.

Can smolagents be used for real-time data retrieval?

Yes, smolagents supports equipping agents with tools like DuckDuckGoSearchTool to answer questions that require current web data, such as prices, weather, or recent events.