Agentic Architecture & Orchestration — Complete Lesson

The Core Concept

An agentic loop sends a message to Claude, receives a response, checks the stop_reason field, executes any requested tools, appends the results to the conversation history, and repeats. The loop continues until Claude signals it is finished by returning stop_reason == "end_turn".

The critical insight: Claude decides when it is done, not the developer's iteration counter or text-parsing logic. The stop_reason field is the only reliable signal. Everything else is a workaround that will fail in production.

Loop Lifecycle

Correct Implementation

def run_agent(client, tools, initial_message):
    messages = [{"role": "user", "content": initial_message}]

    while True:
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            tools=tools,
            messages=messages
        )

        # ✓ ONLY correct termination signal
        if response.stop_reason == "end_turn":
            break

        # ✓ Continue loop on tool_use
        if response.stop_reason == "tool_use":
            # Append assistant response to history
            messages.append({
                "role": "assistant",
                "content": response.content
            })

            # Execute each tool call and collect results
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })

            # ✓ Append tool results for next iteration
            messages.append({
                "role": "user",
                "content": tool_results
            })

    return response

Anti-Patterns the Exam Tests

Exam Traps for Task 1.1

🔨 Implementation Task

Exam Simulation — Task 1.1

The Core Concept

In a hub-and-spoke architecture, a coordinator agent receives the original request, decomposes it into subtasks, delegates each to a specialized subagent, collects results, and synthesizes the final response. No subagent communicates directly with another — all routing passes through the coordinator.

Hub-and-Spoke Architecture

Coordinator Design Principles

The most common coordinator failure is overly narrow task decomposition — breaking "impact of AI on creative industries" into only visual arts subtasks, because that's what the coordinator knows best. The result: every subagent completes successfully, but the final output has systematic blind spots.

• Design coordinator prompts specifying research goals and quality criteria — not step-by-step procedural instructions, to preserve subagent adaptability
• Partition scope across subagents to minimize duplication (distinct subtopics or source types per agent)
• Implement iterative refinement: evaluate synthesis output → identify gaps → re-delegate with targeted queries → re-synthesize
• Route all inter-subagent information through the coordinator — never allow direct subagent-to-subagent communication

Exam Traps for Task 1.2

🔨 Implementation Task

Exam Simulation — Task 1.2

The Core Concept

Subagents are not automatically created — they are spawned using the Task tool. The coordinator must have "Task" in its allowedTools list, and each subagent is defined via AgentDefinition with its own system prompt, description, and tool restrictions.

The Task Tool

Context Passing Pattern

When passing context between agents, use structured data formats that separate content from metadata. Raw text blobs lose attribution — source URLs, document names, and page numbers disappear during synthesis.

# ✓ Pass structured context explicitly — not raw text
synthesis_prompt = f"""
You are a synthesis agent. Combine the following research findings
into a comprehensive report on: {research_topic}

Web Search Results:
{json.dumps(web_results, indent=2)}

Document Analysis:
{json.dumps(doc_analysis, indent=2)}

Each result includes: source_url, excerpt, relevance_score, date.
Preserve source attribution in your synthesis.

Quality criteria: Cover all major categories. Flag any gaps.
"""

# ✗ DO NOT pass context like this:
synthesis_prompt = f"Synthesize this: {str(all_results)}"
# ↑ Loses structure, attribution, and metadata

Parallel Spawning

To run subagents in parallel, emit multiple Task tool calls in a single coordinator response. Spawning them across separate turns forces sequential execution and negates the latency benefit.

• Include complete findings from prior agents directly in the subagent's prompt — never assume it can access them from history
• Use structured data formats (JSON with source URLs, document names, page numbers) to preserve attribution when passing context
• Spawn parallel subagents by emitting multiple Task calls in a single coordinator response — not across separate turns
• Design coordinator prompts with goals and quality criteria — not step-by-step instructions — to preserve subagent adaptability

Exam Traps for Task 1.3

🔨 Implementation Task

Exam Simulation — Task 1.3

The Core Concept

Prompt-based guidance tells Claude what it should do. Programmatic enforcement tells the system what it can do. For critical business logic — identity verification before financial operations, compliance checks before data access — only programmatic gates provide the deterministic guarantees that production requires.

