The Agentic Loop
Every agentic system follows the same core loop: receive input, reason, act (tool call), observe results, decide to continue or stop. The loop is governed by stop_reason in the API response.
| stop_reason | Meaning | Loop Action |
|---|---|---|
| end_turn | Claude finished voluntarily | Exit loop — task complete |
| tool_use | Claude wants to call a tool | Execute tool, feed result back, continue |
| max_tokens | Output limit reached | May need continuation logic |
Key rule: Always set a maximum iteration limit to prevent infinite loops. Feed tool errors back to Claude — it can often self-correct.
Orchestration Patterns
| Pattern | When to Use | Key Characteristic |
|---|---|---|
| Prompt Chaining | Sequential transformation steps | Output of step N is input to step N+1 |
| Routing | Different input types need different handling | Classification step dispatches to specialists |
| Parallelization (Fan-Out/Fan-In) | Independent subtasks | Split, process concurrently, aggregate |
| Evaluator-Optimizer | Iterative quality improvement | Generate, evaluate, refine until threshold met |
| Orchestrator-Worker | Dynamic subtask decomposition | Central agent plans, delegates, synthesizes |
| Anti-Pattern | Why It Fails |
|---|---|
| Over-orchestrating simple tasks | Single Claude call often sufficient — added latency for no benefit |
| Sharing mutable state between parallel agents | Race conditions and inconsistent results |
| No exit condition on loops | Infinite loops burning tokens and time |
| Routing without a fallback | Unclassified inputs get dropped silently |
Guardrails
Three types: input guardrails (validate before Claude sees it), output guardrails (validate Claude's response before returning to user), tool-use guardrails (restrict which tools and parameters are allowed).
In the Agent SDK: guardrails run as parallel checks alongside the main agent. They can halt execution immediately if a violation is detected.
Claude Agent SDK Primitives
| Primitive | Purpose |
|---|---|
| Agent | Defines system prompt, tools, guardrails, and handoff targets |
| Runner.run() | Manages the agentic loop internally |
| @tool decorator | Registers a function as a tool with auto-generated schema |
| @guardrail decorator | Registers input/output validation functions |
| Handoff | Transfers control from one agent to another |
Multi-Agent vs Single-Agent Decision
Use single agent when: one tool set covers the task, shared context is critical, latency matters.
Use multi-agent when: tasks need fundamentally different tool sets, domain expertise varies, you need isolation between concerns.