AI Agents Crash Course
All of AI agents on one page — what an agent is, tools, the loop, planning, memory, multi-agent systems, evaluation, safety, and how to debug them
AI Agents Crash Course
Start here
This single page covers all of AI agents at working depth. Read it start to finish in about 30 minutes and you will understand what an agent is, how the loop works, which decisions matter, and what to do when it misbehaves.
Every section ends with a Go deeper link to a full page on that topic. Read this first, then follow the links for whatever you need in detail.
| Property | Value |
|---|---|
| Level | Everyone — starts from zero, ends at production |
| Reading time | ~30 minutes |
| Prerequisites | None. Knowing what an LLM is helps, but is not required. |
| You will understand | The whole of agents, well enough to design, build, and debug one |
1. What an Agent Is
A normal LLM call is one shot. Text in, text out. The model cannot look anything up, cannot take an action, and cannot check its own work.
An agent wraps that model in a loop and gives it tools.
| Part | What it means |
|---|---|
| The model | Decides what to do next |
| Tools | Functions it can ask you to run — search, database, API, calculator, code |
| The loop | Think → act → look at the result → think again, until the task is done |
| Stopping rule | How it knows it is finished |
The one-sentence definition
An agent is a language model that decides its own next step, in a loop, using tools, until it reaches a goal.
The important word is decides. A fixed sequence of model calls is a workflow. An agent chooses its own path as it goes.
Chatbot, workflow, agent
| Chatbot | Workflow | Agent | |
|---|---|---|---|
| Path | One reply | Fixed steps, always the same | Decided at run time |
| Tools | None | Maybe, at fixed points | Yes, chosen by the model |
| Predictable? | Yes | Yes | No |
| Cost | 1× | 2–4× | 3–20× |
| Debuggable? | Easy | Easy | Hard |
| Use when | The answer is in the model | You know the steps | You cannot know the steps in advance |
Most things called agents should be workflows. If you can write down the steps in advance, write them down — you get something cheaper, faster, testable, and far easier to debug. Use an agent only when the steps genuinely depend on what earlier steps return.
Go deeper: What Is an Agent?
2. Watch the Loop Run
This is the core mechanic. Press play:
The agent loop, step by step
The task
“What was our Q3 revenue in Europe, and how does it compare to last year?”
I need Q3 revenue for Europe, and the same figure for last year to compare.
The model is not answering. It is deciding what to do next. This is the whole difference between an agent and a chatbot.
Two things to notice. The model never runs a tool — it asks, and your code decides whether to comply. And the context only ever grows: every observation is added and nothing is removed, which is why long agent runs hit the context limit and why managing that is a real design problem.
Two things to take from that:
- The model never runs a tool. It outputs a request to call one. Your code decides whether to comply. That boundary is where every safety control you will ever add belongs.
- The context only grows. Every result gets appended and nothing is removed. Long runs eventually hit the model's limit — managing that is real work, not an edge case.
Go deeper: The Agent Loop
3. Tools
Tools are how an agent affects anything outside its own text. Without them you do not have an agent.
How a tool call actually works
One tool call, end to end
What a tool definition looks like
name: get_revenue
description: Look up revenue for one region and quarter. Use this for any
question about sales figures. Do NOT use it for forecasts.
parameters:
region (string, required) One of: Europe, Americas, APAC
quarter (string, required) One of: Q1, Q2, Q3, Q4
year (integer, required) Four-digit year, e.g. 2025The description is a prompt, not documentation. It is the only thing the model has to decide with. "Gets data" gives it nothing. Say what the tool does, when to use it, and when not to — that last part prevents more wrong calls than anything else.
Tool rules that matter
| Rule | Why |
|---|---|
| Keep the list short | Choice quality drops noticeably past ~15 tools, especially if several sound alike |
| Use enums, not free text | region: "Europe" | "APAC" prevents a whole class of bad arguments |
| Validate before running | Never execute what the model asked for without checking it first |
| Return useful errors | "No records matched" teaches the agent something. A bare empty result does not. |
| Never return a silent failure | An error string looks like data to the model, and it will use it as data |
Go deeper: Tools & Function Calling
4. Planning and Reasoning
For anything beyond two or three steps, an agent that just reacts tends to wander. Planning helps.
| Approach | How it works | Best for |
|---|---|---|
| ReAct | Think, act, observe, repeat. Decide one step at a time. | Short tasks; exploring |
| Plan-and-execute | Write the whole plan first, then carry it out | Longer tasks; keeps the agent on track |
| Decomposition | Break a big goal into named subtasks | Complex work with clear parts |
| Reflection | After acting, ask "did that work? what now?" | Quality-sensitive work |
Planning first is usually worth it past about three steps. A plan gives the agent something to check itself against, which is what stops the classic failure where it drifts off and forgets the original goal. The trade-off is that a plan made before seeing any data can be wrong — so let the agent revise it.
Go deeper: Planning & Reasoning
5. Memory
The model remembers nothing between calls. Every request must carry everything it needs to know. "Memory" is what you build to manage that.
| Type | What it holds | How long |
|---|---|---|
| Working memory | The current run — thoughts, tool calls, results | This task only |
| Short-term | The current conversation | This session |
| Long-term | Facts about the user, past decisions, learned preferences | Forever, in a database |
Context is not free and it is not unlimited. Every observation you append costs money on every subsequent call, and models read the middle of a long context less reliably than the ends. Do not paste raw tool output into the transcript — summarise it, and keep a compact running state separate from the full history.
Go deeper: Memory and Context Engineering
6. One Agent or Many?
When one agent is not enough, there are standard ways to coordinate several. Each one costs more.
What each coordination pattern costs
No agent at all. One prompt, one answer. Always try this first.
Read the task and answer it
Wall-clock time so far
0 ms
One call was 900 ms
Cost so far
0.00 units
One call was 1.00
Run them all. Two results are worth sitting with: the router can beat a single call on cost, because it sends easy work somewhere cheap. And parallel workers cost three times more but finish almost as fast as one, because you wait for the slowest, not the sum.
| Pattern | Shape | Use when |
|---|---|---|
| One call | No agent at all | The task fits in one prompt — always try this first |
| Chain | Fixed steps in order | You know the steps in advance |
| Router | Classify, then send down one path | Traffic is mixed and most of it is easy |
| Parallel | Split, run at once, merge | The parts do not depend on each other |
| ReAct agent | Think, act, observe, repeat | You cannot know the steps in advance |
| Orchestrator + workers | Planner delegates to specialists | The task needs different kinds of expertise |
| Debate / evaluator | One produces, one critiques, repeat | Quality matters more than cost |
Multi-agent systems are the most over-used idea in this field. They multiply cost, latency, and failure modes. Two agents that need to agree can disagree; a planner becomes a single point of failure; and a bug can now hide in the handoff between agents. Reach for one only when a single agent has measurably failed at the task.
Go deeper: Multi-Agent Systems and Orchestration Patterns
7. Measuring an Agent
Agents are harder to evaluate than a normal model call, because a right answer reached by a stupid route is a problem waiting to happen.
Measure two things
| What | Question | Why it matters |
|---|---|---|
| Outcome | Did it get the right result? | The thing you actually care about |
| Trajectory | Did it get there sensibly? | A lucky right answer will not stay right |
| Metric | Meaning |
|---|---|
| Task success rate | Fraction of tasks completed correctly. The headline number. |
| Steps per task | Efficiency. A rising average means the agent is wandering. |
| Tool error rate | How often calls fail. Often the real cause of bad answers. |
| Cost per task | Agents are expensive and the variance is large — track p95, not just the mean. |
| Loop rate | How often it hits the iteration cap. Should be near zero. |
| Human handoff rate | How often it gives up. Directly maps to business value. |
Agents are not deterministic. The same input can take a different path on every run. Run each evaluation case several times and look at the distribution — a single passing run tells you almost nothing.
Go deeper: Evaluating Agents
8. Safety
An agent that can only write text is low risk. An agent that can send email, move money, or delete records is a different thing entirely.
| Risk | What it looks like | Control |
|---|---|---|
| Prompt injection | Instructions hidden in a web page, email, or document the agent reads | Treat all fetched content as data, never as instructions |
| Excessive permissions | The agent can do more than the task needs | Give each tool the narrowest scope that works |
| Destructive actions | Deletes, payments, sends — no undo | Require human approval; make them reversible where possible |
| Runaway cost | A loop that never ends | Hard caps on iterations, tokens, and money |
| Data leakage | Secrets pasted into a prompt or sent to a tool | Scrub inputs; never put credentials in the context |
The most important rule in agent safety: the model produces a request, and your code decides whether to honour it. Never wire a model's output straight into an action that matters. Validate, check permissions, and put a human in front of anything you cannot undo.
Go deeper: Safety & Security
9. When It Breaks
Agent bugs all look the same from outside — "it did the wrong thing". The trace tells you the real story.
Why did the agent do that?
Did the agent call any tool at all?
Open the trace and look at the first few steps. An agent that never acts and an agent that acts wrongly are completely different bugs.
Notice that “the model reasoned badly” is the last leaf, not the first. Most agent failures are mechanical — a tool that never reached the model, a vague description, an error string the agent read as data. Reach for a bigger model only after the boring causes are ruled out.
Common symptoms and their real causes:
| Symptom | Usual cause |
|---|---|
| Ignores a tool you gave it | The tool never reached the model, or the description is vague |
| Picks the wrong tool | Two tools sound alike, or the list is too long |
| Bad arguments | Loose schema — free text where an enum belonged |
| Loops forever | No clear finish condition, and no iteration cap |
| Stops too early | The prompt never said what "done" looks like |
| Forgets the goal midway | Context filled up, or no plan to check itself against |
| Confidently wrong after a tool failed | The tool returned an error string and the agent read it as data |
| Works, then fails identically later | It is non-deterministic — it was always going to sometimes fail |
Go deeper: Failure Modes & Debugging
10. Production Essentials
| Area | The thing you must get right |
|---|---|
| Hard limits | Cap iterations, tokens, and cost per task. Non-negotiable. |
| Tracing | Log every thought, tool call, argument, and result. Without a full trace you cannot debug anything. |
| Timeouts | Every tool call needs one. One hanging API should not hang the agent. |
| Retries | Retry transient failures with backoff. Do not retry a bad argument — fix it. |
| Idempotency | A retried action must not run twice. Especially payments and sends. |
| Cost tracking | Per task, not per call. Watch p95 — agent cost has a long tail. |
| Human handoff | Design the give-up path deliberately. It will be used. |
| Model version pinning | Behaviour changes between versions. Pin, then test before upgrading. |
Go deeper: Production & Operations and Designing an Agent System
11. Vocabulary You Need
| Term | Meaning |
|---|---|
| Agent | A model that decides its own next step, in a loop, using tools |
| Tool / function calling | Letting the model request that your code run a function |
| ReAct | Reason + Act — the think/act/observe loop |
| Trajectory | The full path an agent took, step by step |
| Trace | The logged record of that path |
| Observation | The result of a tool call, fed back to the model |
| System prompt | The standing instructions given on every call |
| Context window | Maximum tokens the model can read at once |
| Token | The unit models read and bill by — roughly ¾ of a word |
| Orchestrator | An agent that plans and delegates to others |
| Worker / specialist | An agent given one narrow job |
| Handoff | Passing control and context from one agent to another |
| Reflection | An agent reviewing its own output before continuing |
| Guardrail | A check that blocks unsafe input, output, or action |
| Prompt injection | Malicious instructions hidden in content the agent reads |
| Human in the loop | A person approving an action before it happens |
| MCP | Model Context Protocol — a standard way to expose tools to models |
| Idempotent | Safe to run twice with the same effect as running once |
Go deeper: Glossary
12. The Twelve Rules
| # | Rule |
|---|---|
| 1 | Try one LLM call first. Then a workflow. An agent last. |
| 2 | If you know the steps, write them down. That is a workflow, and it is better. |
| 3 | The model requests, your code decides. Never wire output straight to action. |
| 4 | Tool descriptions are prompts. Say when to use it and when not to. |
| 5 | Fewer tools work better. Past ~15, choice quality falls. |
| 6 | Always cap iterations, tokens, and cost. Every agent, no exceptions. |
| 7 | Say what "done" looks like. Most loops come from an unclear finish line. |
| 8 | Never return a silent tool failure. Errors read as data. |
| 9 | Context only grows — manage it. Summarise; do not paste raw output. |
| 10 | Trace everything. No trace, no debugging. |
| 11 | Run evaluations many times. Agents are non-deterministic; one pass proves nothing. |
| 12 | Check the boring causes first. It is usually a tool or a description, not the model's intelligence. |
13. Where To Go Next
The fundamentals track
| Page | Covers |
|---|---|
| What Is an Agent? | Definitions, agent vs workflow, when not to use one |
| Tools & Function Calling | Schemas, the call cycle, errors, MCP |
| The Agent Loop | ReAct, iteration, termination, control flow |
| Planning & Reasoning | Decomposition, plan-and-execute, reflection |
| Memory | Working, short-term, long-term, retrieval |
| Context Engineering | System prompts, context budget, compaction |
| Multi-Agent Systems | Orchestrator-workers, handoffs, debate, and when not to |
| Evaluating Agents | Outcome vs trajectory, metrics, test sets |
| Safety & Security | Injection, permissions, sandboxing, human gates |
| Production & Operations | Limits, tracing, retries, cost, deployment |
| Failure Modes & Debugging | Symptom to cause across every stage |
| Designing an Agent System | A full worked design with real numbers |
| Glossary | Every term and abbreviation |
Then build one
| Project | Time |
|---|---|
| Tool Calling Agent | ~2 hours |
| ReAct Agent | ~4 hours |
| Planning Agent | ~5 hours |
| Multi-Agent System | ~3 days |