Orchestration Builder User Guide

1. Introduction

Orchestration workflows coordinate multiple AI agents to work together, like a "Kubernetes for AI Agents." Unlike individual Agent Definitions (which define single agents), orchestrations define how multiple agents communicate, share state, and coordinate their work.

Key Concepts

• Orchestration Workflow: A complete workflow that coordinates multiple agents
• State: Shared, structured context that all steps can read and write to
• Step: A single unit of work (agent execution, tool call, human approval, parallel execution)
• Transition: Conditional control flow between steps
• Flow: The overall execution graph (start, end, max iterations)

2. Getting Started

Launching the Orchestration Builder

1. Open Agent Genesys: Launch the application
2. Welcome Screen: Click "New Orchestration" button
3. Orchestration Builder Opens: You'll see the Orchestration Builder workspace

Prerequisites

Before building your first orchestration:

1. Agent Definitions: Create at least one Agent Definition (see Agent Builder Guide)
   • Agents are referenced by their ID in orchestration steps
   • Each agent should have clear input/output schemas
2. Basic Understanding: Familiarity with:
   • Agent Definitions (how single agents work)
   • State management (shared data between steps)
   • Conditional logic (if/then branching)

3. Understanding the Interface

The Orchestration Builder interface consists of five main areas:

1. Header (Top Bar)

The header contains global actions:

• Orchestration Name: Click to edit your orchestration's name
• Menu Icon (☰): Access actions:
  • Load Orchestration: Open an existing orchestration
  • Save: Save your current orchestration
  • Execute: Run the orchestration with initial state
  • Export: Export orchestration definition
  • Settings: Configure providers and settings
  • Validation: Shows validation errors (red badge with count)

Status Indicators:

• Validation Badge: Red circle with error count (if validation errors exist)
• "Unsaved changes": Red indicator when you have unsaved work
• "Saved [time]": Green indicator showing last save time

2. Canvas (Center Area)

The canvas is where you build your orchestration workflow:

• Adding Steps: Click step types in the bottom toolbar, then click canvas to place
• Moving Steps: Click and drag steps to reposition them
• Connecting Steps: Drag from an output handle (bottom) to an input handle (top) to create transitions
• Selecting Steps: Click a step to select it (properties appear in right panel)
• Double-Click Agent Steps: Opens the agent's definition in a new tab for editing
• Deleting: Select a step and press Delete key, or right-click and select "Delete"
• Panning: Click the Hand tool (👋) in the bottom toolbar, then click and drag the canvas
• Right-Click Panning: Hold right mouse button and drag to temporarily pan

Canvas Modes (Bottom Toolbar):

• Hand (👋): Pan mode - click and drag to move around
• Pointer (👆): Select mode - click to select steps, drag to move them
• Step Type Icons: Click to enter "add step" mode, then click canvas to place

Step Types Available:

• Agent Step 🤖: Execute an Agent Definition
• Parallel Step ⚡: Run multiple branches in parallel
• Human Gate 👤: Wait for human approval
• Tool Step 🔧: Call an external tool (web search, file system, API)
• Condition 🔀: Conditional branching (used in transitions)
• Join 🔗: Merge parallel branch results

3. Properties Panel (Right Sidebar)

The Properties Panel shows configuration options organized into tabs:

• Step Configuration: Configure the selected step (agent, tool, parallel, etc.)
• State Schema: Define the structure of shared state
• Transitions: Configure conditional flow between steps
• Execution View: Monitor execution in real-time
• Trace Viewer: View detailed execution traces for debugging
• Flow Config: Configure start/end steps, max iterations, timeout
• Validation: View validation errors

Opening/Closing:

• Click icons in the right sidebar dock to open panels
• Panels slide out as drawers
• Click outside or press Escape to close

4. Bottom Toolbar

The bottom toolbar contains:

• Mode Controls: Hand (pan) and Pointer (select) icons
• Step Type Icons: Click to add steps to the canvas
• Visual Indicators: Active mode/step type is highlighted with glow

5. Right Sidebar Dock

Icons for opening different panels:

• ⚙️ Step Configuration: Configure selected step
• 📊 State Schema: Define state structure
• ➡️ Transitions: Edit transition conditions
• ▶️ Execution: Monitor and run orchestrations
• 🔍 Trace Viewer: View execution traces
• ⚙️ Flow Config: Configure flow settings
• ✅ Validation: View validation errors (red badge if errors exist)

4. Creating Your First Orchestration

