Orchestrator mode uses a manager agent to dynamically decide which worker agents to involve and in what order, enabling adaptive, intelligent coordination.

What is Orchestrator Mode?

Unlike sequential workflows where the path is predetermined, orchestrator mode gives a manager agent the power to analyze goals, delegate tasks, and synthesize results—much like a human project manager.

                    ┌─→ [Agent A] ─┐
Input → [Manager] ──┼─→ [Agent B] ─┼──→ [Manager] → Output
                    └─→ [Agent C] ─┘

The manager:

Analyzes the incoming request
Decides which worker agent(s) to use
Delegates with specific instructions
Evaluates the results
Iterates or completes based on progress

When to Use Orchestrator Mode

Orchestrator mode excels when:

Scenario	Why Orchestrator Works
Unpredictable tasks	Best approach isn't known upfront
Complex problems	Multiple specialists might be needed
Adaptive workflows	Different inputs need different handling
Quality-focused	Manager can iterate until satisfied
Customer routing	Route to appropriate specialist dynamically

Good Use Cases

Customer support: Route to billing, technical, or sales based on inquiry
Research projects: Decide which sources to consult based on topic
Content strategy: Choose writers, editors, or designers as needed
Problem solving: Try different approaches until one works
Multi-domain tasks: Combine expertise from different specialists

When NOT to Use Orchestrator

Simple, predictable processes
When you need guaranteed execution order
Cost-sensitive applications (manager adds overhead)
When audit trails must show exact steps upfront

For these cases, consider Sequential Mode.

How Orchestrator Mode Works in AffinityBots

The Manager Agent

The manager is an AI agent with special responsibilities:

Understand the goal - Parse what the user wants to achieve
Know the team - Understand each worker's capabilities
Make decisions - Choose which worker to use and why
Provide instructions - Give workers clear, specific tasks
Evaluate results - Determine if more work is needed
Synthesize output - Combine results into a final response

The Delegation Loop

User Input
    ↓
[Manager analyzes goal]
    ↓
[Manager selects worker]
    ↓
[Worker executes task]
    ↓
[Manager evaluates result]
    ↓
 ┌──┴──┐
 │     │
Done?  No → [Select next worker]
 │
 ↓
[Manager synthesizes final output]
    ↓
Output

Key Concepts

Concept	Description
Manager Prompt	Instructions for how the manager should coordinate
Worker Descriptions	Help manager understand when to use each worker
Max Iterations	Limit on how many delegations can occur
One at a Time	Manager delegates to ONE worker per iteration

Using Orchestrator Mode in the Playground

The Playground lets you test orchestrator-style coordination before building a formal workflow.

Method 1: Single Agent Orchestrator

Create an agent that acts as its own orchestrator:

You are a versatile assistant with multiple capabilities:

**Research Mode**: When asked for information, thoroughly research
and cite sources.

**Writing Mode**: When asked to write, create polished content
with proper structure.

**Analysis Mode**: When given data, provide insights and
recommendations.

**Creative Mode**: When asked for ideas, brainstorm multiple
creative options.

Analyze each request and determine which mode(s) to use.
Explain your approach before executing.

Method 2: Manual Orchestration

Simulate orchestration manually:

Start with a "manager" agent
Ask it to analyze the task and recommend which specialist to use
Switch to that specialist agent
Get the result
Return to the manager to evaluate
Repeat or finish

This helps you understand the flow before automating it.

Testing Worker Agents

Before adding workers to an orchestrator workflow:

Test each worker individually
Verify they handle their specialty well
Note their strengths and limitations
Write clear descriptions for the manager

Building Orchestrator Workflows

Step 1: Create the Workflow

Navigate to Workflows
Click Create Workflow
Select Orchestrator as the workflow type
Name it descriptively (e.g., "Customer Support Router")

Step 2: Configure the Manager

Click on the Orchestrator Node to configure:

Manager Prompt

Tell the manager how to coordinate:

You are a customer support manager coordinating a team of specialists.

Your team:
- **Billing Agent**: Handles payment issues, refunds, subscription changes
- **Technical Agent**: Solves product bugs, feature questions, integrations
- **Sales Agent**: Handles upgrades, new features, pricing questions

For each customer inquiry:
1. Analyze what type of issue this is
2. Choose the most appropriate specialist
3. Provide them with clear context and instructions
4. Evaluate their response for completeness
5. If more help is needed, delegate to another specialist
6. Synthesize a final, helpful response for the customer

Always be helpful, professional, and thorough.

Manager Model

Choose a capable model for the manager:

Model	Best For
GPT-4	Complex reasoning, nuanced decisions
Claude	Detailed analysis, careful coordination
GPT-4o	Balance of speed and capability

Max Iterations

Set a limit on delegations:

3-5: Typical for most workflows
Higher: For complex, multi-step problems
Lower: For simple routing scenarios

