Builds a tool-using agent loop

Building agents · competency building-agents/builds-agent-loop

Taught in: the Building agents course

Draws on: Tool use, The agent loop and harness, Agentic retrieval and memory

Learning objectives

Defines a tool with a schema the model uses correctly (base)

Claim	Why	Example
The tool description says when to use the tool and when not to, as well as what it does.	The model chooses tools from their descriptions, and a description that only names the function leads to it being called for the wrong job.	"Look up a customer by exact account id; do not use for name searches, use search_customers instead" cuts wrong calls that "Get customer" invites.
Every parameter has a type, a description and, where the set is small, an enum, so the model cannot invent a value.	A free-text parameter where a fixed set was meant produces near-misses such as "EUR" against a code that expects "eur".	currency becomes an enum of the four supported codes and amount is documented as "integer cents, not a decimal".
The tool returns errors as structured results the model can read and act on, rather than raising through the loop.	An exception that escapes ends the run, but an error message in the result lets the model retry, ask or give up on purpose.	On a missing record the tool returns {"ok": false, "error": "no account 4711"} and the model tells the user instead of the process crashing.

Served by: Building your first agent, What a tool call looks like on the wire, When a tool fails, Writing a tool schema the model uses correctly

Implements the loop with error handling and a stop condition (base)

Claim	Why	Example
The loop has an explicit iteration limit and a token or cost budget, and stops cleanly when either is hit.	A model that keeps finding one more thing to do will run until the bill or the timeout stops it.	The loop stops after twelve turns or a set spend and returns "stopped: budget reached" together with what it has so far.
The loop ends when the model replies without a tool call, and the learner can point to the line that checks this.	The natural stop condition of an agent loop is the model deciding it is done, and if the code does not honor that, the loop never ends or ends by accident.	The learner shows the branch that returns the final text when the response has no tool calls, and the test that covers it.
A tool failure is fed back into the conversation as a result, and the loop continues or stops by policy rather than by an unhandled exception.	Real tools time out, return garbage and hit rate limits, and the agent has to keep working through that.	A timed-out HTTP call becomes a tool result saying so, and after two of them in a row the loop stops and reports instead of retrying forever.

Served by: Building your first agent, Several tool calls in one turn, Stopping the loop on purpose, When a tool fails

Adds retrieval or memory and knows when basic RAG is enough (base)

Claim	Why	Example
The learner starts with basic retrieval (embed, search, put the top results in context) and adds an agentic loop only when the basic version measurably fails.	A retrieve, evaluate, refine loop costs several model calls per question, and most questions do not need it.	On the evaluation set, basic RAG answers 85 percent, so the learner adds a second retrieval step only for the questions where the first result set was empty or off topic.
The learner picks the memory store by how the memory is used: a file for a handful of facts, a database for structured lookup, a vector index for similarity.	Reaching for a vector database for twenty facts adds infrastructure and hides what the agent knows.	The agent's "user preferences" memory is a JSON file per user, read at session start.
The learner tests retrieval with questions whose answer is in the documents and questions whose answer is not, and checks the agent says so in the second case.	A retrieval system that answers everything is one that invents answers when the documents have none.	The evaluation set includes "what is the refund policy for gift cards" where no such policy exists, and the expected answer is "not found".
The learner tells the model what came from retrieval and what to do when it does not answer the question.	Retrieved text without a frame is treated as instructions or as the model's own knowledge.	The prompt says "The passages below were retrieved for this question. Answer only from them, and say if they do not cover it."

Served by: Where an agent's memory lives, Retrieval as a tool the agent calls

Rebuilds the loop on an agent SDK and explains what the SDK took over (expert)

Claim	Why	Example
The learner can name what the SDK does that their hand-written loop did: message handling, tool dispatch, retries, stop conditions, streaming.	Knowing what was taken over is what lets the learner debug the SDK's version when it behaves differently [1].	The learner points at the SDK's tool dispatch and explains where their own version's error handling went.
The learner keeps the stop conditions and budgets explicit in SDK code, rather than trusting defaults.	SDK defaults are chosen for demos, and a production agent needs its own limits.	The learner sets the maximum turns and a cost cap in the SDK configuration and tests that both stop the agent.
The learner can say what the SDK makes harder and where they would drop to the raw API.	An SDK is a set of choices, and knowing which ones do not fit is part of using it.	The SDK's context management compacts history in a way that drops the tool results the learner's evaluation needs, so the learner turns it off for the evaluation run.

Served by: Rebuilding the loop on an agent SDK

Alignment

Framework	Code	Asks	Objectives here
Ng, AI engineering skills map	Building and deploying AI applications	Build, evaluate, ship	defines-a-tool, implements-the-loop, adds-retrieval, uses-an-sdk

References

1. Anthropic. Claude Platform 101. Claude Academy. Course. Academy claude-platform-101