Skip to main content
Conditional edges enable dynamic routing in your agent workflows. Instead of following a fixed path, agents can route to different next steps based on their output, state, or structured data.

​
Overview

Conditional edges allow you to:
  • Route based on classification: Send content to different agents based on categories
  • Implement quality gates: Retry or revise work that doesn’t meet standards
  • Create decision trees: Branch workflows based on agent decisions
  • Build adaptive systems: Change behavior based on runtime conditions
Conditional edges enable dynamic routing in workflows, allowing agents to make runtime decisions about which path to take next.

​
How Conditional Edges Work

In a standard workflow, edges are static: 
edges:
  - from: "agent_a"
    to: "agent_b"  # Always goes to agent_b
With conditional edges, the next step is determined at runtime: 
edges:
  - from: "classifier"
    condition: "Route to the appropriate team based on {{classifier.output.category}}"
    condition_type: "literal"
    possible_outputs: ["tech_support", "billing_support", "general_support"]

​
Conditional Edge Types

There are two types of conditional edges:

​
1. Boolean Edges

For binary yes/no decisions (quality gates, approvals): 
edges:
  - from: "agent_name"
    condition: "Your decision prompt with {{agent_name.output.field}}"
    condition_type: "boolean"
    routing:
      yes: "success_agent"
      no: "failure_agent"
Required fields:
  • condition: Template string with variable substitution
  • condition_type: Must be "boolean"
  • routing: Dict with yes and no keys mapping to agent names

​
2. Literal Edges

For multi-way routing based on specific values: 
edges:
  - from: "agent_name"
    condition: "Route based on {{agent_name.output.category}}"
    condition_type: "literal"
    possible_outputs: ["agent_a", "agent_b", "agent_c"]
Required fields:
  • condition: Template string with variable substitution
  • condition_type: Must be "literal"
  • possible_outputs: List of valid agent names to route to

​
Basic Conditional Routing

​
Boolean Routing (Quality Gates)

Route based on true/false conditions: 
name: "Content Quality Gate"
description: "Review and revise content until it meets quality standards"
architecture: "workflow"

agents:
  - name: "writer"
    agent_type: "llm_agent"
    system_prompt: "Write a blog post on the given topic."
  
  - name: "quality_checker"
    agent_type: "llm_agent"
    
    system_prompt: |
      Review the blog post for quality. Check for:
      - Clear and engaging writing
      - Proper grammar and spelling
      - Logical structure
      - Appropriate length
      
      Determine if it passes quality standards.
    
    structured_output:
      enabled: true
      schema:
        passes_quality:
          type: "bool"
          description: "Whether the content meets quality standards"
        
        issues:
          type: "list[str]"
          description: "List of quality issues found"
        
        suggestions:
          type: "list[str]"
          description: "Suggestions for improvement"
  
  - name: "reviser"
    agent_type: "llm_agent"
    system_prompt: |
      Revise the blog post based on the quality feedback provided.
      Address all issues and implement suggestions.
  
  - name: "publisher"
    agent_type: "llm_agent"
    system_prompt: "Format and publish the approved blog post."

edges:
  - from: "__start__"
    to: "writer"
  
  - from: "writer"
    to: "quality_checker"
  
  # Conditional edge based on quality check
  - from: "quality_checker"
    condition: "Does the content pass quality standards? Check {{quality_checker.output.passes_quality}}"
    condition_type: "boolean"
    routing:
      yes: "publisher"      # If passes_quality = true
      no: "reviser"         # If passes_quality = false
  
  - from: "reviser"
    to: "quality_checker"    # Re-check after revision
  
  - from: "publisher"
    to: "__end__"

entry_point: "writer"

​
Multi-Way Routing (Classification)

Route to different agents based on categories: 
name: "Customer Support Router"
description: "Route support tickets to appropriate departments"
architecture: "workflow"

agents:
  - name: "ticket_classifier"
    agent_type: "llm_agent"
    
    system_prompt: |
      Analyze the customer support ticket and classify it into one of these categories:
      - technical: Technical issues, bugs, errors
      - billing: Payment, invoices, subscription questions
      - general: General inquiries, feedback, other
    
    structured_output:
      enabled: true
      schema:
        category:
          type: "str"
          description: "Support ticket category (technical, billing, or general)"
        
        priority:
          type: "str"
          description: "Ticket priority level (low, medium, high, or urgent)"
        
        summary:
          type: "str"
          description: "Brief summary of the issue"
  
  - name: "tech_support"
    agent_type: "react_agent"
    tools: ["knowledge_base_search", "bug_tracker"]
    system_prompt: "Handle technical support issues. Search knowledge base and create bug reports if needed."
  
  - name: "billing_support"
    agent_type: "react_agent"
    tools: ["payment_system", "invoice_generator"]
    system_prompt: "Handle billing and payment inquiries. Access payment history and generate invoices."
  
  - name: "general_support"
    agent_type: "llm_agent"
    system_prompt: "Handle general customer inquiries with friendly, helpful responses."

edges:
  - from: "__start__"
    to: "ticket_classifier"
  
  # Multi-way conditional routing
  - from: "ticket_classifier"
    condition: "Route to the appropriate support team based on {{ticket_classifier.output.category}}"
    condition_type: "literal"
    possible_outputs: ["tech_support", "billing_support", "general_support"]
  
  - from: "tech_support"
    to: "__end__"
  
  - from: "billing_support"
    to: "__end__"
  
  - from: "general_support"
    to: "__end__"

entry_point: "ticket_classifier"

​
Using with Structured Output

For reliable routing, use structured output to control conditional edges: 
agents:
  - name: "classifier"
    agent_type: "llm_agent"
    
    structured_output:
      enabled: true
      schema:
        category:
          type: "str"
          description: "Category: technical, billing, or general"
        priority:
          type: "str"
          description: "Priority: low, medium, or high"

edges:
  - from: "classifier"
    condition: "Route by category: {{classifier.output.category}}"
    condition_type: "literal"
    possible_outputs: ["tech_team", "billing_team", "general_team"]
Structured output ensures consistent, predictable routing decisions

​
Best Practices

Use Structured Output: Always use structured output with str fields for conditional routing. Specify allowed values clearly in descriptions and system prompts to ensure reliable, predictable routing decisions.
Clear Conditions: Make routing conditions explicit and mutually exclusive. Avoid ambiguous categories.
Limit Iterations: Set maximum iteration counts for loops to prevent infinite cycles.
Handle All Cases: Ensure every possible output value has a corresponding route. Missing routes will cause errors.
Test Edge Cases: Test your conditional logic with edge cases and unexpected inputs.

​
Common Use Cases

Quality Gates: Check if work meets standards → approve or send for revision Classification: Categorize inputs → route to specialized handlers Escalation: Try automated solution → escalate to human if needed Iterative Refinement: Generate → evaluate → improve until acceptable
Conditional edges only work with workflow architecture, not with single agents
For literal edges, every value in possible_outputs must be a valid agent name

​
Next Steps

Structured Output

Learn how to define schemas for reliable conditional routing

YAML Configuration

Complete guide to workflow and edge configuration