How Does the Agent Loop Work?

An agent loop repeatedly sends the current state to a model, interprets the model’s response, executes allowed tool calls, records their results, and asks the model what to do next. The loop ends on a final answer, policy denial, approval pause, budget limit, cancellation, unrecoverable error, or explicit completion condition.

What will you be able to do?

You will trace a run as state transitions, distinguish one model turn from one application run, and design stop conditions that do not depend on the model deciding to behave.

What is the mental model?

The model is a planner inside an event loop, not the loop itself.

An SDK performs much of this plumbing, but your application still owns the boundary around it.

What state changes during a run?

Represent a run as an append-only event stream:

The conversation is useful model context. The event stream is operational truth. Do not confuse them.

How would you build the smallest loop?

This pseudocode exposes the responsibilities that an SDK later implements:

Notice what the model does not own: identity, permission, timeout, budget, checkpointing, or final verification.

How do you prove the loop works?

Test transitions, not prose:

1. A final response produces run.completed without a tool event.
2. A permitted tool produces proposal, policy, start, and completion events in order.
3. A denied tool never reaches its handler.
4. An approval-required tool produces a serializable checkpoint.
5. A repeated mutating request uses the same idempotency key.
6. Exhausted turns produce budget_exhausted, not a fake success.

Failure injection: Configure a tool to time out. The loop should record a classified failure, apply only its configured retry policy, and either choose a safe alternative or stop. It must not retry forever.

What is a real stop condition?

Use multiple, independent stops:

• final answer with required schema;
• task-specific acceptance check;
• maximum model turns;
• maximum tool calls;
• wall-clock deadline;
• token or monetary proxy budget;
• repeated-state/cycle detection;
• human cancellation;
• policy denial or unavailable approval; and
• provider/runtime failure.

“The prompt says stop when finished” is guidance, not enforcement.

What mistakes should you avoid?

• Logging only the final answer.
• Counting retries at several layers and multiplying traffic.
• Treating a tool error message as trusted instruction.
• Replaying a mutating tool without idempotency.
• Resuming from conversation text without the policy and budget state.

Check your understanding

1. What is the difference between model context and operational state?
2. Which component authorizes a tool call?
3. Why must stop conditions exist outside the prompt?

Expert extension

Draw the state machine for running, waiting_for_approval, retry_scheduled, succeeded, failed, and cancelled. Define which transitions are legal and which events make each transition auditable.

Official references

• OpenAI: Running agents
• Claude: How the agent loop works