Last Updated: October 30, 2025 This is a living document and patterns may evolve as AG2 develops.
A comprehensive collection of agent orchestration patterns using AG2 (AutoGen 2). This cookbook demonstrates various ways to design and coordinate multi-agent systems, from simple two-agent conversations to complex hierarchical structures.
This cookbook provides ready-to-run examples of common agent interaction patterns. Each pattern demonstrates a specific approach to organizing agent communication and task coordination.
Just as human organizations have evolved different structures to solve various types of problems, multi-agent systems can be designed using patterns that mirror successful human workforce models. These patterns aren’t arbitrary - they reflect decades of organizational design wisdom applied to autonomous AI agents.
Why This Matters: Understanding the human analogy helps you:
Each pattern in this cookbook corresponds to a real-world organizational structure, from one-on-one mentoring to complex corporate hierarchies.
uv sync
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
python pattern_basic_1_two_agent_chat.py
These patterns cover fundamental agent interaction models, each mirroring common human collaboration structures:
pattern_basic_1_two_agent_chat.py)Pattern: Direct one-on-one interaction between two agents.
Human Workforce Analogy:
When to Use:
Real-World Example: A junior developer asking a senior architect about system design decisions.
pattern_basic_2_sequential_chat.py)Pattern: Agents process work in a fixed, predetermined sequence.
Human Workforce Analogy:
When to Use:
Real-World Example: A content creation workflow where a researcher gathers information, a writer creates the draft, an editor refines it, and a publisher distributes it.
pattern_basic_3_nested_chat.py)Pattern: A coordinator agent delegates work to specialized sub-teams who have their own internal conversations.
Human Workforce Analogy:
When to Use:
Real-World Example: A project manager assigns the backend work to a dev team (who discuss architecture among themselves), frontend to another team (who coordinate on UI/UX), and QA to a testing team.
pattern_basic_4_group_chat.py)Pattern: Multiple agents collaborate in a shared discussion space.
Human Workforce Analogy:
When to Use:
Real-World Example: A product launch meeting with marketing, engineering, sales, and customer success all contributing their perspectives on go-to-market strategy.
These patterns mirror sophisticated organizational structures found in modern workforces:
pattern_advanced_context_aware_routing.py)Pattern: Dynamic routing where the next agent is selected based on current context and conditions.
Human Workforce Analogy: Smart help desk routing, hospital patient routing to specialists, legal case assignment, dynamic project staffing
Real-World Example: A customer inquiry system that routes technical questions to engineering, billing questions to finance, and feature requests to product based on inquiry content.
Complexity: Medium-High
pattern_advanced_escalation.py)Pattern: Progressive escalation through tiers of increasing expertise or authority.
Human Workforce Analogy: IT support tiers (L1 → L2 → L3), customer complaints (CSR → Supervisor → Manager), medical diagnosis (Nurse → GP → Specialist)
Real-World Example: Technical support where basic questions are handled by automated responses, moderate issues go to support agents, and critical problems escalate to senior engineers.
Complexity: Medium
pattern_advanced_feedback_loop.py)Pattern: Iterative cycles of work and review until quality standards are met.
Human Workforce Analogy: Code review cycles, academic paper review, design iteration with critique, PR review process
Real-World Example: Content creation where a writer produces content, an editor provides feedback, the writer revises, and the cycle continues until approval.
Complexity: Medium-High
pattern_advanced_hierarchical.py)Pattern: Multi-level organizational structure with executives, managers, and specialists.
Human Workforce Analogy: Corporate structure (C-Suite → VPs → Directors → Managers → ICs), military command chain, academic administration, construction projects
Real-World Example: A research project where an executive sets objectives, managers define workstreams, team leads coordinate specialists, and researchers execute tasks - with results flowing back up the chain.
Complexity: High
pattern_advanced_organic.py)Pattern: Agents are dynamically selected based on their expertise descriptions (auto-routing).
Human Workforce Analogy: Consulting firms matching consultants to clients, gig economy platforms (Upwork, Fiverr), hospital on-call specialists, open-source collaboration
Real-World Example: A software project where the system automatically brings in the security expert for security questions, database specialist for data modeling, and frontend developer for UI decisions based on conversation context.
Complexity: Medium
pattern_advanced_pipeline.py)Pattern: Sequential processing through specialized stages with quality gates.
Human Workforce Analogy: Software CI/CD pipeline, manufacturing with QC checkpoints, pharmaceutical drug development, publishing workflow
Real-World Example: Data processing pipeline where analysts clean data, engineers transform it, data scientists build models, and ML engineers deploy - with validation checks between stages.
Complexity: Medium
pattern_advanced_redundant.py)Pattern: Multiple agents independently work on the same task for validation or consensus.
Human Workforce Analogy: Jury deliberation, academic peer review, medical second opinions, audit processes, competitive bidding
Real-World Example: Hiring decisions where multiple interviewers independently assess a candidate and compare notes to reach consensus, reducing individual bias.
Complexity: Medium
pattern_advanced_star.py)Pattern: Central coordinator distributes work to specialized agents (hub-and-spoke).
Human Workforce Analogy: Dispatch center (911), project manager coordinating parallel workstreams, talent agent managing clients, administrative assistant coordinating meetings
Real-World Example: A project coordinator receiving a complex request, breaking it into parallel tasks (design, development, documentation), assigning to specialists, and consolidating results.
Complexity: Medium
pattern_advanced_triage_with_tasks.py)Pattern: Incoming requests are classified, prioritized, and routed to appropriate handlers.
Human Workforce Analogy: Emergency room triage, IT ticketing systems, airport security screening, customer service routing, legal intake
Real-World Example: Customer support system that analyzes tickets, categorizes by type (bug, feature, question), assigns priority (critical/high/medium/low), and routes to appropriate teams.
Complexity: Medium-High
Choose a pattern based on your requirements:
| Pattern | Best For | Complexity | Control Level | Human Analogy |
|---|---|---|---|---|
| Two Agent Chat | Simple Q&A | Low | Direct | Mentoring |
| Sequential Chat | Fixed workflows | Low | High | Assembly line |
| Nested Chat | Modular tasks | Medium | High | Project teams |
| Group Chat | Collaboration | Medium | Low | Team meeting |
| Context-Aware Routing | Adaptive workflows | Medium-High | Medium | Smart routing |
| Escalation | Tiered support | Medium | Medium | L1/L2/L3 support |
| Feedback Loop | Quality control | Medium-High | Medium | Review cycles |
| Hierarchical | Large organizations | High | High | Corporate structure |
| Organic | Dynamic teams | Medium | Low | Consulting pool |
| Pipeline | Processing stages | Medium | High | Manufacturing |
| Redundant | Critical validation | Medium | Medium | Jury/peer review |
| Star | Centralized control | Medium | High | Dispatch center |
| Triage | Request routing | Medium-High | Medium | ER triage |
When translating human workforce structures to agent systems, consider:
| Human Org Structure | Agent Pattern | Key Difference |
|---|---|---|
| 1:1 Meeting | Two Agent Chat | Agents never tire of conversation |
| Assembly Line | Sequential Chat, Pipeline | No shift changes, perfect handoffs |
| Project Team | Nested Chat | Sub-teams work at machine speed |
| Standup Meeting | Group Chat | All participants fully present |
| Skill Marketplace | Organic | Instant matching, no negotiation |
| Support Tiers | Escalation | Instant escalation when criteria met |
| Peer Review | Feedback Loop | Faster iteration cycles |
| Corporation | Hierarchical | No office politics, clear delegation |
| Audit Team | Redundant | Perfect independence, no groupthink |
| Operations Center | Star | No context loss in coordination |
| Intake Process | Triage | Consistent classification |
Mistake 1: Over-orchestration
Mistake 2: Under-specified roles
Mistake 3: Ignoring human involvement
Mistake 4: Missing quality gates
Mistake 5: Human-centric assumptions
All patterns use AG2’s LLMConfig for model configuration:
from autogen import LLMConfig
llm_config = LLMConfig(config_list={
"api_type": "openai",
"model": "gpt-5-nano",
"api_key": os.getenv("OPENAI_API_KEY")
})
Advanced patterns use:
from autogen.agentchat import initiate_group_chat
result, final_context, last_agent = initiate_group_chat(
pattern=agent_pattern,
messages="Your initial message",
max_rounds=20
)
new_agent = ConversableAgent(
name="agent_name",
system_message="Role description",
description="When to use this agent",
llm_config=llm_config
)
def custom_function(param: str, context_variables: ContextVariables) -> ReplyResult:
context_variables["key"] = param
return ReplyResult(
response="Function completed",
context_variables=context_variables,
handoff="next_agent_name"
)
from autogen.agentchat.group import OnCondition, StringLLMCondition
transitions = [
OnCondition(
target=AgentNameTarget("target_agent"),
available_condition=ExpressionAvailableCondition(
condition=ContextExpression('task_completed == True')
)
)
]
pattern cookbook/
├── .env # Environment configuration
├── .env.example # Example environment file
├── pyproject.toml # Project dependencies
├── uv.lock # Locked dependencies
├── pattern_basic_1_two_agent_chat.py
├── pattern_basic_2_sequential_chat.py
├── pattern_basic_3_nested_chat.py
├── pattern_basic_4_group_chat.py
├── pattern_advanced_context_aware_routing.py
├── pattern_advanced_escalation.py
├── pattern_advanced_feedback_loop.py
├── pattern_advanced_hierarchical.py
├── pattern_advanced_organic.py
├── pattern_advanced_pipeline.py
├── pattern_advanced_redundant.py
├── pattern_advanced_star.py
└── pattern_advanced_triage_with_tasks.py
Think of agent patterns as:
Ask yourself:
Then translate those answers directly into agent patterns.
Multi-agent systems can seem abstract and overwhelming. By grounding them in familiar human organizational patterns, you gain:
1. Intuitive Design: You already know how to organize teams - just apply that knowledge to agents.
2. Communication: Explaining “we’re using a hierarchical pattern with escalation” is clearer than describing the technical implementation.
3. Pattern Recognition: When you see a new problem, ask “how would humans solve this?” and you’ll know which pattern to use.
4. Debugging: If your agent system isn’t working, think about what would fail in the human equivalent. Missing handoff? Unclear authority? No quality control?
5. Scaling: Organizational design principles (span of control, delegation, specialization) apply directly to agent systems.
As AI agents become more capable, the patterns that worked for human organizations will increasingly apply to hybrid human-agent teams. Understanding these patterns now prepares you for:
The skills you develop designing agent systems - clear role definition, explicit decision criteria, well-defined handoffs - are the same skills that make human teams excel.
This is a tutorial collection for learning AG2 patterns. Feel free to:
Part of the build-with-ag2 tutorial collection.