smolagents

Core concepts

1. CodeAgent vs ToolCallingAgent: CodeAgent writes and executes real Python per turn; ToolCallingAgent is the drop-in JSON-tool-calling alternative if you want parity with other frameworks. smolagents Docs
2. Why code execution is faster for multi-step tasks: A model can loop, branch, and combine several tool calls in one generated code block instead of one round trip per tool call.
3. The @tool decorator and Args: docstrings: smolagents parses the Args: section of a docstring directly to build the tool schema — a malformed block breaks tool discovery, not just the docs.
4. Security is not automatic: The default local executor is explicitly documented as not a sandbox — escaping it is expected behavior. Use executor_type="e2b" or "docker" for anything beyond local experimentation.
5. additional_authorized_imports: Any import a tool needs beyond the safe allowlist must be explicitly declared when constructing the agent.

What Is It?

smolagents is HF's lightweight agent library with two execution paradigms.

CodeAgent lets models author executable code guarded by sandbox executors.

ToolCallingAgent follows familiar function-calling patterns with smaller deps.

Why Should I Care?

Great for HF model ecosystems and experiments where code-as-action helps.

Forces you to think about sandbox boundaries early.

Real World Analogy

smolagents CodeAgent is giving the model a scratchpad calculator — it writes code steps instead of filling out JSON permission slips for every move.

Visual Mental Model

CodeAgent -> execute code in sandbox
  ToolCallingAgent -> classic tool JSON

Beginner Explanation

Hugging Face smolagents offers CodeAgent (model writes code) vs ToolCallingAgent (classic tools). Pick based on trust in sandboxed execution vs explicit tools.

Smallest Possible Example

# CodeAgent writes Python snippets
# ToolCallingAgent uses JSON tool calls
print("Pick agent class by execution style")

Common Mistakes

❌ Running CodeAgent without a real sandbox.

Arbitrary code execution is a security incident waiting to happen.

❌ Assuming smaller library means no ops concerns.

You still need logging, limits, and model routing.

❌ Using CodeAgent when tools are stable and few.

ToolCallingAgent is simpler to audit.

Real Project Example

Hugging Face Spaces demos often use smolagents for quick prototypes.

Research notebooks on HF Hub illustrate CodeAgent patterns.

Build This Mini Project

Run a ToolCallingAgent with one calculator tool locally, then read CodeAgent docs and list sandbox requirements before trying it.

Interview Question

CodeAgent vs ToolCallingAgent?

CodeAgent generates executable code for multi-step logic; ToolCallingAgent uses structured tool calls. CodeAgent needs stronger isolation; ToolCallingAgent is easier to audit when tools are fixed.

Key Takeaways

• Two agent styles in one library.
• CodeAgent demands sandboxes.
• HF ecosystem friendly.
• Match agent class to risk profile.

Resources

• smolagents Docs
• GitHub: smolagents
• Hugging Face Agents Course (free, covers smolagents directly)

YouTube learning

Core concepts from video walkthroughs:

• How to build AI agents with smolagents — full course
• SmolAgents: code-based agents in a few lines
• Building agents with Smolagents (Hugging Face)

The 60-second story

Two ways to send an intern to the stock room. One way: they write you a slip, “please fetch SKU 14,” you fetch it, you hand it back, they write another slip. That is JSON tool calling. It is clear and slow when the job is “fetch, filter, add, repeat.”

The other way: they write a short Python script, run it in a pen, and come back with the answer. That is CodeAgent in smolagents. One turn can loop and branch. ToolCallingAgent is still there if you want the slip style so you match every other framework in the building.

The @tool decorator publishes a function into that pen. The Args: block in the docstring is not decoration. The library reads it to build the schema. A sloppy block does not just look bad. The tool does not show up. That is a memorable failure, like a vending machine that ignores a button because the label was crooked.

Here is the part people skip until the headline. The default local executor is not a locked room. The docs say escaping it is expected. Your laptop is not a sandbox because a README used the word “agent.” For anything past a toy, set the executor to E2B or Docker. additional_authorized_imports is the visitor list. If the script needs datetime or your helper package and it is not on the list, it does not get in. That list is a safety control, not paperwork.

Map the intern.

• A JSON tool call is one slip per trip.
• CodeAgent is a short script in a pen.
• ToolCallingAgent is the slip style, still available.
• The Args: docstring is the label the machine actually reads.
• The default executor is an unlocked room.
• E2B or Docker is a real door.
• Authorized imports are the visitor list.

from smolagents import tool

@tool
def add(a: int, b: int) -> int:
    """Add two numbers.
    Args:
        a: left
        b: right
    """
    return a + b

The docstring is part of the mechanism. Treat it like code.

Code agents exist because a dozen round trips for a simple loop burn time and tokens. The risk exists because running model-written Python is running code. Those two sentences are the whole product decision. Speed in the pen, walls around the pen.

Mental model: a script in a pen, not a slip for every step. If the pen has no walls, you do not have an agent platform. You have a model with a shell.

You can explain the page if you say why code can beat tool-calling on multi-step jobs, and why “local” does not mean “safe.”