Agent Orchestration & Workflow

🎼 The Symphony of Intelligent Coordination

AgentRouter's orchestration system coordinates multiple agents to work together seamlessly - each agent plays its part, contributing to a unified solution. This document explains how agents coordinate, communicate, and collaborate to solve complex tasks.

🔄 Core Orchestration Flow

The orchestration lifecycle follows a structured pattern:

Task Initiated → Planning Phase
Planning Phase → Analyze Task → Create Strategy → Decision Point
Execution Phase → Tool Execution or Agent Delegation → Process Results
Iteration Control → Check Completion → Continue Loop or Prepare Final Response
Task Complete ✨

📋 Planning Agent - The Brain

The Planning Agent is the intelligent decision-maker that orchestrates the entire workflow:

Decision Making Process

The Planning Agent follows a state machine pattern:

Analyzing (agent_status: running): Receive and understand task
Planning: Generate strategy
Evaluating: Determine if tool, agent, or direct response needed
Executing: Call tool or delegate to agent
Processing: Get and process results
Finalizing (agent_status: preparing_final_response): Generate final response

Planning Response Structure

{
    "agent_status": "running",           # or "preparing_final_response"
    "plan": "Step-by-step strategy",     # Detailed execution plan
    "reasoning": "Why this approach",     # Decision rationale
    "final_decision": "Summary",         # Completion reasoning
    "tool_choice": {                      # Next action to take
        "type": "function",
        "name": "tool_or_agent_name"
    }
}

Agent Communication Protocol

Message Flow Between Agents

The workflow shows how messages flow:

User → Manager Agent: Initial task submission
Manager Agent → Planning Agent: Request strategy
Planning Agent → Tool Call Agent: Get tool parameters
Tool Call Agent → Tool/Agent: Execute actions
Results → Planning Agent: Process results
Loop continues until task is complete

🔧 Tool vs Agent Decision Logic

The Planning Agent makes intelligent decisions about when to use tools versus when to delegate to specialized agents:

Decision Matrix

Scenario	Choice	Reasoning
Calculate 2+2	Tool	Simple operation, direct execution
Analyze customer sentiment	Agent	Requires specialized processing
Parse JSON data	Tool	Data transformation
Create marketing strategy	Agent	Complex, multi-faceted task
Validate input	Tool	Quick validation
Process refund request	Agent	Business logic + multiple steps

🔄 Iteration Control & Max Iterations

The system includes built-in iteration control to prevent infinite loops:

Flow Control

Start: iteration = 0
Check: iteration < max_iterations
Execute: Plan → Execute → Increment
Exit Conditions:
- ✅ Task Complete (agent_status: preparing_final_response)
- ⚠️ Max Iterations Reached (forces final response)
- ❌ Error Occurred (raises exception)

Configurable Iteration Limits

manager = ManagerAgent(
    name="orchestrator",
    api_key="key",
    max_iterations=30  # Configurable: 3-50 (default: 30)
)

🔐 Message History Management

How Messages Flow Through the System

Original User Message starts the flow
Iteration 1: Plan Message → Tool Call Message → Tool Result
Iteration 2: Plan Message → Agent Call → Agent Result
Final Processing: Transform messages → Generate final response

Message Transformation for Final Response

Keep all original messages - User and assistant messages preserved
Keep tool/agent results - All execution results maintained
Remove intermediate plans - Clean up internal planning messages
Update system message - Add agent personality parameters

🚦 Agent Status States

The agent transitions through various states during execution:

class AgentStatus(Enum):
    IDLE = "idle"                    # Agent waiting for task
    RUNNING = "running"               # Task being processed
    PREPARING_FINAL_RESPONSE = "preparing_final_response"  # Ready to respond
    COMPLETED = "completed"           # Task finished
    FAILED = "failed"                # Error occurred

🎯 Real-World Orchestration Example

E-Commerce Order Processing

A practical orchestration example:

# Create specialized agents
order_manager = ManagerAgent(
    name="order_manager",
    api_key="key",
    goal="Process customer orders"
)

inventory_checker = WorkerAgent(
    name="inventory_checker",
    role="Validates stock levels, reserves inventory, and tracks product availability across warehouses",  # REQUIRED: Concise role
    goal="Verify product availability"
)

payment_processor = WorkerAgent(
    name="payment_processor",
    role="Authorizes payments, validates cards, processes refunds, and manages transaction security",  # REQUIRED: Clear role
    goal="Handle payment transactions"
)

