ai-agents-foundations
Agents I: Foundations
Building agents with open language models in Python, from the loop to a coding agent
by Hernán Díaz Rodríguez, PhD · Professor at the University of Oviedo
The book
Agents I: Foundations teaches how to build agents: programs in which a language model decides the next step, carries it out with tools, looks at the result and decides again until the task is done. Over twelve chapters, the operations agent of North Cycles, a bicycle store in Portland, Oregon, learns to process returns, change sizes, prepare quotes and notify customers: the agent loop, tools, planning, reflection, exploring alternatives, memory, skill libraries, orchestration patterns, frameworks (smolagents and LangGraph), evaluation and security. The last chapter builds a coding agent that fixes the code of one of the store’s programs.
Everything is programmed from scratch in Python, with a loop of a few lines that grows chapter after chapter, and with free, open models, with no API keys or paid services: Qwen3-4B-Instruct-2507 on Colab’s free GPU and, without a GPU, Qwen3-1.7B. Every task is checked by the state the store is left in, not by what the agent says, and every figure in the book comes from an experiment you can repeat in the chapter’s notebook. This edition is not a plain translation: the store, its data and every experiment are its own, run in English.
It belongs to the AI in Practice series: hands-on books on artificial intelligence, with original experiments, a notebook and a video in every chapter.
¿Prefieres español? La edición española, Agentes I: fundamentos, está en la raíz del repositorio.
Chapters
Each chapter has its notebook on Google Colab and its video, with Robotín and the author. All the videos are in the YouTube playlist.
| Ch. | Title | Notebook | Video |
|---|---|---|---|
| 1 | The agent loop |  |
 |
| 2 | Using tools | |
|
| 3 | Planning and executing | |
|
| 4 | Reflection and self-correction | |
|
| 5 | Exploring alternatives: trees of thoughts | |
|
| 6 | Memory | |
|
| 7 | Skill libraries | |
|
| 8 | Workflow patterns and orchestration | |
|
| 9 | Agent frameworks compared | |
|
| 10 | Evaluating agents | |
|
| 11 | Failures, prompt injection and observability | |
|
| 12 | Project: a terminal coding agent | |
|
How to use the notebooks
- Click Open in Colab and run the cells in order. The first cell installs the library versions the book was checked with.
- Turn on the free GPU: Runtime → Change runtime type → T4 GPU. The model takes about 8 GB and the first time it takes a few minutes to download. Without a GPU, the notebooks choose Qwen3-1.7B by themselves, smaller and slower, which fails quite a bit more as an agent.
- The notebooks download the files of the
data/folder by themselves the first time. - On a T4, the notebooks take from about twenty minutes to more than an hour. The figures may change slightly with another GPU or other library versions.
Data
North Cycles and all its data are fictional. The agent’s tools work on a copy of the store that is reset for every test, so you can make mistakes without consequences.
| File | Contents | Chapters |
|---|---|---|
orders.json |
The store’s orders, with customer, products, status and dates | 1 to 4 and 6 to 11 |
stock.json |
The units of each product by size and the restock dates | 1 to 11 |
catalog.json |
40 products with category, price and description | 2 to 11 |
returns_project/ |
The small returns program, with its tests, that the agent fixes | 12 |
hidden_tests/ |
The tests the agent does not see, to check whether it really fixes the bug | 12 |
License
This material is distributed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) license: it can be used and adapted for teaching and study, crediting the author, but not for commercial purposes. The models used by the notebooks have their own licenses: Qwen3 (Apache 2.0) and multilingual-e5-base (MIT). smolagents and LangGraph are distributed under the Apache 2.0 and MIT licenses, respectively.