Getting Started with Hugging Face smolagents

smolagents is Hugging Face’s lightweight library for code agents—agents that write and run Python (or call tools) to finish a task. Docs: huggingface.co/docs/smolagents · code: github.com/huggingface/smolagents.

For after-work learners it is a friendly on-ramp: small API surface, HF ecosystem models, and a clear “agent as a loop that may execute code” mental model.

Who this is for

Python learners who already run scripts and want a first tool-calling / code-agent without standing up a full orchestration platform. If pip install still feels scary, finish a few Intro lessons first.

Overview: Top 10 AI agent tools for after-work Python.

Steps to start tonight

1. Create a venv and install

python -m venv .venv
source .venv/bin/activate
pip install -U smolagents
# plus any model backend extras the current docs list

Follow the install line on huggingface.co/docs/smolagents—extras change.

2. Pick one model access path

Either a cloud API key (e.g. HF token / OpenAI-compatible) or a small local model if the docs’ local path fits your machine. Write the choice in NOTES.md. One path only tonight.

export HF_TOKEN=...   # if your chosen path needs it

3. Run the shortest CodeAgent (or ToolCallingAgent) sample

Copy the minimal example from the docs. Ask something constrained: “Compute 17 * 19 and return only the number.” Watch whether the agent used a code step or a tool.

4. Add one custom tool

Define a tiny @tool (or equivalent decorator/class from the docs) like word_count(text: str) -> int. Re-run with: “How many words are in: after work python?” Confirm your tool appears in the trail.

5. Turn off the playground urge

Do not wire Gradio, Spaces, and three models on night one. Save that for weekend #2.

Tiny exercise (20–30 minutes)

Change the tool to slugify(text: str) -> str (lowercase, spaces → -). Ask the agent to slugify “Hello Smol Agents”. If it invents a slug without calling the tool, tighten the tool description and system prompt—do not add five more tools.

Pitfalls

• Letting the agent eval anything on your laptop with no sandbox story. Start with the docs’ recommended safe defaults; never point it at secrets folders.
• Pulling a huge local model “because HF.” Use the smallest path that runs.
• Skipping the printed steps. The lesson is the trail, not the final number.
• Hard-coding tokens in notebooks you will push.
• Comparing every agent framework tonight. Ship one smolagents run first.

Why this fits after work

One venv, one agent, one tool—weekday-sized. You learn code-agent behavior without a platform tax.

Next step

When tool traces feel readable, strengthen Python with Intro to Python Programming so the code the agent writes is code you can also write by hand.