Smolagents — Lightweight AI Agent Framework

What it is

Smolagents is Hugging Face's lightweight agent framework. The core library is approximately 1,000 lines of code. Agents write and execute Python code as their actions instead of outputting JSON tool calls, making them more flexible and easier to debug.

The framework targets researchers and developers who want to prototype agents quickly without the overhead of larger frameworks. It supports OpenAI, Anthropic, Hugging Face, and local models.

How it saves time or tokens

Smolagents uses code-based actions where the agent writes Python directly. This avoids the overhead of defining JSON schemas for every tool and parsing structured outputs. The agent can compose tools, use variables, and write loops -- capabilities that JSON-based tool calling cannot express.

The minimal codebase means fewer abstractions to learn and debug. You can read the entire source in an afternoon.

How to use

1. Install with pip install smolagents.
2. Define tools using the @tool decorator with type hints and docstrings.
3. Create a CodeAgent with your tools and model, then call agent.run() with a natural language query.

Example

from smolagents import CodeAgent, tool, HfApiModel

@tool
def get_weather(city: str) -> str:
    '''Get current weather for a city.'''
    return f'Sunny, 22C in {city}'

agent = CodeAgent(
    tools=[get_weather],
    model=HfApiModel()
)
result = agent.run('What is the weather in Paris?')
print(result)

Related on TokRepo

• AI tools for agents -- Agent frameworks and orchestration tools
• Multi-agent frameworks -- Compare multi-agent approaches

Common pitfalls

• Code agents execute Python code generated by the LLM. This is powerful but carries security risks. Run agents in sandboxed environments when processing untrusted input.
• The @tool decorator requires a docstring. Without it, the agent has no description of what the tool does and will not use it correctly.
• Smolagents is intentionally minimal. If you need built-in memory, RAG, or team orchestration, consider pairing it with a larger framework or building those components yourself.