---
title: Pattern Cookbook
sidebarTitle: Overview
---

Orchestration patterns are standardized approaches for organizing and coordinating AI agents to work together effectively on complex tasks. These patterns provide structured ways to design agent interactions, information flows, and responsibilities.

The pattern implementations use AG2's  group chat orchestration, read more about it [here](/docs/user-guide/advanced-concepts/orchestration/group-chat/introduction).

Each pattern includes:

- Description of the structure and information flow
- Visualization example of agent interactions
- Code example showing how to implement the pattern with AG2's swarm orchestration
- Code example output

## Patterns

### [Context-Aware Routing](/docs/user-guide/advanced-concepts/pattern-cookbook/context_aware_routing)

A dynamic workflow where tasks are intelligently distributed to specialized agents based on content analysis rather than predetermined paths.

![Content Aware chat](./assets/context_aware_routing.png)

**Business Use Cases:**

- Customer support systems that route queries to appropriate department specialists
- Multi-domain virtual assistants that connect users with specialized services
- Knowledge management systems that direct questions to domain experts
- Research platforms that route complex questions to knowledgeable AI agents
- Dynamic content moderation based on content type

### [Escalation](/docs/user-guide/advanced-concepts/pattern-cookbook/escalation)

A resource-efficient approach where simpler, less resource-intensive agents handle tasks first, with more capable (but potentially more expensive) agents only engaged when necessary.

![Escalation chat](./assets/escalation_pattern.png)

**Business Use Cases:**

- Tiered customer support (chatbot → human agent → specialist)
- Computational tasks with varying complexity requirements
- Content moderation (automated → human review)
- Technical problem-solving with varying difficulty levels
- Healthcare triage and diagnosis systems

### [Feedback Loop](/docs/user-guide/advanced-concepts/pattern-cookbook/feedback_loop)

A workflow where content progresses through repeated cycles of evaluation and improvement, enabling continuous refinement through deliberate iterations.

![Feedback loop chat](./assets/feedback_loop_pattern.png)

**Business Use Cases:**

- Document writing and editing processes
- Iterative design and creative tasks
- Learning systems that improve over time
- Continuous improvement workflows
- Complex problem-solving requiring multiple refinement cycles
- Quality assurance processes with iterative improvement

### [Hierarchical / Tree](/docs/user-guide/advanced-concepts/pattern-cookbook/hierarchical)

A tree-structured organization where "manager" agents at higher levels delegate tasks to "specialist" agents at lower levels, then aggregate and refine their outputs.

![tree pattern chat](./assets/tree-hierarchical-pattern.png)

**Business Use Cases:**

- Complex research reports requiring both oversight and specialized deep dives
- Product development workflows coordinating multiple specialized teams
- Multi-faceted analysis that benefits from both generalists and specialists
- Organizational decision-making with multiple levels of approval
- Enterprise customer service with tiered support levels

### [Organic](/docs/user-guide/advanced-concepts/pattern-cookbook/organic)

A flexible pattern that relies on agent descriptions and conversation context to naturally determine the most appropriate specialist for each stage of a conversation, without requiring explicit routing rules.

![Organic chat](./assets/organic_pattern.png)

**Business Use Cases:**

- Collaborative creative projects where expertise needs shift organically throughout the process
- Educational assistants that adapt to changing student questions across different subjects
- Consultative services where problem diagnosis may require different specialists at unpredictable points
- Versatile virtual assistants that handle diverse user needs without rigid conversation flows

### [Pipeline / Sequential Processing](/docs/user-guide/advanced-concepts/pattern-cookbook/pipeline)

A pattern that organizes agents into a linear sequence where each agent performs their specific action before passing onto the next agent in the chain.

![Sequential chat](./assets/sequential_pattern.png)

**Business Use Cases:**

- E-commerce order processing workflows (validation → inventory → payment → fulfillment)
- Content creation pipelines (research → draft → edit → polish)
- Data processing workflows (collect → clean → analyze → visualize)
- Multi-stage reasoning tasks (define problem → identify approaches → execute → validate)
- Document processing (extraction → classification → analysis → archiving)

### [Redundant](/docs/user-guide/advanced-concepts/pattern-cookbook/redundant)

