Mastering Hub and Spoke Agent Architecture with Claude

Overview

This course explores the "Hub and Spoke" architecture for AI agents, a high-value design pattern that separates the coordination of complex tasks from their execution. By implementing a central coordinator agent to manage sub-agents, developers can build scalable, observable, and highly reliable AI systems. Mastering this specific architecture is identified as a critical skill gap that separates mid-level engineers from high-earning specialists in the current AI economy.

Background & Context

In the rapidly evolving landscape of AI engineering, there is a significant "skill gap" between engineers earning $95K and those earning $300K. The differentiator is often the ability to move beyond simple, single-prompt interactions and into sophisticated agentic architectures. The Hub and Spoke model solves the problem of "agent chaos," where multiple agents talking to each other in an unstructured way lead to hallucinations, loss of context, and difficulty in debugging.

This architecture is championed as a professional standard for building production-ready agents, similar to the underlying logic suspected to be used in advanced tools like Claude Code. By creating a centralized "choke point" for information, developers can implement better error handling and observability, ensuring that the AI system remains controllable as it grows in complexity.

Core Concepts

The Coordinator Agent (The Hub)

The Coordinator Agent is the central intelligence of the system. Its primary role is not to perform the actual work, but to manage the workflow. The coordinator acts as the "brain" that receives the user's request, determines what needs to be done, and delegates those tasks to the appropriate specialized agents. It is explicitly instructed: "do not do the work yourself."

The coordinator is responsible for three primary functions:

1. Task Decomposition: Breaking a complex user request into smaller, manageable sub-tasks.
2. Routing: Deciding which sub-agent is best suited for a specific sub-task based on the complexity and nature of the query.
3. Aggregation: Collecting the outputs from various sub-agents and synthesizing them into a single, coherent, and polished final response.

Sub-Agents (The Spokes)

Sub-agents are specialized workers designed to perform one specific task with high precision. In a true Hub and Spoke model, sub-agents are "blind" to one another; they have no direct lines of communication. A research agent, for example, cannot talk to a review agent; it must send its findings back to the coordinator, which then decides if and how that information should be passed to the review agent.

This isolation prevents "context pollution," where an agent becomes confused by irrelevant information from other agents. Each spoke focuses solely on its specific prompt and toolset, ensuring higher quality outputs and easier debugging.

Routing Logic

Routing is the decision-making process the coordinator uses to assign work. Rather than using static routing (where Task A always goes to Agent B), the coordinator uses dynamic routing based on the use case:

• Simple Factual Questions: The coordinator may route to a single agent for a quick answer.
• Multi-step Tasks: The coordinator delegates tasks sequentially, passing the results of one agent forward to the next.
• Independent Sub-tasks: The coordinator delegates tasks in parallel to multiple agents to increase efficiency.

Observability and Choke Points

Because every piece of information must pass through the coordinator, the architecture creates a natural "choke point." This is a strategic advantage for developers because it provides a single location to monitor all inputs and outputs. This makes it significantly easier to implement logging, error handling, and quality checks, as the developer only needs to observe the hub to understand the state of the entire system.

How It Works / Step-by-Step

Step 1: Defining the Coordinator's Role

The first step in implementation is establishing the system prompt for the coordinator. The prompt must clearly define the agent as a manager. It should be told to use its judgment to assess complexity and specifically forbidden from attempting to solve the user's problem directly.

Step 2: Task Decomposition and Routing

Once a request is received, the coordinator performs the following logic:

1. Analyze the Request: The coordinator identifies the core goal.
2. Decompose: It breaks the goal into a list of required sub-tasks.
3. Assess Complexity: It determines if the task is simple, sequential, or parallel.
4. Delegate: It invokes the specific tools or sub-agents required for each sub-task.

Step 3: Execution by Spokes

The sub-agents receive a specific instruction and the necessary context from the coordinator. They execute their task—such as scanning a document or searching a database—and return the result to the hub. The sub-agents do not know the overall goal of the project; they only know the specific task they were assigned.

