Conditional Edges

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"
    llm_model: "gemini-1.5-pro"  # Optional: specific model for evaluation

**Required fields:**
- `condition`: Template string with variable substitution
- `condition_type`: Must be `"boolean"`
- `routing`: Dict with `yes` and `no` keys mapping to agent names

**Optional fields:**
- `llm_model`: Specific model to use for this routing decision. Must be compatible with BAML (e.g., `gemini-1.5-pro`, `mistral-large-latest`).

### 2. Literal Edges

For multi-way routing based on specific values:

```yaml
edges:
  - from: "agent_name"
    condition: "Route based on {{agent_name.output.category}}"
    condition_type: "literal"
    possible_outputs: ["agent_a", "agent_b", "agent_c"]
    llm_model: "gemini-1.5-pro"  # Optional override

Required fields:

condition: Template string with variable substitution
condition_type: Must be "literal"
possible_outputs: List of valid agent names to route to

Optional fields:

llm_model: Specific model to use for this routing decision. Must be compatible with BAML.

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

Loop-Back Edges

Conditional edges can route back to a previous agent, creating loops for iterative refinement. Use recursion_limit at the system level to prevent infinite cycles:

name: "Iterative Refinement"
architecture: "workflow"
recursion_limit: 20

agents:
  - name: "drafter"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: "Draft a response based on the user's request."

  - name: "reviewer"
    agent_type: "llm_agent"
    structured_output:
      enabled: true
      schema:
        approved:
          type: "bool"
          description: "Whether the draft meets quality standards"

edges:
  - from: "__start__"
    to: "drafter"
  - from: "drafter"
    to: "reviewer"
  - from: "reviewer"
    condition: "Is the draft approved? {{reviewer.output.approved}}"
    condition_type: "boolean"
    routing:
      yes: "__end__"
      no: "drafter"     # Loop back to drafter for revision

entry_point: "drafter"

Always set recursion_limit when using loop-back edges. The default limit is 5 steps (configurable via environment variables). Without a sufficient limit, the workflow may terminate early.

Conditional Routing from START

You can use a conditional edge from __start__ to dynamically select the first agent based on user input. Set entry_point to "START" to enable this:

name: "Dynamic Entry Router"
architecture: "workflow"
entry_point: "START"

agents:
  - name: "simple_handler"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: "Handle simple questions directly."

  - name: "research_handler"
    agent_type: "react_agent"
    tools: ["tavily_search"]
    prompt_config:
      system_prompt: "Research complex questions using web search."

edges:
  - from: "__start__"
    condition: "Based on the user's question: {{user_input}}, determine if this is a simple question or requires research."
    condition_type: "literal"
    possible_outputs: ["simple_handler", "research_handler"]
  - from: "simple_handler"
    to: "__end__"
  - from: "research_handler"
    to: "__end__"

When entry_point is "START", no automatic edge from __start__ to an agent is created. You must define your own edge from __start__ (either static or conditional).

How Evaluation Works

Under the hood, conditional edges use a multi-step evaluation pipeline:

Variable substitution: Template variables like {{agent.output.field}} are replaced with actual values from the workflow state
LLM evaluation: The substituted condition is sent to an LLM via BAML structured output for reliable parsing. This uses the default model unless overridden by llm_model.
Validation: The LLM’s response is validated (against possible_outputs for literal, or yes/no for boolean)
Retry logic: If the response is invalid, the evaluation is retried up to 3 times with a 1-second delay
Fallback: If all retries fail, the edge routes to __end__ to terminate the workflow gracefully

The BAML evaluation returns both a routing decision and a reasoning explanation. The reasoning is included in observability events for debugging.

Template Variables in Conditions

Condition templates support the same {{ }} syntax as agent prompts:

Variable	Description
`{{agent_name.output.field}}`	Structured output field from a previous agent
`{{agent_name.output}}`	Full text output from a previous agent (last message)
`{{user_input}}`	The current user message
`{{history}}` or `{{history[N]}}`	Conversation history (all or last N messages)
`{{variables.var_name}}`	Global workflow variable

Special Node Names

Both __start__/__end__ and START/END are valid node names in edges. They are normalized internally:

# These are equivalent:
- from: "__start__"
  to: "agent_a"

- from: "START"
  to: "agent_a"

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 recursion_limit when using loop-back edges. The default is 5 steps, which may be too low for iterative workflows.

Handle All Cases: Ensure every possible output value has a corresponding route. If the LLM returns an invalid value, the edge will retry up to 3 times, then fall back to __end__.

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 supervisor or single agents

For literal edges, every value in possible_outputs must be a valid agent name defined in the agents list

Next Steps

Structured Output

Learn how to define schemas for reliable conditional routing

Sequential Patterns

Build linear pipelines with static edges

Supervisor Pattern

Use dynamic routing without explicit edges

YAML Configuration

Complete guide to workflow and edge configuration

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Artaios Agents Studio

Platform

Integration

Overview

How Conditional Edges Work

Conditional Edge Types

1. Boolean Edges

Basic Conditional Routing

Boolean Routing (Quality Gates)

Multi-Way Routing (Classification)

Using with Structured Output

Loop-Back Edges

Conditional Routing from START

How Evaluation Works

Template Variables in Conditions

Special Node Names

Best Practices

Common Use Cases

Next Steps

Structured Output

Sequential Patterns

Supervisor Pattern

YAML Configuration

​Overview

​How Conditional Edges Work

​Conditional Edge Types

​1. Boolean Edges

​Basic Conditional Routing

​Boolean Routing (Quality Gates)

​Multi-Way Routing (Classification)

​Using with Structured Output

​Loop-Back Edges

​Conditional Routing from START

​How Evaluation Works

​Template Variables in Conditions

​Special Node Names

​Best Practices

​Common Use Cases

​Next Steps

Structured Output

Sequential Patterns

Supervisor Pattern

YAML Configuration

Overview

How Conditional Edges Work

Conditional Edge Types

1. Boolean Edges

Basic Conditional Routing

Boolean Routing (Quality Gates)

Multi-Way Routing (Classification)

Using with Structured Output

Loop-Back Edges

Conditional Routing from START

How Evaluation Works

Template Variables in Conditions

Special Node Names

Best Practices

Common Use Cases

Next Steps