A pattern that employs multiple agents to attempt the same task using different approaches, with results compared to select the best outcome or combine strengths.

![redundant chat](./assets/redundant_pattern.png)

**Business Use Cases:**

- Critical systems where errors must be minimized
- Creative tasks benefiting from multiple distinct perspectives
- Complex problem solving with unclear optimal approaches
- Medical diagnosis requiring multiple expert opinions
- Security systems needing cross-validation of potential threats

### [Star / Hub-and-Spoke](/docs/user-guide/advanced-concepts/pattern-cookbook/star)

A pattern that centralizes coordination through a single agent while leveraging specialized expertise through satellite agents.

![Star and Hub chat](./assets/starpattern_example.png)

**Business Use Cases:**

- Customer support systems with specialized agents for different query types
- Research projects requiring diverse domain expertise
- City or travel guides that need to coordinate information from multiple domains
- Planning tasks requiring input from various specialized knowledge areas
- Product recommendation systems with multiple product specialists

### [Triage with Tasks](/docs/user-guide/advanced-concepts/pattern-cookbook/triage_with_tasks)

A pattern that breaks down complex requests into categorized, sequential tasks processed by specialized agents in a dependency-respecting workflow.

![Triage with task chat](./assets/triage_tasks_pattern.png)

**Business Use Cases:**

- Content creation pipelines requiring research before writing
- Product development processes with sequential phase requirements
- Complex customer service requests needing multi-stage resolution
- Academic or scientific workflows involving data gathering and analysis before conclusions
- Report generation requiring fact-finding before compilation and presentation
- Multi-phase project planning with dependent deliverables
- Technical support cases requiring diagnosis before solution implementation

This pattern is used within our [`DocAgent`](/docs/user-guide/reference-agents/docagent) ([code](https://github.com/ag2ai/ag2/blob/main/autogen/agents/experimental/document_agent/document_agent.py)).

## Error Handling

It is possible, and even expected, that some agents may fail to complete their response successfully and that may disrupt the workflow. This could be due an exception being raised in a tool call or function.

If you are able to catch those exceptions, you can transfer to an `error agent` in your group chat using either [`ReplyResult`](/docs/api-reference/autogen/agentchat/group/reply_result/ReplyResult) or setting a context variable (e.g. `my_agent.set_context("errored", True)`) and using an [`OnContextCondition`](/docs/api-reference/autogen/agentchat/group/on_context_condition/OnContextCondition/#autogen.agentchat.group.on_context_condition.OnContextCondition) to transfer to the error agent.

```python
from autogen.agentchat.group import AgentTarget, ContextExpression, OnContextCondition, ReplyResult

# Transfer to the error_agent if the context variable "errored" is set to True
my_agent.handoffs.add_context_condition(
    OnContextCondition(
        target=AgentTarget(error_agent),
        condition=ExpressionContextCondition(expression=ContextExpression("${errored}")),
    )
)

# Transfer to the error_agent when a tool fails
def my_tool_function(my_parameter: str, context_variables: ContextVariables) -> ReplyResult:
    try:
        ...
    except Exception as e:
        # Option 1: set context variable that will be handled in a handoff associated
        # with this agent (see above)
        context_variables["errored"] = True
        return ReplyResult(
            message=f"An exception was raised: {e}",
            context_variables=context_variables
        )

        # Option 2: include the target error_agent in the returned ReplyResult
        # to transfer directly without the need for a handoff
        return ReplyResult(
            target=AgentTarget(error_agent),
            message=f"An exception was raised: {e}",
            context_variables=context_variables
        )

# Error agent can return to the user (or some other agent) automatically when it transitions
error_agent.handoffs.set_after_work(RevertToUserTarget())
```

For a concrete example of error handling, see the [implementation of DocAgent](https://github.com/ag2ai/ag2/blob/main/autogen/agents/experimental/document_agent/document_agent.py).

## Getting Started

To implement these patterns in your own applications:

1. Review the pattern documentation to identify which pattern(s) best suit your use case
2. Examine the example code for implementation details
3. Use AG2's  Group Chat framework to implement the chosen pattern
4. Customize the agents and their capabilities for your specific needs

For more information on using the Group Chat framework itself, refer to the [Group Chat documentation](/docs/user-guide/advanced-concepts/orchestration/group-chat/introduction).
