Building AI Agents — Worked Examples

A hands-on tour of how to build AI agents two different ways. No prior experience with AI or large language models (LLMs) is assumed. Start here, then follow whichever track fits you.

---

What is an agent? (30-second version)

A large language model (LLM) like Claude is, at its core, a text predictor: you give it text, it gives you text back. On its own it can talk, but it cannot do anything — it can't read your files, search the web, or run code.

An agent is an LLM that has been given:

1. Tools — actions it is allowed to take (search a database, run a script, send an email). The model decides when to use them; your code actually runs them.
2. A loop — after a tool runs, the result is fed back to the model so it can decide the next step. The model keeps taking steps until the task is done.

That's the whole idea. Everything else (skills, MCP, permissions) is about giving the agent more and better capabilities, safely.

  You ─▶ "Find the most-cited paper on transformers and summarize it."
          │
          ▼
   ┌──────────────┐   wants to search   ┌─────────────┐
   │  LLM (Claude)│ ──────────────────▶ │  search tool │
   │  decides     │ ◀────────────────── │  (your code) │
   │  next step   │   here are results  └─────────────┘
   └──────┬───────┘
          │  (loops until done)
          ▼
       Final answer

---

Key words, in plain English

Term	What it means
LLM	The AI model that reads and writes text (here: Claude).
Prompt	The text you send the model.
System prompt	Standing instructions that shape how the model behaves ("You are a careful research assistant").
Tool	An action the model can ask to take. You define it and run it.
Tool use / function calling	The mechanism by which the model asks to use a tool.
Agent loop	Repeating "model thinks → tool runs → result goes back" until finished.
Skill	A reusable bundle of instructions (and sometimes scripts) the agent loads only when relevant — like a cheat-sheet it opens when the task calls for it.
MCP	Model Context Protocol — a standard way to plug external tools/data sources into an agent, so you don't hand-write every integration.

---

The three tracks

Three ways to build agents with Claude. They share the same ideas; they differ in who writes the loop and where it runs.

Track 1 — Claude Code (configure an agent with files)

Claude Code is a ready-made agent that runs in your terminal. You don't write the agent — you configure it by dropping a few files in your project. Fastest way to see skills, tools, and MCP working.

→ Best if you want results in minutes and prefer editing config over writing code.

Track 2 — Anthropic SDK (Python) (build an agent in code)

The low-level SDK: call Claude from your own Python program and build the agent loop yourself. More work, but total control — and the best way to understand what an agent actually is.

→ Best if you want to learn the mechanics or need control over every step.

Track 3 — Claude Agent SDK (Claude Code as a library)

The middle layer: Claude Code's whole agent — loop, built-in tools, skills, MCP, permissions — as a Python library. One query() call runs a complete agent.

→ Best if you want to ship a capable agent from Python with minimal code.

Bonus — Operating agents well (a cheat sheet, not a track)

Once your agent works, there's a separate skill: keeping it cheap, lean, and resumable across sessions. Right-size the model, cache, batch, prune context, write decent tool descriptions, leave a progress log.

This isn't a fourth track — there's no progressive teaching here. It's a one-page reference + two template files. Read it once, copy what you need.

→ Best for week 2 of any project. The operational stuff doesn't matter until it suddenly does.

---

How they map to each other

Concept	Claude Code (Track 1)	Anthropic SDK (Track 2)	Agent SDK (Track 3)
The agent loop	built in	you write it	built in (query())
Talk to the model	type in the terminal	client.messages.create(...)	query(prompt=...)
Tools	built in + MCP	you define + run them	built in + @tool
Skills	SKILL.md file	system prompt / Managed Agents	same SKILL.md files
MCP	.mcp.json file	mcp_servers=[...] param	mcp_servers={...} option
Permissions	.claude/settings.json	your own if checks	allowed_tools / permission_mode

Suggested order for beginners: Track 1 (see it work) → Track 2 (understand it) → Track 3 (ship it). Check the bonus when you start to care about cost or session-to-session continuity.

Read PLAN.md for the design rationale and how these files were built.

Pick a track and open its README.md.