Architecture Overview
Why Architecture Matters
The Problem: A single agent approach works for simple tasks, but complex workflows require coordinating multiple capabilities, routing decisions, and error recovery.
The Solution: Agent architectures provide proven patterns for organizing agent systems -- from simple single-agent setups to sophisticated multi-agent orchestrations.
Real Impact: Choosing the right architecture can mean the difference between an agent that handles 80% of cases and one that handles 99%.
Real-World Analogy
Think of agent architectures like company structures:
- Single Agent = A solo freelancer who does everything
- Router = A receptionist who directs you to the right department
- Multi-Agent = A team of specialists collaborating on a project
- Hierarchical = A company with managers overseeing specialist teams
Comparing Architectures
Single Agent
One LLM handles everything -- perception, reasoning, tool use, and response. Simple to build but limited in complexity.
Router Architecture
A classifier agent routes requests to specialized sub-agents. Great for diverse task types with clear boundaries.
Parallel Multi-Agent
Multiple agents work simultaneously on different aspects of a task. Results are combined by an aggregator.
Orchestrator-Worker
A central orchestrator breaks tasks into subtasks and delegates to worker agents, then synthesizes results.
Single Agent Architecture
Router Architecture
class RouterAgent:
def __init__(self):
self.agents = {
"code": CodeAgent(),
"research": ResearchAgent(),
"data": DataAnalysisAgent(),
}
def route(self, query):
# Use LLM to classify the intent
intent = self.classify(query)
agent = self.agents[intent]
return agent.run(query)
def classify(self, query):
response = llm.chat(messages=[{
"role": "system",
"content": "Classify: code, research, or data"
}, {"role": "user", "content": query}])
return response.strip().lower()Multi-Agent Systems
When to Use Multi-Agent
- Parallel processing: Different aspects of a task can be handled simultaneously
- Specialization: Each agent has deep expertise in one domain
- Debate/verification: Agents can check each other's work
- Complex workflows: Tasks that naturally decompose into independent subtasks
Hierarchical Agents
| Architecture | Complexity | Best For | Tradeoff |
|---|---|---|---|
| Single | Low | Simple tasks, prototyping | Limited capability |
| Router | Medium | Diverse task types | Classification errors |
| Parallel | Medium | Independent subtasks | Coordination overhead |
| Orchestrator | High | Complex multi-step workflows | Higher latency and cost |
| Hierarchical | Very High | Enterprise-scale systems | Significant engineering |
Quick Reference
| Pattern | Description | Example Use Case |
|---|---|---|
| Single Agent | One LLM + tools handles all tasks | Personal coding assistant |
| Router | Classifier routes to specialists | Customer support with departments |
| Fan-out/Fan-in | Parallel agents, results aggregated | Multi-source research |
| Orchestrator-Worker | Manager delegates to workers | Complex data pipeline builder |
| Evaluator-Optimizer | One generates, another evaluates | Code review and improvement |