shipping_coordinator = WorkerAgent(
    name="shipping_coordinator",
    role="Calculates shipping rates, selects carriers, generates labels, and tracks delivery status",  # REQUIRED: Focused role
    goal="Arrange shipping and delivery"
)

# Build hierarchy
order_manager.attach_worker(inventory_checker)
order_manager.attach_worker(payment_processor)
order_manager.attach_worker(shipping_coordinator)

# Process order
result = await order_manager.run("Process order #12345")

💡 Orchestration Best Practices

1. Task Decomposition

# Good: Clear, focused tasks
result = await worker.run(
    task="Analyze Q3 sales data for electronics category",
    additional_context="Focus on top 10 products"
)

# Bad: Too broad
result = await worker.run("Do sales analysis")

2. Agent Specialization

# Create specialized agents for specific domains
data_analyst = WorkerAgent(
    name="data_analyst",
    role="Performs statistical analysis, identifies correlations, builds predictive models, and creates data visualizations",  # REQUIRED: Clear role
    goal="Analyze and visualize data patterns",
    instruction="Use statistical methods to identify trends"
)

report_writer = WorkerAgent(
    name="report_writer",
    role="Drafts executive summaries, compiles technical documentation, and formats reports with charts and tables",  # REQUIRED: Concise role
    goal="Create professional reports",
    instruction="Write clear, concise executive summaries"
)

3. Error Handling Strategy

from agentrouter.exceptions import (
    ExecutionError,
    MaxIterationsError,
    APIError
)

try:
    result = await manager.run("Complex task")
except MaxIterationsError:
    # Task too complex, consider breaking it down
    logger.warning("Task exceeded max iterations")
except APIError as e:
    # API failure, check connectivity
    logger.error(f"API error: {e}")
except ExecutionError as e:
    # General execution failure
    logger.error(f"Execution failed: {e}")

4. Configuration Optimization

# Optimize for different scenarios
quick_response = ManagerAgent(
    name="quick",
    api_key="key",
    max_iterations=10,      # Fewer iterations for simple tasks
    api_timeout=30.0        # Shorter timeout
)

thorough_analysis = ManagerAgent(
    name="thorough",
    api_key="key",
    max_iterations=50,      # More iterations for complex tasks
    api_timeout=120.0,      # Longer timeout
    worker_timeout=180.0    # Extended worker execution time
)

🔍 Monitoring & Debugging

Using the Pipeline Tracer

from agentrouter.visualization import PipelineTracer

# Enable tracing
tracer = PipelineTracer()
manager.set_tracer(tracer)

# Execute with tracing
result = await manager.run("Analyze customer feedback")

# Display execution trace
tracer.display()
# Shows: API calls, tool executions, agent delegations, timing

Key Metrics to Monitor

Metric	Description	Typical Range
Iterations Used	Number of Plan-Execute cycles	1-10 for most tasks
Execution Time	Total task completion time	Varies by complexity
Tool Calls	Number of tool executions	0-20 per task
Agent Delegations	Number of worker invocations	0-5 per task
API Calls	Total API requests	2-30 per task

🚀 Common Orchestration Patterns

1. Sequential Processing

Tasks processed in order, each depending on previous results:

# Data pipeline example
collect_data → validate_data → analyze_data → generate_report

2. Delegation Pattern

Manager delegates to specialized workers:

# Customer service example
manager → (billing_agent | technical_support | sales_agent)

3. Hierarchical Processing

Multi-level delegation for complex tasks:

# Organization structure
ceo → department_heads → team_leads → specialists

Next: Dive into the Execution Engine

Learn about retry mechanisms, error handling, and configuration management

Explore Execution →

🎼 The Symphony of Intelligent Coordination​

🔄 Core Orchestration Flow​

📋 Planning Agent - The Brain​

Decision Making Process​

Planning Response Structure​

Agent Communication Protocol​

Message Flow Between Agents​

🔧 Tool vs Agent Decision Logic​

Decision Matrix​

🔄 Iteration Control & Max Iterations​

Flow Control​

Configurable Iteration Limits​

🔐 Message History Management​

How Messages Flow Through the System​

Message Transformation for Final Response​

🚦 Agent Status States​

🎯 Real-World Orchestration Example​

E-Commerce Order Processing​

💡 Orchestration Best Practices​

1. Task Decomposition​

2. Agent Specialization​

3. Error Handling Strategy​

4. Configuration Optimization​

🔍 Monitoring & Debugging​

Using the Pipeline Tracer​

Key Metrics to Monitor​

🚀 Common Orchestration Patterns​

1. Sequential Processing​

2. Delegation Pattern​

3. Hierarchical Processing​