Most of the confusion about agents disappears once you see how little is inside one. This lesson gives you that picture, then helps you decide when an agent is worth building at all.
A model, a loop and some tools#
A language model on its own answers once and stops. An agent is that same model placed in a loop, with a short list of things it is allowed to do:
- The model reads the task and decides what to do next.
- A tool is a normal function you wrote: search a list, read a file, call an API. The model asks for it by name; your code runs it.
- The result goes back to the model, which decides again: use another tool, or give the final answer.
That is the whole trick. The model never runs anything itself. Your code stays in charge of what actually happens, which is exactly why you can make an agent safe.
while (steps < MAX_STEPS) { const turn = await model(history) // 1. the model decides if (turn.done) return turn.answer // 2. it is finished const result = await runTool(turn.tool) // 3. your code does the work history.push(turn, result) // 4. the model sees what happened}Agent, or just a prompt?#
A loop adds cost, delay and more ways to fail. Reach for it only when the task needs something a single answer cannot give you:
- The answer depends on information the model does not have, such as your notes, your database or today's data.
- The number of steps is not known in advance: "find the right file, then fix it, then run the tests".
- It has to act, not only answer: create a ticket, send a message, change a file.
Tip
Start with the simplest thing that could work. If one well-written prompt gets you 90% of the way, ship that. Add a tool only when you can name the exact thing the prompt cannot do.
What you will build in this path#
Over five lessons you will build a small notes assistant: you ask it a question, it searches your notes with a tool, and it answers from what it finds. It is deliberately boring, because boring is easy to test. Every idea in it (tools, the loop, limits, testing) carries straight over to bigger agents.
- Lesson 2: set up your machine and make your first call to a model.
- Lesson 3: build the loop and the search tool.
- Lesson 4: write tests and fix what fails.
- Lesson 5: add limits and safety checks before anyone else uses it.