Let's build a simple two-agent orchestration: a research agent followed by a writing agent. This introduces the basic workflow.

Step 1: Name Your Orchestration

1. Click on the orchestration name in the header (default: "New Orchestration")
2. Type: "Research and Write"
3. Press Enter or click outside to save

Step 2: Define State Schema

1. Click the State Schema icon (📊) in the right sidebar dock
2. The State Schema Editor opens
3. Add fields:
   • Click "Add Field"
   • Field Name: research_question
   • Type: string
   • Click "Add"
   Repeat for:
   • Field Name: research_results, Type: array, Items: string, Default: []
   • Field Name: final_draft, Type: string, Default: null
4. The state schema defines what data is shared between steps

Step 3: Add an Agent Step (Research)

1. In the bottom toolbar, click the Agent Step icon (🤖)
2. Click on the canvas (left side) to place the step
3. Click the step to select it (Properties Panel opens)
4. In the Step Configuration panel:
   • Agent: Select your research agent from the dropdown
   • Input Mapping: Map agent inputs to state:
     • Agent Input: question → State Field: research_question
   • Output Mapping: Map agent outputs to state:
     • State Field: research_results → Operation: set → Agent Output: findings

Step 4: Add an Agent Step (Writing)

1. Click the Agent Step icon again
2. Click on the canvas (right side of the research step)
3. Select the new step
4. In Step Configuration:
   • Agent: Select your writing agent
   • Input Mapping:
     • Agent Input: notes → State Field: research_results
   • Output Mapping:
     • State Field: final_draft → Operation: set → Agent Output: draft

Step 5: Configure Flow

1. Click the Flow Config icon (⚙️) in the right sidebar
2. Set:
   • Start Step: Select your research step (the first agent step)
   • End Step: end (special value for workflow end)
   • Max Iterations: 10 (prevents infinite loops)
   • Timeout (seconds): 300 (5 minutes)

Step 6: Connect Steps (Create Transitions)

1. Hover over the bottom handle of the research step
2. Click and drag to the top handle of the writing step
3. Release to create a transition
4. Click the Transitions icon (➡️) to edit transition conditions
5. For this simple flow, the default transition (always go to next step) is fine

Step 7: Execute Your Orchestration

1. Click the Execution icon (▶️) in the right sidebar
2. In the Execution View:
   • Enter initial state in the JSON editor:

     {
       "research_question": "What are the benefits of AI?",
       "research_results": [],
       "final_draft": null
     }

3. Click "Execute"
4. Watch the execution flow through steps
5. See state updates in real-time
6. View the final result

Step 8: Save Your Orchestration

1. Click "Save" in the header menu
2. Your orchestration is now saved

5. Step Types

This section details each step type, its purpose, and configuration options.

Agent Step

Purpose: Executes an Agent Definition with input/output mapping to shared state.

Icon: 🤖

Configuration Options

Input Mapping

Maps state fields to agent input fields.

• Example: { "question": "state.research_question", "context": "state.context" }
• Agent receives mapped inputs when executed

Output Mapping

Maps agent outputs to state fields.

Operations:

• set: Replace state field value
• append: Add to array field
• merge: Merge object into state field
• concat: Concatenate string/array values

Example: { "state.research_results": { "operation": "set", "value": "output.findings" } }

Retry Policy

• max_retries: Number of retry attempts (default: 0)
• on_failure: Action on failure:
  • halt: Stop execution
  • continue: Continue to next step
  • fallback: Use fallback step

Validation Rules

• Validate agent output before proceeding
• Can check type, format, required fields, etc.

Double-Click Behavior: Opens the agent's definition in a new tab for editing

Parallel Step

Purpose: Executes multiple branches of steps in parallel.

Icon: ⚡

Configuration Options

Join Strategies

1. merge (default):
   • Merges outputs from all branches
   • Requires join step with merge rules
   • Example: Combine research from multiple sources
2. first_complete:
   • Uses result from first branch to complete
   • Other branches may continue but results are ignored
   • Example: Redundant API calls for reliability
3. majority_vote:
   • Requires multiple branches with same output structure
   • Selects output that appears in majority of branches
   • Example: Consensus-based decisions
4. manual_review:
   • Pauses execution for human review
   • Human selects which branch result to use
   • Example: Quality control checkpoint

Join Step

Purpose: Merges results from parallel branches into shared state.

Icon: 🔗

Configuration Options

Merge Rules (for merge strategy)

Merge Operations