Step 3: Add Worker Agents

For each worker:

Click Add Worker Agent
Select an existing agent
Write a clear description for the manager:

**Billing Agent**
Specializes in: Payment processing, refunds, subscription management,
invoice questions, payment method updates.

Use when: Customer mentions billing, payments, charges, refunds,
subscription, or pricing issues.

Strengths: Accurate billing information, policy knowledge,
refund processing.

Add task-specific instructions (optional):

When helping with billing issues:
- Always verify the customer's account first
- Explain any charges clearly
- Offer solutions, not just explanations
- Escalate fraud concerns immediately

Step 4: Test and Activate

Click Test with various inputs
Watch the manager's decisions
Verify workers are chosen appropriately
Adjust descriptions or prompts as needed
Toggle Active when ready

Example: Research Assistant Orchestrator

The Team

Manager Agent

Model: GPT-4
Purpose: Coordinate research tasks

Web Researcher

Purpose: Find current information online
Tools: Web search enabled

Data Analyst

Purpose: Analyze numbers and trends
Tools: Code execution

Writer

Purpose: Synthesize findings into reports
Tools: None (pure writing)

Manager Prompt

You are a research coordinator managing a team of specialists.

Your team:
- **Web Researcher**: Finds current information, news, and online sources
- **Data Analyst**: Analyzes numbers, creates charts, identifies trends
- **Writer**: Creates clear, well-structured reports and summaries

For research requests:
1. Break down what information is needed
2. Delegate to Web Researcher for facts and sources
3. If data analysis is needed, send to Data Analyst
4. Finally, have Writer synthesize everything into a report

Evaluate each result before proceeding. If information is incomplete,
request additional research. Aim for comprehensive, accurate reports.

How It Works

User: "Research the current state of AI in healthcare and create a summary report."

Manager thinks: "This needs web research for current information, possibly data analysis for statistics, and writing for the final report."

Delegation 1: → Web Researcher "Find recent developments in AI healthcare applications, focusing on 2024 news and research."

Result: Web Researcher returns findings about diagnostic AI, drug discovery, etc.

Manager evaluates: "Good overview, but needs specific statistics."

Delegation 2: → Data Analyst "Analyze the market size and growth statistics for AI in healthcare."

Result: Data Analyst provides market figures and trends.

Manager evaluates: "Now I have facts and data. Time for the report."

Delegation 3: → Writer "Create a comprehensive summary report combining the research findings and data analysis."

Result: Writer produces the final report.

Manager synthesizes: Combines everything into the final output for the user.

Best Practices

1. Write Clear Worker Descriptions

The manager chooses workers based on descriptions:

❌ Vague: "Handles customer stuff"
✅ Clear: "Billing specialist - handles payment issues, refunds,
subscription changes, invoice questions. Use when customer mentions
money, payments, or billing."

2. Give the Manager Good Judgment

Include decision criteria in the manager prompt:

When choosing a specialist:
- If the question is about money → Billing Agent
- If the question is technical → Technical Agent
- If unclear, start with Technical Agent as default
- If one specialist can't fully help, involve another

3. Set Appropriate Iteration Limits

Workflow Type	Suggested Limit
Simple routing	2-3
Multi-step tasks	4-6
Complex research	6-10

Too low: May not complete complex tasks Too high: Risk of runaway costs

4. Design Workers for Specialization

Each worker should excel at one thing:

❌ Bad: One agent that does "everything"
✅ Good: Separate agents for billing, technical, sales

Specialized workers give the manager clear choices.

5. Include Fallback Instructions

Tell the manager what to do when stuck:

If no specialist seems appropriate, or if you're unsure:
1. Ask clarifying questions
2. Try the most likely specialist
3. If still stuck, provide a helpful general response

Troubleshooting

Manager always picks the same worker

Review worker descriptions—make distinctions clearer
Add explicit criteria to manager prompt
Test with varied inputs to check routing

Workflow runs too long

Lower max iterations
Add completion criteria to manager prompt
Make workers more focused/efficient

Poor quality final output

Improve manager's synthesis instructions
Add "evaluate before completing" to manager prompt
Consider adding a final review worker

Workers not receiving enough context

Check context settings in workflow
Add explicit instructions for manager to provide context
Include relevant history in delegation prompts

Orchestrator vs Sequential: Quick Comparison

Aspect	Sequential	Orchestrator
Flow	Predetermined	Dynamic
Control	Task order fixed	Manager decides
Flexibility	Low	High
Predictability	High	Lower
Cost	Lower (no manager)	Higher (manager overhead)
Best for	Pipelines	Routing & complex tasks

Related Guides

Sequential Mode - Linear agent pipelines
Creating a Workflow - Step-by-step workflow guide
Introduction to Workflows - Workflow fundamentals
Adding Guardrails - Validate agent outputs