- In short
- A custom agent loop sends messages, inspects stop_reason, executes the requested tools, appends the results, and repeats until the model ends the turn. Hooks intercept tool calls to enforce deterministic behaviour such as validation or blocking, independent of the model judgement. For high-stakes or irreversible actions, deterministic enforcement through hooks is preferred over relying on a prompt instruction.
When you build the loop yourself
The Claude Agent SDK runs the agentic loop for you, and most of the time that is the right call. But the Claude Certified Developer - Foundations (CCDV-F) exam expects you to understand what happens when you need control the SDK does not give you, and that means building a custom loop or harness yourself and using hooks to make certain actions deterministic. This is an apply-level knowledge point: you are expected to reason about how the loop runs and where enforcement belongs.
A custom agent loop is a precise sequence. You send the current messages to the model. You inspect the stop_reason on the response to learn what the model wants next. If the model requested tools, you execute them, append their results to the conversation, and send the updated messages back. If the model ended the turn, you stop. That cycle, send, inspect, execute, append, repeat, is the entire mechanism, and building it by hand is what gives you control the SDK's built-in version does not expose.
- Custom agent loop
- A hand-built agentic loop that sends messages, inspects the stop_reason, executes any requested tools, appends their results, and repeats until the model ends the turn. Building it yourself gives control the SDK's built-in loop does not, at the cost of owning the mechanics.
stop_reason is the control signal
The single most important detail in a custom loop is that stop_reason is the authoritative signal for what to do next. When the model wants to call a tool, the response carries a tool-use stop reason, and your loop's job is to run those tools and continue. When the model is finished, the stop reason says the turn has ended, and your loop terminates. You branch on that field, not on anything else.
This is where the first exam trap lives. It is tempting to look at the model's text and decide the task is done because it said something like "all set" or "that completes the request." That is a natural-language cue, and it is unreliable: the model can produce closing-sounding text while still intending to call another tool, or continue when you expected it to stop. The stop_reason field is the structured, deterministic signal that actually tells you the state of the turn, so terminating on prose instead of on stop_reason is a correctness bug the exam specifically probes.
Hooks make actions deterministic
The second half of this knowledge point is enforcement. In a custom harness you can add hooks that intercept tool calls, and a hook enforces deterministic behaviour independent of the model's judgement. When the model requests a tool, the hook runs first: it can validate the arguments, block the call outright, or otherwise apply a rule in code before the action ever happens. Because the hook is code the runtime executes, it behaves the same way every time, regardless of what the model concluded in its reasoning.
This is the property that makes hooks the right tool for high-stakes or irreversible actions. Deterministic enforcement through hooks is preferred over prompt instructions precisely because a prompt is probabilistic. A system prompt telling the agent "never delete production data" is guidance the model usually follows, but usually is not a guarantee, and for an irreversible deletion, usually is not good enough. A hook that intercepts the delete tool and refuses any call targeting production enforces the rule with certainty, because the model is not in the loop for that decision.
What the CCDV-F exam trips candidates on
The exam tests two traps here, and both are about trusting the wrong signal.
The first is relying on a prompt instruction to prevent a destructive action instead of a hook that enforces it deterministically. A scenario will describe an agent that can perform some irreversible or high-stakes action, and a design that tries to prevent misuse with a strongly worded system prompt. The credited answer recognises that prompt instructions are probabilistic and cannot guarantee the outcome, so a hook that intercepts the tool call and blocks it is the correct enforcement mechanism for anything that must never happen.
The second is terminating the loop on natural-language cues instead of the stop_reason field. A scenario will show a loop that ends when the reply "looks finished," and ask why it behaves unpredictably. The answer is that the loop must branch on stop_reason, the structured signal, rather than on the wording of the model's text. Both traps reward the same instinct: prefer the deterministic, structured signal over the model's probabilistic behaviour or prose.
Worked example
An agent can run shell commands, including deletions. The team's safeguard is a system prompt line reading 'Never delete files outside the workspace.' In testing it behaves, but a reviewer flags the design. What is wrong and how should it be fixed?
The reviewer is right, and the reason is the difference between guidance and guarantee. The system prompt line is a prompt instruction: probabilistic influence the model usually honours but can reason around, especially on an unusual input or in a long conversation. For an irreversible action like a deletion, a single failure is unacceptable, and usually-safe is not safe enough. Testing looked clean because the model was attentive on the handful of cases tried, which is exactly what hides the gap.
The fix is a hook. In the custom loop, intercept the shell-command tool before it executes and inspect the requested path. If the deletion targets anything outside the workspace, the hook blocks the call and returns a refusal as the tool result, so the model sees the action was denied and continues without performing it. Because the hook is code, it enforces the boundary deterministically on every call, independent of whatever the model concluded, which is the guarantee the prompt could never provide.
Note the loop mechanics stay intact around the hook. The model still requests the tool via a tool-use stop_reason, the hook adjudicates, the result is appended, and the loop continues on the same stop_reason-driven cycle. The hook adds deterministic enforcement without changing how the loop decides what to do next.
Common misreadings to avoid
Misconception
A strongly worded system prompt is enough to stop an agent from taking a destructive action.
What's actually true
Misconception
It is fine to end the agent loop when the model's reply reads as finished.
What's actually true
How this shows up on the exam
Domain 1 questions on this knowledge point are applied. They give you a loop or an enforcement decision and ask you to spot the flaw or choose the mechanism. If the question is about how the loop continues, the answer turns on inspecting stop_reason and executing the requested tools until the model ends the turn. If the question is about preventing a costly or irreversible action, the answer is a deterministic hook, not a better-worded prompt.
This knowledge point deepens the Agent SDK fundamentals that precede it, since the custom loop is the same gather-context, take-action, verify-work cycle built by hand. It also connects forward to context concerns, because a long-running loop accumulates tool results, which is exactly the pressure that agent memory and context-window management addresses. Owning the loop is what lets you insert enforcement and manage context deliberately rather than hoping the defaults are enough.
A custom agent loop must reliably decide when to run tools and when to stop, and must guarantee it never issues a refund above a set limit. Which design is correct?
People also ask
How does a custom agent loop work?
What is stop_reason used for in an agent loop?
When should I use a hook instead of a prompt instruction?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
No videos curated for this concept yet
We are still curating the best official and community videos for this topic.
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.