147 lines
4.4 KiB
Markdown
147 lines
4.4 KiB
Markdown
# Agent Loops: The Complete Guide
|
|
|
|
**June 15, 2026**
|
|
|
|
Every agent is a loop. The difference between a demo agent and a production agent is how well you control that loop.
|
|
|
|
---
|
|
|
|
## The Three Loop Types
|
|
|
|
### Type 1: Think → Act → Observe (Basic)
|
|
|
|
```
|
|
1. LLM decides what to do next (thinks)
|
|
2. Tool executes the decision (acts)
|
|
3. Result feeds back to LLM (observes)
|
|
4. Repeat until done
|
|
```
|
|
|
|
This is the simplest loop. Every lab in this course starts here. It works for single-step tasks where the agent calls one tool and returns an answer.
|
|
|
|
**Problem**: No bounded iteration. Without `MAX_ITERATIONS`, the agent loops forever on ambiguous tasks.
|
|
|
|
### Type 2: Plan → Execute → Verify (Guarded)
|
|
|
|
```
|
|
1. Agent plans the approach (tool selection + sequence)
|
|
2. Agent executes each step
|
|
3. Verifier agent checks each result
|
|
4. On failure: re-plan with new context
|
|
5. On success: proceed or terminate
|
|
```
|
|
|
|
The verifier is a second, simpler agent (or the same agent with a verification prompt) that checks output quality before the loop continues. This prevents the agent from confidently proceeding with wrong results.
|
|
|
|
### Type 3: Cascade (Multi-Model)
|
|
|
|
```
|
|
Step 1: Haiku (cheap) — bulk processing
|
|
→ Step 2: Sonnet (mid) — analysis
|
|
→ Step 3: Opus (premium) — synthesis, quality check
|
|
```
|
|
|
|
Each step uses a different model tier. Early steps are cheap and fast. Later steps are expensive but thorough. The cascade loop saves 60-80% on token costs compared to running everything through Opus.
|
|
|
|
---
|
|
|
|
## Termination Conditions
|
|
|
|
Every loop needs at least one termination condition. Production loops need three:
|
|
|
|
### 1. Content-Based Termination
|
|
|
|
The agent decides it's done:
|
|
|
|
```python
|
|
if response.stop_reason == "end_turn":
|
|
return response.text # Normal completion
|
|
elif response.stop_reason == "tool_use":
|
|
continue_loop() # Agent wants another turn
|
|
```
|
|
|
|
### 2. Hard Limit Termination
|
|
|
|
The loop has a maximum iteration count:
|
|
|
|
```python
|
|
MAX_ITERATIONS = 10
|
|
for i in range(MAX_ITERATIONS):
|
|
result = agent_step()
|
|
if result.is_done:
|
|
return result
|
|
return {"error": "Max iterations exceeded", "partial_result": result}
|
|
```
|
|
|
|
This is non-negotiable in production. Every lab includes it. Without it, a single bad prompt can cost you $50+ in runaway token usage.
|
|
|
|
### 3. Cost Budget Termination
|
|
|
|
The loop tracks cumulative cost and stops when the budget is spent:
|
|
|
|
```python
|
|
BUDGET_CENTS = 50
|
|
total_cost = 0
|
|
|
|
for i in range(MAX_ITERATIONS):
|
|
result = agent_step()
|
|
total_cost += result.cost_cents
|
|
if total_cost > BUDGET_CENTS:
|
|
return {"error": "Budget exceeded", "total_cost": total_cost}
|
|
if result.is_done:
|
|
return result
|
|
```
|
|
|
|
---
|
|
|
|
## Loop Anti-Patterns
|
|
|
|
### Grinding
|
|
|
|
The agent runs the same code repeatedly hoping for a different result:
|
|
|
|
```python
|
|
# BAD: no change between iterations
|
|
for i in range(100):
|
|
score = evaluate(agent_config)
|
|
if score > best_score:
|
|
best_score = score # same config, different random seed
|
|
```
|
|
|
|
**Fix**: Hash the agent configuration. If it hasn't changed, don't re-run.
|
|
|
|
### Hallucination Cascade
|
|
|
|
Each loop iteration builds on potentially wrong information from the previous step. By iteration 5, the agent's context is full of hallucinated facts, and it makes reasonable-looking decisions based on nonsense.
|
|
|
|
**Fix**: A verifier step after every tool call checks factual claims before they enter the context window.
|
|
|
|
### Infinite Loop by Design
|
|
|
|
Some tasks naturally loop (monitoring, polling). Without careful budgeting, these can run forever:
|
|
|
|
```python
|
|
# BAD: no cost tracking on long-running loops
|
|
while True:
|
|
data = check_api()
|
|
if data.alerts:
|
|
send_notification(data.alerts)
|
|
time.sleep(60)
|
|
```
|
|
|
|
**Fix**: Daily cost budget + max iterations even in "infinite" loops.
|
|
|
|
---
|
|
|
|
## The 5 Rules of Production Loops
|
|
|
|
1. **Always set MAX_ITERATIONS** — even in loops you expect to terminate naturally
|
|
2. **Always track cost per iteration** — you can't optimize what you don't measure
|
|
3. **Always verify intermediate results** — don't let bad context compound
|
|
4. **Always have a fallback** — what happens when max iterations is reached? Return partial results, don't crash
|
|
5. **Always log the loop** — every iteration should be recorded for debugging
|
|
|
|
---
|
|
|
|
*This is adapted from Module 1: Foundations of the [Agentic Engineering the Hard Way](/free-preview) course. Full course includes 65 lessons, 13 labs, and 20 skill kits.*
|