Agentic loops and control flow

Text description

• Model: Returns text, typed tool requests, other content blocks, and a stop reason.
• Application orchestrator: Interprets output, preserves conversation state, and decides whether to continue, stop, retry, or escalate.
• Tools and services: Execute permitted operations and return observations through the application.

Episode One builds the smallest reliable production agent, beginning with a model response and ending with a governed action loop. By the end, you should be able to draw every state transition, preserve the action-observation pair, and explain when the application should continue, stop, retry, or escalate. Now add the next layer: the control loop that turns a model call into an agentic system. Is an agent just a model with tools attached? Not quite. The surrounding loop must interpret model output, execute tools, preserve state, and decide when control returns to the user. With the Messages application programming interface, or A P I, your application constructs the request and retains the conversation state it needs for the next turn.

The model can return text, a tool-use request, or other content blocks, together with a stop reason. For the Foundations exam, the decisive stop reasons are tool use and end turn. When the stop reason indicates tool use, the application executes the requested tool and returns the result in the next message. When the stop reason is end turn, the loop normally stops and presents the result. Why not stop whenever the assistant emits some text that sounds final? Because natural language is not a reliable control signal and the assistant can emit explanatory text before requesting a tool. Parsing phrases such as task complete turns prose variation into a production state machine.

Text description

• Send request: Provide the retained messages and available tool definitions.
• Inspect response: Use the stop reason and typed content blocks as control signals.
• Execute permitted tool: Validate the request before invoking the selected capability.
• Append request and result: Preserve the assistant tool request and add the matching tool-result block.
• Request again or stop: Continue after tool use; normally present the result after end turn.

Why not stop after a fixed number of iterations? A safety ceiling is useful, but it should not be the primary semantic completion rule. A hard cap can interrupt a valid workflow or disguise a loop that is repeatedly failing. The normal loop is request, inspect, execute, append, and request again. When Claude requests a tool, preserve the assistant content containing that tool request in the history. Then append a user-side tool-result block that references the matching tool-use identifier. That pairing lets the model connect its requested action with the observation returned by the environment. Suppose Harbour Resolution receives the message that a customer was charged twice.

Claude first calls get customer using a stable customer identifier. The application checks the caller's authorisation, invokes the customer service, and returns a concise structured result. Claude may then call list transactions, compare candidate charges, and decide whether more evidence or human escalation is required. The model chooses among permitted next actions from the context, rather than following a prewritten branch for every possible complaint. When would a fixed decision tree be better? When the process is fully known, rules are stable, and variation provides little value. Many production systems should combine both approaches. A deterministic workflow might authenticate the user, retrieve the case, enforce limits, and create an approval task.

Text description

• Model proposes: Selects a permitted tool and supplies candidate input from the available context.
• Application governs: Checks tool name, schema, authorisation, policy, and idempotency requirements.
• Service enforces: Applies domain rules, transaction boundaries, and server-side controls before creating effects.

Within that workflow, Claude can interpret the complaint, choose relevant read-only tools, and draft the recommendation. This is a hybrid design rather than an ideological commitment to autonomy. What should happen before any tool actually runs? The application should validate the tool name, input schema, authorisation scope, and operational policy. It should also establish idempotency where repeated execution could create duplicate effects. A payment tool needs an idempotency key, transaction boundary, and server-side amount controls. The model should never be responsible for remembering whether the payment already happened. What if the tool input is structurally valid but semantically impossible, such as a negative payment amount?

The tool or service validates domain rules and returns a structured error instead of attempting to improvise. A useful error includes a stable code, a safe message, whether retry may help, and any fields the agent can correct. For example, invalid currency is different from temporary service unavailable. The first invites corrected input, while the second may justify bounded retry with backoff. Do not return a stack trace, secret, or raw database exception as model context. The tool adapter should normalise implementation-specific failures into a small error contract. How much tool output should be appended to the conversation? Enough for the next decision, but not an unbounded dump of every backend field.

Text description

• Independent calls: Read-only calls may run in parallel, with correct identifiers and deterministic result aggregation.
• Dependent calls: Run in order when a later request needs a value produced by an earlier one.

Verbose observations increase cost, distract reasoning, and can crowd out earlier facts. The durable record can retain the full response outside the model context, while Claude receives a safe task-relevant projection. The projection should preserve identifiers and provenance needed for later auditing. Consider a subtle control-flow problem. Claude requests two independent read-only tools in the same response. Should the application always execute them serially? No. Independent calls can run in parallel if their permissions, dependencies, and error handling allow it. Parallel execution reduces latency, but results still need correct identifiers and deterministic aggregation. Dependent calls must remain ordered when the second requires a value from the first.

The exam may present an agent that always invokes every available tool regardless of the request. What is wrong with that design? It increases latency, cost, attack surface, and irrelevant context, while preventing the model from selecting only the capabilities needed. However, sensitive workflows may deliberately constrain tool choice more tightly. Tool choice can be automatic, restricted to a specific tool, or disabled, depending on the task boundary. The architecture decides how much discretion is appropriate rather than assuming maximum autonomy. Let us inspect termination more carefully. Claude calls a lookup tool, receives not found, calls the same tool again with identical input, and continues repeating.

Text description

• Same lookup repeats: The model requests the identical tool with identical input after receiving not found.
• Detect and bound retries: Recognise repetition and apply the configured retry and loop limits.
• Return terminal tool error: Surface a clear structured failure rather than fabricating an answer.
• Escalate or end safely: Record the reason and state which facts remain unresolved.

The stop reason remains tool use, so the semantic loop has not completed. What controls should surround it? Detect repeated identical calls, apply bounded retries, surface a clear terminal tool error, and escalate or end safely. Record the reason rather than returning a fabricated answer. A loop budget is a containment control for pathological behaviour, not proof that the task succeeded. The final response should state unresolved facts when the evidence remains incomplete. Here is the loop you should be able to draw from memory. The orchestrator sends messages and tool definitions to Claude. Claude either ends the turn or emits one or more typed tool requests.

The orchestrator validates, authorises, executes, normalises, records, and returns each observation. The cycle continues until end turn, a governed escalation, a confirmed workflow state, or a safety boundary stops it. This adds application completion states without replacing the semantics of the A P I. Production orchestration combines model protocol with business protocol. Episode One is complete when you can draw the loop and explain every transition without relying on natural-language guesses. For source navigation, know where to confirm Messages content blocks, stop reasons, tool-use flow, strict tool handling, and Agent S D K control behaviour. In the next episode we will split this single loop across specialised subagents without losing control or context.