# Building agents

> Build an agent from a model, a loop and tools.

Page: https://schubergphilis.github.io/ai-training/building-agents/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

From a bare model API to a working agent, one mechanism at a time.

## Tool use

- [What a tool call looks like on the wire](https://schubergphilis.github.io/ai-training/building-agents/how-a-model-calls-a-tool/): The request, the tool_use reply, the tool_result message and the final answer of one real API tool call, mapped onto the fake model of the first agent lesson.
- [Building your first agent](https://schubergphilis.github.io/ai-training/building-agents/agent-loop/): Define one tool, run the loop that lets a model call it, and see why the loop is the whole architecture.
- [Writing a tool schema the model uses correctly](https://schubergphilis.github.io/ai-training/building-agents/tool-schemas/): Give a fake model two overlapping tools, watch it pick the wrong one, and fix that with a description that says when to use the tool and an enum the model cannot guess around.
- [When a tool fails](https://schubergphilis.github.io/ai-training/building-agents/tool-errors/): Break a tool on purpose, return the failure as data the model can read, and give the loop a retry policy with a named stop reason.
- [Approving a risky tool call](https://schubergphilis.github.io/ai-training/building-agents/approving-a-tool-call/): Make the loop stop before a refund tool runs, show a person the call and its exact arguments, and send a refusal back to the model as the tool's result.
- [Several tool calls in one turn](https://schubergphilis.github.io/ai-training/building-agents/parallel-tool-calls/): Let the fake model ask for three weather lookups in one reply, run them together and return the results as one message, then watch a fourth call that needs the first result wait for its own round.

## The agent loop and harness

- [Stopping the loop on purpose](https://schubergphilis.github.io/ai-training/building-agents/stopping-the-loop/): Give the agent loop every reason it needs to stop, run three fake models that never answer, and name the rule that ended each run.
- [Rebuilding the loop on an agent SDK](https://schubergphilis.github.io/ai-training/building-agents/loop-on-an-sdk/): Put the weather agent on the Claude Agent SDK, name the five parts of the hand-written loop the SDK took over, set the turn and cost limits the defaults leave open, and see where the SDK's compaction gets in the way of an evaluation.

## Agentic retrieval and memory

- [Retrieval as a tool the agent calls](https://schubergphilis.github.io/ai-training/building-agents/retrieval-as-a-tool/): Build a keyword search as a tool, run it once per question and then in a bounded loop against a twelve-document handbook, and use a six-question test set to decide which version a question needs.
- [Where an agent's memory lives](https://schubergphilis.github.io/ai-training/building-agents/agent-memory/): Compare five places an agent can keep what it should know tomorrow, start with a notes file a person can read, see what changes when that file grows to ten thousand lines, and see how memory files and compaction keep an agent's context window small.

## Evaluation and testing

- [Turning good into a rubric](https://schubergphilis.github.io/ai-training/building-agents/rubrics/): Score twelve runs of a handbook assistant on five quality pillars, rewrite "well grounded" as an anchored 0-1-2 criterion two graders agree on, and check it against a model judge on a sample.
- [A golden set is the agent's regression suite](https://schubergphilis.github.io/ai-training/building-agents/golden-sets/): Run a golden set of fifteen handbook questions with the qualities a good answer has, predict what a one-line prompt change breaks, hold one item in five back for release, and add two items.
- [Recording and grading the path the agent took](https://schubergphilis.github.io/ai-training/building-agents/traces-and-trajectories/): Give an invoice assistant's loop a trace of every model and tool call, grade two runs with the same answer by the path they took, write the expected path for a lookup as a rule, and read two transcripts the scores passed.
- [Reading failures one by one](https://schubergphilis.github.io/ai-training/building-agents/error-analysis/): Read a handbook assistant's ten failed runs of one week, one at a time, name the step where each went wrong, count the kinds, fix the most common one first, and turn every failure into a golden-set item.
- [A model as the grader](https://schubergphilis.github.io/ai-training/building-agents/llm-as-judge/): Have a stand-in judge with a length bias grade runs of a handbook assistant, compare its scores with a person's, and pair numbers that rise on their own with ones that catch them.

## Design patterns

- [Workflows before agents](https://schubergphilis.github.io/ai-training/building-agents/workflows-before-agents/): Run a chain with a gate, a route and parallel calls on a shop's emails, with code deciding the order of the fake model calls, and tell those tasks apart from one that needs an agent that chooses its own steps.
- [Reasoning before each action](https://schubergphilis.github.io/ai-training/building-agents/react/): Give the fake model a one-line thought before each tool request, compare its trace with the plain loop's on the same tasks, and see when the reasoning changes the call and what it costs.
- [A second pass that critiques the first](https://schubergphilis.github.io/ai-training/building-agents/reflection/): Run a fake critic and reviser on four handbook answers, see a critic without criteria loop on a trivial edit, and bound the pattern with concrete checks, a cap of two rounds and a view of what each round costs.
- [Writing the plan before taking the steps](https://schubergphilis.github.io/ai-training/building-agents/planning/): Have the fake model write a numbered plan before any tool runs, work through it, and see a stale plan send a false email until the model revisits the plan after each step.
- [Plan everything first or react step by step](https://schubergphilis.github.io/ai-training/building-agents/plan-or-react/): Place plan-then-execute and reactive agents on one spectrum, compare a fixed workflow with an agent, count what six patterns cost at twelve steps, and name what is lost between levels of plans and at each handoff of a composition.

## Orchestration and multi-agent

- [Orchestration in code or by a model](https://schubergphilis.github.io/ai-training/building-agents/orchestrating-agents/): Run three fake agents as a pipeline in code and then under a manager model that calls two of them as tools, name the sequential, hierarchical and collaborative arrangements, and stop the run with a report when a fault hits a boundary.
- [What every extra agent costs](https://schubergphilis.github.io/ai-training/building-agents/orchestration-tax/): Count the tokens that a pipeline and a manager with workers spend on handoffs and repeated context next to a single agent, name the rest of the tax, ask what one agent can't do, and compare both designs on the same golden set.

## Guardrails and production

- [How a running agent gets attacked](https://schubergphilis.github.io/ai-training/building-agents/agent-attack-surface/): Name the four risks that appear once a model can act, count the outbound channels in a support agent's permission list, see what a planted line does when the system prompt is the only layer, and cut the agent down to what its task needs.
- [Guardrails in layers](https://schubergphilis.github.io/ai-training/building-agents/guardrails-in-layers/): Add a permission check, an output filter for account numbers and an approval gate one at a time around a shop's support agent, run the planted recipe page after each, read in the trace which layer acted, and say what each layer catches and misses.
- [Gating a deploy on the evaluation](https://schubergphilis.github.io/ai-training/building-agents/eval-gated-deploys/): Turn the golden set script into a gate with a threshold per metric, predict what it does with a prompt that drops one instruction, fix the prompt from the failing transcripts, and plan a staged rollout with a rollback that is a configuration change.
- [Growing the evaluation set from traces](https://schubergphilis.github.io/ai-training/building-agents/evals-from-traces/): Read a weekly sample of the handbook assistant's traces, label each run good or bad, find the failures the golden set has no case for, strip personal data from them, and add them as cases that the deploy gate runs on the next change.
- [Cost, caching and pinning the model](https://schubergphilis.github.io/ai-training/building-agents/cost-and-provider-operations/): Give an agent loop a cost record and a token budget, cache the prompt prefix that never changes, retry the provider errors that go away after a wait and report the others, and pin the model id.
- [Protocols for tools and for other agents](https://schubergphilis.github.io/ai-training/building-agents/agent-protocols/): See how the Model Context Protocol and agent-to-agent protocols such as A2A turn N x M integrations into N plus M, what an Agent Card declares, and why each connection is a trust decision that the defense layers of a support agent still have to cover.