• concat: Concatenate arrays or strings
• merge: Merge objects (deep merge)
• first: Use first branch's result
• last: Use last branch's result

Target Field: state.combined_research
Operation: concat
Source Branches: ["branch_1", "branch_2", "branch_3"]

Human Gate Step

Purpose: Pauses execution and waits for human approval before proceeding.

Icon: 👤

Configuration Options

Execution Behavior

• Execution pauses at this step
• Human Gate modal appears with the prompt
• Human can:
  • Approve: Continue to next step
  • Reject: Stop execution (or go to rejection step)
  • Custom Action: Provide custom data and proceed

Timeout Handling

• If timeout is set and exceeded:
  • on_timeout action is executed
  • Can route to another step, approve, or reject

Use Cases

• Quality control checkpoints
• Sensitive decision points
• Manual data validation
• Content moderation

Prompt: "Review the generated content for accuracy and tone. Approve to continue or reject to stop."
Timeout: 3600 (1 hour)
On Timeout: "approve"

Tool Step

Purpose: Calls an external tool (web search, file system, API call).

Icon: 🔧

Configuration Options

Available Tools

1. Web Search:
   • Parameters: query (search query string)
   • Output: Search results array
2. File System:
   • Parameters: operation (read, write, list), path, content (for write)
   • Output: File contents or operation status
3. API Call:
   • Parameters: url, method (GET, POST, etc.), headers, body
   • Output: API response

Output Mapping

• Similar to Agent Step output mapping
• Maps tool output to state fields
• Example: { "state.search_results": { "operation": "set", "value": "output.results" } }

Condition Node

Purpose: Visual representation of conditional transitions (configured in Transitions panel).

Icon: 🔀

Configuration: Use the Transitions panel to configure conditions (see Transitions section).

6. State Management

State is the shared, structured context that all steps can read from and write to.

Defining State Schema

1. Click the State Schema icon (📊) in the right sidebar
2. Click "Add Field"
3. Configure field:
   • Field Name: Unique identifier (e.g., user_query)
   • Type: Data type (string, number, boolean, array, object, null, or union)
   • Default: Default value (optional)
   • Items: For array types, item type (e.g., string for array[string])
   • Enum: For string types, allowed values (optional)
   • Validation Rules: Min/max, pattern, etc. (optional)
4. Click "Add"
5. Repeat for all state fields

Field Types

• string: Text values
• number: Numeric values
• boolean: True/false values
• array: Arrays (specify item type in "Items" field)
• object: Objects (complex nested structures)
• null: Nullable types (use union: ["string", "null"])

Validation Rules

For each field, you can set:

• Minimum/Maximum: For numbers (e.g., min: 0, max: 100)
• Min Length/Max Length: For strings/arrays (e.g., minLength: 1, maxLength: 1000)
• Pattern: Regex pattern for strings (e.g., email validation)
• Enum: Allowed values for strings (e.g., ["pending", "approved", "rejected"])

Accessing State in Steps

In Input Mapping

• Reference state fields: state.field_name
• Example: { "question": "state.research_question" }

In Output Mapping

• Write to state fields: state.field_name
• Example: { "state.results": { "operation": "set", "value": "output.data" } }

In Transition Conditions

• Reference state: state.field_name
• Example: len(state.research_notes) >= 3

State Immutability

• Steps receive a snapshot of state at execution time
• Steps write changes back to state via output mappings
• State updates are atomic per step
• Parallel branches receive the same state snapshot

7. Transitions and Flow Control

Transitions define how execution flows from one step to another.

Creating Transitions

Visual Method

1. Drag from output handle (bottom) of source step to input handle (top) of target step
2. Connection line appears
3. Transition is created automatically

Editing Transitions

1. Click the Transitions icon (➡️) in the right sidebar
2. Select source step from dropdown
3. View/edit conditions for that step

Transition Conditions

Each transition can have multiple conditions:

Condition Structure

{
  "if": "len(state.research_notes) >= 3",
  "to": "writing_step",
  "validate": []
}

Condition Expression (if field)

• Python-like expressions
• Access state: state.field_name
• Built-in functions: len(), str(), int(), etc.
• Operators: ==, !=, >, <, >=, <=, and, or, not, in

Examples

• len(state.research_notes) >= 3 - Array has at least 3 items
• state.status == "approved" - Status equals "approved"
• state.score > 80 and state.reviewed == true - Complex condition
• "error" in state.message.lower() - String contains substring

Default Transition

• If no conditions match, execution follows the default transition
• Can be set to a specific step or end (terminate)

