The Agentic Loop Pattern

• Send request to Claude with tools defined → Inspect stop_reason → Execute tools if needed → Return results → Repeat
• The loop continues while stop_reason === 'tool_use' and exits when stop_reason === 'end_turn'
• Tool results MUST be appended to conversation history so Claude can reason about the next action
• Claude decides which tool to call based on context — NOT pre-configured decision trees

stop_reason Values

Anti-Patterns to Avoid

• Parsing natural language to determine loop termination — always use stop_reason
• Setting arbitrary iteration caps as the primary stopping mechanism
• Checking for assistant text content as a completion indicator
• Pre-configuring tool call sequences instead of letting Claude reason

Hub-and-Spoke Architecture

• Coordinator manages ALL inter-subagent communication, error handling, and information routing
• Subagents do NOT inherit the coordinator's conversation history — context must be explicitly passed
• Coordinator responsibilities: task decomposition, delegation, result aggregation, deciding which subagents to invoke
• All communication routed through coordinator for observability and control

Subagent Design Principles

Context Passing

• Context is EXPLICIT — must be provided in the prompt; no automatic inheritance or shared memory
• AgentDefinition config includes: descriptions, system prompts, and tool restrictions per subagent
• Each subagent has its own isolated conversation; coordinator aggregates results

Error Handling Patterns

• Return descriptive tool_result errors that help Claude self-correct on the next iteration
• Use is_error flag in tool results to distinguish errors from successful outputs
• Implement exponential backoff for transient failures (rate limits, network errors)
• Set maximum iteration limits as safety nets — but not as primary control flow

Guardrail Approaches