Step 4: Result Aggregation

After the spokes return their results, the coordinator enters the aggregation phase. It must:

1. Combine Outputs: Merge multiple data points into one response.
2. Resolve Conflicts: If two sub-agents provide conflicting information, the coordinator uses its reasoning capabilities to resolve the discrepancy.
3. Format the Data: The coordinator "makes the data pretty," ensuring the final output is professional and coherent for the end user.

Real-World Examples & Use Cases

Case Study: Job Application Screener

The source provides a detailed example of how a Job Application Screener would function using this architecture:

• The Hub (Coordinator): Receives a job posting and a resume. It decomposes the request into specific screening criteria.
• Spoke 1 (Keyword Scanner): A specialized agent prompted to check if required skills appear explicitly in the resume. It is told to be literal and not to infer or extrapolate.
• Spoke 2 (Deep Evaluation): An agent that analyzes the quality of experience.
• Spoke 3 (Red Flag Detector): An agent specifically looking for gaps in employment or contradictory information.
• The Hub (Aggregation): The coordinator takes the "Pass/Fail" from the scanner, the "Score" from the evaluation, and the "Warnings" from the red flag detector to produce a final hiring recommendation.

Additional Application Scenarios

1. Technical Due Diligence: A coordinator decomposes a software review into five fixed areas (e.g., Security, Scalability, Maintainability, etc.). Different agents analyze each area, and the coordinator aggregates the findings into a comprehensive technical report.
2. Travel Planning: A coordinator delegates to a "Flight Agent," a "Hotel Agent," and a "Local Attractions Agent." The coordinator ensures the hotel is near the attractions and the flights align with the check-in dates before presenting a final itinerary.

Key Insights & Takeaways

• The "Skill Gap" is Architectural: The difference between a $95K and $300K engineer is the ability to implement complex patterns like Hub and Spoke rather than simple prompts.
• Strict Separation of Concerns: Sub-agents must never communicate directly; all communication must flow through the coordinator to maintain control.
• Coordinator as Manager, Not Worker: The coordinator's value is in decomposition, routing, and aggregation, not in performing the tasks itself.
• Dynamic Routing is Essential: Effective systems use judgment to decide between sequential and parallel execution based on the complexity of the query.
• Observability is a Primary Benefit: The hub acts as a central point for monitoring, making the system easier to debug and refine.
• Literalism in Spokes: Sub-agents (like the Keyword Scanner) should be prompted to be literal and avoid extrapolation to prevent hallucinations.

Common Pitfalls / What to Watch Out For

• The "Generic" Trap: Avoid creating coordinators that are too generic (e.g., "manage tasks"). If the coordinator's role is too vague, the agent will struggle to decompose tasks effectively. Use concrete use cases (like the Job Screener) to guide the agent's logic.
• Over-reliance on Lower-Tier Models: The source demonstrates that while faster models (like Claude Haiku) can generate basic code, they may miss the sophistication required for complex routing and decomposition. High-reasoning models (like Claude Sonnet or Opus) are typically needed for the coordinator role.
• Allowing Spokes to "Over-reach": Ensure sub-agents are strictly limited to their specific role. If a sub-agent starts trying to coordinate other tasks, the architecture collapses back into a chaotic, unstructured system.

Review Questions

1. Why is it critical that sub-agents in a Hub and Spoke architecture cannot communicate directly with each other?
2. Describe the three primary responsibilities of the Coordinator Agent. How does each contribute to the final output?
3. If you were building a "Restaurant Order Customizer," how would you divide the responsibilities between the Hub and the Spokes? Which tasks would the coordinator handle, and which would be delegated?

Further Learning

• Advanced Prompt Engineering: Learn how to write "system prompts" that enforce the "do not do the work yourself" rule for coordinators.
• Parallel vs. Sequential Execution: Study the trade-offs between parallel processing (speed) and sequential processing (dependency management) in AI workflows.
• State Management: Explore how to maintain "state" or "memory" within the coordinator so it can track which sub-tasks are complete and which are pending.