AI Agents — The Complete Guide

A from-scratch guide to what AI agents are, how they work, and how to actually build them. 16 chapters, fully available in English and Italian, plus a static website, PDF editions, and 5 self-contained runnable Python examples.

🇮🇹 Parli italiano? Vai al README in italiano.

---

🌐 Read it online

English website	https://myfirstaiagent.netlify.app/en/
Sito in italiano	https://myfirstaiagent.netlify.app/
PDF (English)	Guide-AI-Agents-EN.pdf
PDF (Italiano)	Guida-Agenti-AI.pdf

The website includes full-text search (Cmd/Ctrl + K), a chapter-aware tutor, and an interactive playground.

---

What this is

Most AI-agent material is either a marketing blog post or a framework tutorial that hides the mechanics. This guide sits in between: it explains the mechanism first, then shows the code.

No machine-learning background required. If you can read Python, you can follow every example.

It's for you if:

• "I hear about AI agents everywhere but I still don't get what makes them different from ChatGPT."
• "I want to use AI to work better, but I don't know where to start."
• "I can code, but I've never built an agent. Where do I begin?"
• "I tried a chatbot and it disappointed me. Can this be done better?"

Every chapter follows the same structure:

1. Concept — the theory, explained plainly.
2. Practice — concrete examples, code, real workflows.
3. Key takeaways — the 3–5 things that matter.
4. Common mistakes — the traps nearly everyone falls into.

---

Table of contents

Part 1 — Foundations (understanding)

1. What AI Agents Are
2. How LLMs Work (the engine)
3. Anatomy of an Agent
4. Types of Agents and Architectures

Part 2 — Core techniques (talking to them)

5. Prompt Engineering: the Art of Asking
6. Tool Use and Function Calling
7. Memory, Context and RAG

Part 3 — Using agents (day to day)

8. Using AI Chatbots: ChatGPT, Claude.ai, Gemini
9. Claude Code: Terminal-Based Agent for Developers

Part 4 — Building agents (hands on)

10. Building Custom Agents with API and SDK
11. Frameworks: LangChain, AutoGen, CrewAI

Part 5 — Doing it well (quality and responsibility)

12. Best Practices for Development with Agents
13. Security, Costs, Limits
14. Evaluation and Improvement

Part 6 — Applications

15. Real Use Cases and Workflows
16. Glossary and Resources

The Italian chapters live in the repository root (01-*.md … 16-*.md) and are indexed in README.it.md.

---

Runnable examples

Five standalone Python projects in examples/, each mapped to a chapter. No shared state, no framework, pinned dependencies — read them top to bottom like pseudocode.

Folder	Chapter	What it demonstrates
01-agent-loop	Ch. 3	The minimal agent loop: ~70 lines, 2 tools, readable as pseudocode.
02-tool-use	Ch. 6	Real tool design: precise schemas, structured error handling, idempotency keys.
03-rag-minimal	Ch. 7	End-to-end RAG: chunking, embedding, retrieval, generation with citations.
04-prompt-caching	Ch. 10	Production-grade agent: prompt caching, retry with backoff, cost tracking.
05-eval-harness	Ch. 14	Eval harness: .jsonl dataset, programmatic checks, LLM-as-judge, A/B testing.

Run the examples

git clone https://github.com/GabrieleBottai01/AgentiAI.git
cd AgentiAI/examples/01-agent-loop

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

export ANTHROPIC_API_KEY="sk-ant-..."
python main.py

Examples default to claude-haiku-4-5 to keep costs low. Running all five costs well under $0.10. API keys are always read from environment variables, never hardcoded.

---

🌍 Two languages

The guide is written and maintained in both languages — not machine-translated stubs. Both versions have all 16 chapters, both are on the website, both have a PDF edition.

	English	Italiano
Chapters	en/	root (01-*.md … 16-*.md)
Website	myfirstaiagent.netlify.app/en/	myfirstaiagent.netlify.app
PDF	Guide-AI-Agents-EN.pdf	Guida-Agenti-AI.pdf
README	this file	README.it.md

Technical terms (prompt, tool, token, embedding) are kept in English in the Italian edition too — that's the vocabulary you'll meet in the documentation you read next.

---

Repository structure

AgentiAI/
├── 01-*.md … 16-*.md      # 16 chapters — Italian (source of truth)
├── en/                    # 16 chapters — English (source of truth)
├── examples/              # 5 standalone runnable Python projects
├── build_site.py          # Markdown → static bilingual website
├── build_pdf.py           # Markdown → PDF (EN + IT)
├── website/               # BUILD OUTPUT — deployable static site
├── static-js/             # Site sources: search, tutor, playground, i18n
├── site/                  # Earlier Flask prototype (kept for reference)
├── DEPLOY.md              # Deploy guide: Netlify / Vercel / GitHub Pages
└── docs/AVANZAMENTO.md    # Progress log & project decisions (Italian)

The Markdown files are the source of truth. website/ is generated — never edit it by hand.

Build the site and the PDFs yourself

python3 -m venv .venv && source .venv/bin/activate
pip install markdown beautifulsoup4 pygments reportlab

python3 build_site.py    # → website/
python3 build_pdf.py     # → PDF, EN + IT

Then open website/index.html, or serve the folder with python3 -m http.server -d website.

The site is plain HTML/CSS/JS — no framework, no bundler, no node_modules. Deployment instructions for Netlify, Vercel and GitHub Pages are in DEPLOY.md.

---

How to get the most out of it

• Don't read passively. Keep ChatGPT, Claude, or a terminal open next to you and try every example.
• Fail early. Agents are learned by using them, not by studying them. The guide gives you the vocabulary; practice gives you the intuition.
• Come back. The early chapters only fully click after you've built something in chapters 8 and 10.

---

Author

Gabriele Bottai Portfolio · GitHub · LinkedIn · X

Found a mistake, or something explained badly? Open an issue — corrections in either language are welcome.

---

© 2026 Gabriele Bottai