AGENTS · INTRODUCTION · ROADMAP
An agent is not a model.
It is a loop.
roadmap.sh’s AI Agents Roadmap organizes into twelve stages what it takes to design, build, and ship agents: from tokens and temperature to MCP, memory, architectures, evals, and red teaming. This note is the introduction: what each stage covers, which ideas hold everything else up, and where to start.
01 / THE WHOLE MAP
Twelve stages.
One system.
The roadmap reads top to bottom, but the stages are not silos: each one solves a problem that shows up in the previous one.
- 01
Prerequisites
An agent is software that calls APIs, reads files, and runs on a server. Without that base, everything else is magic.
Backend basics · Git and terminal · REST APIs - 02
LLM fundamentals
What the model is, what it sees, what it costs, and which knobs change its output.
Transformers · tokenization · context window · temperature, top-p, penalties, stopping criteria · open and closed weight models - 03
The basics
Product decisions that show up before you write the first loop.
Streaming · reasoning models · fine-tuning vs. prompting · embeddings · RAG · pricing - 04
AI Agents 101
The roadmap’s core: perceive, reason, act, observe, repeat.
What an agent is · what a tool is · the agent loop · use cases - 05
Prompt engineering
How to ask the model for something in a way you can verify.
Specificity · context · examples · format · iteration · Chain-of-Thought · Tree-of-Thought - 06
Tools and actions
What turns text into effects on the world.
Tool definition · input and output schema · error handling · web search, REPL, DB, APIs, email, filesystem - 07
Model Context Protocol
A standard to connect tools and data without rewriting integrations for every app.
Hosts · clients · servers · building servers · local vs. remote - 08
Memory
What the agent keeps, where, and when it lets go.
Short term · long term · episodic vs. semantic · RAG, profiles, summarization, and forgetting - 09
Architectures
Recurring ways to organize the loop depending on the problem.
RAG agent · ReAct · planner-executor · DAG · multi-agent · self-critique - 10
Building agents
Three abstraction levels for the same loop.
From scratch · native function calling (OpenAI, Gemini, Anthropic) · frameworks (LangChain, LangGraph, LlamaIndex, CrewAI, AutoGen…) - 11
Evaluation and observability
How to know it works, and why it failed when it does not.
Metrics · tool unit tests · flow tests · human-in-the-loop · structured logging and tracing - 12
Security and ethics
What happens when the agent holds real permissions and reads untrusted input.
Prompt injection · sandboxing and permissions · PII · bias and toxicity · red teaming
02 / THE CORE
Perceive. Reason.
Act. Observe.
The “AI Agents 101” section is the one to understand first, because everything else extends it.
- 01 · PERCEIVE
Input
The user request, the last tool result, an event, or a file. Everything arrives as context.
- 02 · REASON
Plan
The model decides the next step: answer, ask for more data, or call a tool with certain arguments.
- 03 · ACT
Tool call
Your code—not the model—executes the action, with validation and permissions.
- 04 · OBSERVE
Reflection
The result returns to the context. The loop continues until a stopping criterion is met.
Pseudocode. Almost any agent—with or without a framework—is a variation of this.
messages = [system, user_request]
for step in range(MAX_STEPS):
reply = llm(messages, tools=TOOLS)
if not reply.tool_calls:
return reply.text # stopping criterion
for call in reply.tool_calls:
result = run_tool(call) # validation + permissions
messages.append(result) # observation
raise StepBudgetExceededTwo details of the loop explain much of the roadmap. First, the model never executes anything: it proposes an action and your code decides whether to run it. That is where validation, permissions, and sandboxing live. Second, the loop needs an explicit stopping criterion—a final answer, a step limit, a token budget—because a model has no built-in notion of “enough.”
Before the loop, the roadmap asks for LLM fundamentals for a practical reason: every turn resends the full context. Tokenization, context windows, and per-token pricing stop being theory when an agent takes fifteen steps and each one drags the history along. Temperature, top-p, and stopping criteria matter because an agent needs consistent output, not creative output.
03 / TOOLS AND MCP
A tool is a contract.
MCP makes it portable.
The roadmap breaks a tool down into four parts. None of them is optional.
NAME AND DESCRIPTION
This is what the model reads to decide when to use it. An ambiguous description produces wrong calls.
INPUT AND OUTPUT SCHEMA
Explicit types, required fields, and allowed values. The model proposes arguments; the schema validates them.
ERROR HANDLING
A useful error tells the agent what to fix. “500” does not; “date must be ISO-8601” does.
USAGE EXAMPLES
A couple of concrete cases prevent more mistakes than another paragraph of instructions.
Examples the roadmap lists: web search, code execution (REPL), database queries, API requests, email, Slack or SMS, and filesystem access. Each has a different blast radius, and that should be reflected in its permissions.
The app where the agent lives: an IDE, a desktop chat, your product.
Keeps a 1:1 connection with each server, inside the host.
Exposes tools, resources, and prompts. Runs locally (stdio) or remotely (HTTP).
Without a standard, every integration gets written once per app and per model. MCP separates who uses a capability from who provides it: you write a server for your database or internal API, and any compatible host can use it. The roadmap includes building your own servers and choosing between local and remote deployment.
Portable does not mean safe. A third-party server is code with access to your data, and its tool descriptions enter the model’s context. Treat it like any dependency: review it, constrain it, and audit it.
04 / MEMORY
The model does not remember.
The system does.
An LLM is stateless between calls. All memory is something your code stores and puts back into the context.
Within the prompt
The conversation history and tool results. It is fast but finite: it competes for the context window and is billed per token.
Vector DB · SQL · custom
What survives across sessions: preferences, facts, documents. It must be retrieved explicitly, usually with RAG.
What happened
Concrete events: “Tuesday’s deploy failed because of the migration.” It helps avoid repeating mistakes.
What is true
Distilled general facts: “this repo uses Postgres 16.” It avoids rediscovering the same thing.
Maintaining memory is as much about pruning as adding. The roadmap names four strategies: RAG over vector databases, user-profile storage, history summarization and compression, and forgetting or aging policies. Without the last two, memory grows until it becomes expensive noise.
05 / ARCHITECTURES
Six shapes
for the same loop.
They are not exclusive; a real system usually combines two or three. The useful question is when each one is justified.
Retrieves documents before answering.
The answer depends on private or changing knowledge.
Alternates reasoning and action step by step.
The path is unknown upfront and each observation changes the next step.
One step plans; another executes each subtask.
The task is long and a reviewable plan before acting pays off.
Nodes in a graph without cycles; independent work runs in parallel.
The flow is known and you want traceability and per-stage retries.
Specialized roles that hand work to each other.
There is real specialization; otherwise it only multiplies cost and failure points.
The agent reviews and fixes its own output.
A verifiable criterion exists to judge the output, not just another opinion.
A SANE DEFAULTStart with the simplest system that solves the problem: sometimes a single call with RAG, sometimes a fixed workflow. Add autonomy, planning, or more agents only when an evaluation shows the simple version falls short.
06 / BUILDING
Write the loop by hand
once.
The roadmap offers three abstraction levels. It pays to walk them in order.
- 01
From scratch
Direct API calls, your own loop, output parsing, and error and rate-limit handling. The best way to understand what everything else does.
- 02
Native function calling
Providers (OpenAI, Gemini, Anthropic) return structured tool calls. Fragile parsing disappears; the loop is still yours.
- 03
Frameworks
LangChain, LangGraph, LlamaIndex, Haystack, CrewAI, AutoGen, Agno, and others handle orchestration, memory, and integrations. They speed you up, but they also hide the loop.
Framework and API names change fast: the roadmap still lists OpenAI’s Assistants API, which the provider itself replaced with the Responses API. What does not change is the loop. If you understand it, switching frameworks is a migration; if not, it is starting over.
07 / PRODUCTION
What separates a demo
from a system.
The roadmap’s last three stages are the ones tutorials skip most and production weighs most.
EVALUATE
Success, cost, and latency metrics; unit tests per tool; end-to-end flow tests; human review where the criterion cannot be automated. Tools cited: LangSmith, DeepEval, Ragas.
OBSERVE
Structured logging and tracing for every step: prompt, tool call, result, tokens, and time. Tools cited: LangSmith, Helicone, Langfuse, OpenLLMetry.
PROTECT
Prompt injection and jailbreaks, tool sandboxing and permissions, PII redaction, bias and toxicity guardrails, and red teaming before granting real access.
An agent that reads external content—a web page, an email, an issue—can receive instructions hidden in that content. That is why security is not added at the end: it is decided when you define which tools exist, which permissions they hold, and which actions require human approval.
WHERE TO START
One loop. One tool.
One metric.
- Review the fundamentals until you can estimate the token cost of a ten-step conversation.
- Write the minimum loop against a provider API, without a framework, with a single read-only tool.
- Define a success metric and ten test cases before adding the second tool.
- Add tracing from day one: every step, every tool call, every token.
- Only then add memory, MCP, a more complex architecture, or a framework, one at a time and measuring.
08 / KEEP GOING
Each stage,
in depth.
Notes on this site that go deeper into parts of the roadmap.
09 / SOURCES
The roadmap
and its foundations.
The roadmap is the map; every node links to its own reading. These are the ones behind this introduction.
- 01AI Agents Roadmap · roadmap.sh↗
- 02Content for every roadmap node · GitHub↗
- 03Building effective agents · Anthropic↗
- 04Model Context Protocol specification↗
- 05ReAct: Synergizing Reasoning and Acting in Language Models · Yao et al.↗
Editorial synthesis based on the public version of the roadmap available on October 15, 2026. The twelve-stage grouping follows the roadmap’s order; explanations and recommendations are my own.