Transition Validation

• Each condition can have validation rules
• Validate state before transitioning
• Can check required fields, data types, constraints
• If validation fails, transition is blocked

Flow Configuration

Click the Flow Config icon (⚙️) to configure overall flow:

Flow Bounds

• Max Iterations: Prevents infinite loops (execution stops if exceeded)
• Timeout: Prevents execution from running forever (execution stops if exceeded)

8. Common Orchestration Patterns

This section shows how to build common orchestration types.

9. Best Practices

1. State Schema Design

• Use clear field names: user_email not ue
• Set appropriate types: Use arrays for lists, objects for complex data
• Provide defaults: Set default values for optional fields
• Use validation: Add constraints (min/max, enum, pattern)
• Document fields: Use descriptions to explain field purpose

2. Step Organization

• Name steps clearly: "Research Agent" not "Step 1"
• Layout left-to-right: Start with input, end with output
• Group related steps: Keep parallel branches visually together
• Use alignment: Align steps for readability

3. Input/Output Mapping

• Map explicitly: Don't rely on implicit mappings
• Use descriptive names: Clear field names in mappings
• Choose appropriate operations: Use set for replacement, append for arrays, merge for objects
• Validate mappings: Ensure mapped fields exist in state schema

4. Transitions

• Use conditions wisely: Don't over-complicate transition logic
• Provide defaults: Always have a fallback path
• Validate before transitions: Use validation rules to ensure data quality
• Document complex logic: Add comments explaining transition conditions

5. Parallel Execution

• Use for independent work: Parallelize only when steps don't depend on each other
• Choose appropriate join strategy: Match strategy to use case
• Configure merge rules carefully: Ensure merge rules match data structure
• Test parallel execution: Verify branches execute correctly

6. Human Gates

• Use sparingly: Only for critical decision points
• Set reasonable timeouts: Don't leave gates open indefinitely
• Provide clear prompts: Explain what human needs to review
• Handle timeouts gracefully: Define on_timeout behavior

7. Error Handling

• Configure retry policies: Set retries for unreliable steps
• Define failure actions: Choose halt, continue, or fallback
• Test error scenarios: Verify error handling works
• Log errors: Use trace viewer to debug failures

8. Performance

• Use parallel execution: Parallelize independent steps
• Set appropriate timeouts: Don't let executions run forever
• Limit max iterations: Prevent infinite loops
• Optimize state size: Don't store unnecessary data in state

9. Testing

• Test incrementally: Test as you build
• Test with varied inputs: Different state values
• Test edge cases: Empty arrays, null values, boundary conditions
• Use trace viewer: Debug execution issues
• Monitor execution: Use execution view to watch real-time execution

10. Documentation

• Name orchestrations clearly: Descriptive names
• Document state schema: Explain field purposes
• Document complex transitions: Explain conditional logic
• Keep it simple: Simple orchestrations are easier to maintain

Next Steps

Now that you understand the Orchestration Builder:

1. Build Complex Orchestrations: Combine multiple patterns
2. Explore Tools: Integrate external tools into workflows
3. Use Templates: Browse orchestration templates (when available)
4. Monitor Executions: Use execution and trace viewers for debugging
5. Share Orchestrations: Export and share with your team

Troubleshooting

Orchestration doesn't execute

• Check flow configuration (start step, end step)
• Verify state schema is defined
• Check validation errors (red badge in header)
• Review error messages in execution view

Steps not connecting

• Ensure you drag from output handle (bottom) to input handle (top)
• Check that transitions are configured correctly
• Verify step IDs match in transitions

State not updating

• Check output mappings are configured
• Verify state field names match exactly (case-sensitive)
• Ensure operation type is appropriate (set, append, merge, concat)
• Review trace viewer for state updates

Parallel execution issues

• Verify branches don't depend on each other
• Check join step is configured correctly
• Ensure merge rules match data structure
• Review trace viewer for parallel execution

Human gates not appearing

• Check human gate step is configured
• Verify execution reached the human gate step
• Check timeout settings
• Review execution view for pending gates

Validation errors

• Click validation icon to view errors
• Fix schema validation issues
• Correct step configuration errors
• Resolve transition condition errors

Additional Resources

• Agent Builder Guide: Learn how to create Agent Definitions
• Orchestration Specification: Detailed technical specification
• API Documentation: Orchestration API reference
• Community Examples: Share and learn from community
• Support: Get help from the Agent Genesys community

Happy orchestrating! 🎼