Start Here

Why "data in, data out" is the whole trick

Every piece of software you will ever touch, from a one-line function to a trillion-parameter language model, can be squashed into the same three-box picture:

   ┌───────────┐        ┌─────────────────┐        ┌───────────┐
   │  INPUT    │──────▶ │  TRANSFORMATION  │──────▶ │  OUTPUT   │
   └───────────┘        └─────────────────┘        └───────────┘

A function is input → return value. An HTTP request is request → response. A chat model is message history → next message. An agent is question → (maybe some tool calls) → answer. Once this picture is burned into your head, nothing in this book is "magic" anymore - it's just bigger and bigger versions of the same box. Every diagram in every chapter is a variant of this same shape, because that repetition is the actual teaching method here, not a stylistic tic.

The destination

By the last chapter you will have built this, from scratch, understanding every line:

┌─────────────────────────────────────────────────────────────────────┐
│                         YOUR AGENT PROJECT                          │
│                                                                       │
│   You type a question                                                │
│        │                                                             │
│        ▼                                                             │
│   ┌─────────┐      ┌───────────────┐      ┌─────────────────────┐    │
│   │  Agent  │─────▶│ Provider layer│─────▶│  LM Studio (local)  │    │
│   │  loop   │      │ (swap engines)│  or  │  OpenAI (cloud)     │    │
│   │         │◀─────│               │◀─────│  Anthropic (cloud)  │    │
│   └─────────┘      └───────────────┘      └─────────────────────┘    │
│        │                                                              │
│        ▼                                                              │
│   Can call tools (calculator, web search, files...)                   │
│        │                                                              │
│        ▼                                                              │
│   Answer, grounded, with memory of the conversation                   │
└─────────────────────────────────────────────────────────────────────┘

You'll start 100% local and free (LM Studio, no API key, no internet needed for the model itself) and only later add cloud providers - because that's the cheapest and safest way to learn the mechanics without burning API credits on your mistakes.

Why local-first? If you make a mistake in an infinite loop that calls an LLM a thousand times, doing it against LM Studio on your own machine costs you a warm laptop. Doing it against a paid API can cost you real money before you notice. We only introduce billing once you understand exactly what triggers a call.

The map (read in this order)

Each chapter can be read alone if you already know some of it, but they build on each other. If you skip ahead and something feels like it came from nowhere, it's almost always defined one or two chapters earlier - the table above tells you where to look back.

One idea that repeats through the whole book

Every single tool you'll meet - pip, pyproject.toml, HTTP, JSON, an LLM's chat API, an agent's tool-calling - is solving the same underlying problem: two things that don't know about each other's internals need to exchange data in a shape they both agree on.

   Thing A                 AGREED SHAPE (contract)                Thing B
┌───────────┐        ┌───────────────────────────────┐        ┌───────────┐
│  your     │──────▶ │ JSON / TOML / HTTP / function  │──────▶ │  someone  │
│  code     │        │ signature / API schema...      │        │  else's   │
│           │◀────── │                                │◀────── │  code     │
└───────────┘        └───────────────────────────────┘        └───────────┘

package.json is that contract for npm. pom.xml is that contract for Maven. pyproject.toml is that contract for Python. An LLM's messages list is that contract for a conversation. A "tool call" JSON blob is that contract between a model and your Python function. Once you see this pattern once, every new tool in this book gets easier, not harder.

Common mistake: treating each new tool as an unrelated thing to memorize. If you instead ask "what is thing A, what is thing B, and what's the agreed shape between them?" every chapter from here on collapses into the same five-minute mental exercise.

A worked mini-example of "the contract" before you've written any code

Even before Chapter 1, you can see the pattern in something you already know: a restaurant order.

   Customer                    THE MENU (the contract)                 Kitchen
┌────────────┐        ┌─────────────────────────────────┐        ┌────────────┐
│ "I'll have │──────▶ │ Item name + size + modifiers,    │──────▶ │ cooks the  │
│  a burger" │        │ written on a ticket the kitchen  │        │ exact item │
│            │◀────── │ already knows how to read        │◀────── │ back out   │
└────────────┘        └─────────────────────────────────┘        └────────────┘

The customer doesn't need to know how the kitchen works internally, and the kitchen doesn't need to know why the customer wants a burger. They only need to agree on the ticket format. That's it - that's every API you'll ever use.

What to install before Chapter 1

1. Python 3.11+ - python.org (check "Add to PATH" on Windows)
2. A code editor - VS Code is fine, free
3. LM Studio - lmstudio.ai (we install and configure it properly in Chapter 5, don't worry about it yet)
4. A terminal you're not afraid of (Terminal.app, Windows Terminal, or VS Code's built-in one)

Confirm your install worked before moving on:

python3 --version
# Python 3.11.x  (or newer)

If that command fails, fix it now - every later chapter assumes it works. On Windows, the command is often python --version instead of python3 --version; try both.

Common mistake: installing Python but not checking "Add to PATH" on Windows, then wondering why python3 is "not recognized" in every terminal you open. Reinstalling with that box checked fixes it in under a minute.

How to actually use this book

• Every code block that starts with ```python in this book is meant to be run, not just read. Type it out yourself at least once per chapter, even if you're sure you already know it. Muscle memory beats recognition.
• When a diagram shows boxes and arrows, pause and say out loud what's in each box before reading the explanation underneath it. That's the actual comprehension check.
• Each chapter ends with a short "Check yourself" list. If you can't answer one without looking back, that's fine - it just tells you exactly what to re-read.

That's it. Let's start.