Agents
What happens when the model — not your code — decides what happens next.
Prerequisites
- Structured Output — tool calls are structured output with a runtime attached.
- Tokens & Context Windows — the transcript is the agent's state, and it grows every single turn.
- The RAG Pipeline — retrieval is the tool agents call most.
Why this section exists
A workflow is a program you wrote that happens to call an LLM. An agent is a program the model writes at runtime, one step at a time, out of the tools you gave it. That one difference — who owns control flow — is the axis every agent question rotates around.
It buys you the ability to handle tasks whose path you cannot enumerate in advance. It costs you almost everything you rely on as an engineer: determinism, testability, a bounded cost per request, and a stack trace that means anything.
Common misconception
Agents are often described as "an LLM that can use tools." Tools aren't the distinction — a workflow can call tools too. The distinction is that the sequence of steps is chosen by the model at runtime rather than by your code at design time. Everything else about agents follows from that one property.
The second common error is enthusiasm. The right answer to "should we build this agent?" is frequently "no — here's the workflow that solves it more cheaply and can actually be tested." Agents vs Workflows exists for exactly that decision.
What's in here
| Page | The question it answers |
|---|---|
| Agent Foundations | The loop itself, ReAct, and where state actually lives |
| Tool Calling | Schemas, parallel calls, and what to do when a tool fails |
| The Agent Harness | The runtime around the model — context, dispatch, sandbox, permissions — and how to build one |
| Agents vs Workflows | The maturity question: when not to build an agent |
| Orchestration & Memory | State machines, checkpointing, short- vs long-term memory |
| Harness vs Orchestration | Which layer owns which concern, and where the words stop meaning anything |
| Multi-Agent Systems | Supervisor and handoff patterns, and when the extra agents earn their tokens |
| Agent Reliability | Loops, tool hallucination, compounding error, human-in-the-loop gates |
Where this connects
- MCP — the standard way to plug tools into an agent without writing a bespoke integration per tool.
- Evals & Testing — non-determinism means outcome-based evals replace assertions; this is where that discipline lives.
- Security — an agent with a shell tool is remote code execution by design; permission tiers are not optional.
- Design: Customer Support Agent — the whole section assembled into one working system.