Building Agents on the API
- Define what an agent actually is: a model running in a loop
- Apply the decision test to choose single call vs workflow vs agent
- Design a minimal agent loop with the right guardrails
- Know when to reach for the Claude Agent SDK instead of hand-rolling
- Make an agent robust: bound it, handle failures, restrict privilege, evaluate it
An agent is a model running in a loop: it pursues a goal by calling tools, observing results, and deciding the next step until done. Before you build one, pick the simplest thing that works.
The decision test (don't over-build)
Not every task needs an agent. Walk this tree first — most tasks stop at the top.
Three options, simplest first:
- Single call — one prompt answers it. Most tasks. Cheapest, most reliable.
- Workflow — you orchestrate a fixed sequence of calls in code (deterministic control flow). Use when steps are known.
- Agent — the model decides the steps dynamically. Use only when the path genuinely can't be hardcoded.
Reach for an agent when adaptivity is the point — not because it sounds impressive. A workflow you control is easier to test and debug.
Designing the loop
A minimal custom agent is just four moving parts. Build them in this order:
- State the goal, the constraints, and the available tools. This is what the model reasons against on every turn.
- Send messages → if the response is a tool_use, run the tool, append a tool_result, and repeat → until a final answer or a stop condition.
- Add a max-iterations cap, a token/cost budget, and validation of tool inputs before anything runs.
- Summarize or trim as the history grows — the same idea covered in Context Management (/docs/claude-code/context-management).
The Claude Agent SDK gives you this loop — tools, permissions, context handling — batteries included, so you don't hand-roll it.
Before writing your own loop, ask whether the Agent SDK already covers it. It ships the loop, permissions, and context handling so you can focus on the tools and the goal.
Make it robust
A loop that can call tools can also misbehave. Four habits keep an agent trustworthy:
- Bound everything: iterations, time, cost. Agents can loop.
- Handle tool failures gracefully (return the error as a result).
- Least privilege + human-in-the-loop for risky actions — see Securing Agents.
- Evaluate it on real cases before trusting it — see Evals and the dedicated Evaluating Your AI Agent playbook for trajectory-level scoring and a CI gate.
- An agent is a model in a loop calling tools toward a goal — use one only when the path can't be hardcoded
- Decision order: single call → workflow → agent → managed agents; prefer the simplest that works
- A minimal loop = system prompt + tool_use/tool_result loop + guardrails + context management
- The Claude Agent SDK ships the loop, tools, permissions, and context handling for you
- Robustness = bound iterations/time/cost, handle tool failures, least privilege + human-in-the-loop, and evaluate before trusting