Programmatic Prerequisite Gates

A prerequisite gate intercepts a tool call and checks whether required prior steps have been completed. If not, it blocks the call and returns a structured error explaining what must happen first.

def execute_tool(tool_name, tool_input, session_state):
    # ✓ Programmatic gate — runs before every tool execution
    if tool_name in ["process_refund", "lookup_order"]:
        if not session_state.get("verified_customer_id"):
            return {
                "error": "Prerequisite not met",
                "required": "get_customer must be called first",
                "reason": "Identity verification required before order operations"
            }

    if tool_name == "get_customer":
        result = get_customer_impl(tool_input)
        # ✓ Gate is cleared once prerequisite completes
        session_state["verified_customer_id"] = result["customer_id"]
        return result

    # ✗ Prompt-only approach (12% failure rate):
    # "Always call get_customer before any order operations"

Structured Handoff Protocols

When an agent must escalate to a human, the handoff package must be complete — the human agent receiving it has no access to the conversation history. Every decision, finding, and recommendation must be compiled into a self-contained summary.

• Decompose multi-concern requests into distinct items, investigate each in parallel using shared context, then synthesize a unified resolution before handoff
• Compile structured handoff summaries with: customer ID, issue root cause, refund amount or action taken, recommended next action
• Include what was attempted and what was not — the human agent needs to know where to pick up
• Never escalate with "I couldn't help" — always include the investigation results that led to escalation

Exam Traps for Task 1.4

🔨 Implementation Task

Exam Simulation — Task 1.4

The Core Concept

Hooks intercept the tool call lifecycle at two points: before a tool is called (tool call interception) and after it returns (PostToolUse). This gives you a centralized place to enforce compliance rules and normalize data formats before Claude reasons about tool results.

Hook Patterns

Hook Implementations

def post_tool_use_hook(tool_name, tool_result):
    """Normalize heterogeneous data before model processes it."""

    if "created_at" in tool_result:
        ts = tool_result["created_at"]

        # Unix timestamp → ISO 8601
        if isinstance(ts, (int, float)):
            tool_result["created_at"] = datetime.utcfromtimestamp(ts).isoformat()

    # Numeric status codes → human-readable
    status_map = {1: "active", 2: "pending", 3: "cancelled"}
    if "status" in tool_result and isinstance(tool_result["status"], int):
        tool_result["status"] = status_map.get(tool_result["status"], "unknown")

    return tool_result

def pre_call_hook(tool_name, tool_input, session_state):
    """Block policy-violating actions before execution."""

    if tool_name == "process_refund":
        amount = tool_input.get("amount", 0)

        if amount > 500:
            # Block and redirect to escalation workflow
            return {
                "blocked": True,
                "reason": "Refund exceeds $500 policy maximum",
                "action": "escalate_to_manager",
                "amount_requested": amount
            }

    return None  # None = allow the call to proceed

Exam Traps for Task 1.5

🔨 Implementation Task

Exam Simulation — Task 1.5

The Core Concept

Task decomposition is the act of breaking a complex goal into a sequence of smaller, executable steps. The right pattern depends on how much is known about the task upfront: prompt chaining for predictable workflows where the steps are known in advance, dynamic decomposition for open-ended investigations where each step reveals what to do next.

Decomposition Patterns

Exam Traps for Task 1.6

🔨 Implementation Task

Exam Simulation — Task 1.6

The Core Concept

Sessions preserve conversation history and tool results across work sessions. But session resumption is not always the right choice — when the files being analyzed have changed since the last session, the cached tool results are stale and the model will reason incorrectly from them.

Session Resumption

Session Forking

fork_session creates an independent branch from the current session's state. Both branches share the same history up to the fork point, then diverge independently. Neither branch's changes affect the other.

• Use --resume <session-name> for named session continuation when prior context is mostly valid
• Use fork_session to compare two approaches (e.g., testing strategies, refactoring patterns) from a shared analysis baseline
• Choose summary injection over resumption when prior tool results are stale — inject a structured summary of findings as the first message
• When resuming after changes, explicitly tell the agent which specific files changed — enable targeted re-analysis rather than full re-exploration

Exam Traps for Task 1.7

🔨 Implementation Task

Exam Simulation — Task 1.7