Router Tasks

Router tasks are the decision engine of Compozy workflows, enabling dynamic routing based on runtime conditions. They evaluate template expressions and direct workflow execution down different paths, making workflows intelligent and adaptive to varying data conditions. When combined with basic tasks and parallel processing, router tasks create sophisticated automation that can handle complex business logic automatically.

Key Benefits

Intelligent Decision Making

Evaluate complex conditions using template expressions to automatically route workflows based on data, user context, or business rules

Flexible Route Definitions

Define routes as simple task references or complex inline configurations with full task orchestration capabilities

Robust Fallback Handling

Built-in default routes and comprehensive error handling ensure workflows gracefully handle unexpected conditions

Business Logic Integration

Implement approval workflows, feature flags, content moderation, and complex business rules declaratively

How Router Tasks Work

Condition Evaluation
Router tasks evaluate template expressions against workflow context, task outputs, and input data to determine the routing path
Route Resolution
The condition result becomes a key to look up the target route, which can reference existing tasks or define inline configurations
Dynamic Execution
Based on the route selection, the workflow executes different task paths, enabling completely different business logic flows
State Management
Router execution state and route decisions are tracked by deployment options for durability and debugging

Router tasks leverage the same template engine used throughout Compozy, providing access to workflow input, task outputs, environment variables, and utility functions for comprehensive decision-making capabilities.

Task Structure

Understanding router task configuration is essential for building effective conditional workflows. Router tasks must define a condition expression and route mappings, with optional default and error handling strategies.

Before implementing router tasks, ensure you understand basic task configuration and template expressions. Router tasks build on these foundational concepts.

Core Configuration

Every router task follows this fundamental structure:

id: router-name
type: router
condition: "{{ .tasks.previous_task.output.result }}"

routes:
  route_key_1: target-task-id
  route_key_2:
    type: basic
    $use: agent(local::agents.#(id=="handler"))
    with:
      data: "{{ .workflow.input.data }}"
  route_key_3: another-task-id

# Optional fallback route
default: default-handler

# Error handling
on_error:
  next: error-handler

condition
Template expression that evaluates to determine routing. Can access workflow input, task outputs, and environment variables
routes
Map of condition results to target tasks. Values can be task IDs (string) or inline task configurations (object)
default
Fallback route when condition result doesn't match any route key. Essential for robust error handling
on_error
Error handling configuration when condition evaluation fails. Links to error handling patterns

Key Components

Router tasks support multiple configuration patterns, from simple routing to complex business logic. Understanding these patterns helps you choose the right approach for your use case.

Behind the Scenes

Understanding how router tasks execute helps optimize performance and debug issues. When a router task runs, it follows a sophisticated evaluation and execution pipeline that integrates with Compozy's template engine and task orchestration system.

Loading diagram...

Context Collection
Router tasks gather workflow input, previous task outputs, and environment variables to provide complete context for condition evaluation
Template Processing
The template engine evaluates conditions with access to all workflow state and utility functions
Route Resolution
Route lookup supports both task ID references and inline task configurations, enabling flexible workflow design patterns
Task Execution
Selected routes execute using the same task execution pipeline as regular workflow tasks
State Persistence
Routing decisions and execution results are persisted by deployment options for durability and observability

Conditional Routing Patterns

Router tasks excel at implementing complex business logic through template expressions. These patterns demonstrate common approaches for different types of conditional logic.

Template Expression Routing

The most common pattern uses template expressions to evaluate data and determine routing paths. This approach leverages Compozy's template expressions for powerful data processing:

id: weather-activity-router
type: router
condition: |
  {{
    $weather := .tasks.get_weather.output
    $temperature := $weather.temperature
    $conditions := $weather.conditions

    if (lt $temperature 32)
      "cold"
    else if (and (gt $temperature 75) (eq $conditions "sunny"))
      "hot_sunny"
    else if (contains $conditions "rain")
      "rainy"
    else
      "moderate"
  }}

routes:
  cold:
    type: basic
    $use: agent(local::agents.#(id=="activity-suggester"))
    with:
      weather_type: "cold"
      suggestions: ["indoor activities", "warm clothing", "hot drinks"]

  hot_sunny:
    type: basic
    $use: agent(local::agents.#(id=="activity-suggester"))
    with:
      weather_type: "hot"
      suggestions: ["swimming", "beach", "air conditioning"]

  rainy:
    type: basic
    $use: agent(local::agents.#(id=="activity-suggester"))
    with:
      weather_type: "rainy"
      suggestions: ["indoor activities", "umbrella", "movies"]

  moderate: moderate-weather-activities

This pattern demonstrates how router tasks can implement intelligent decision-making by analyzing task outputs and applying business rules to determine appropriate actions.

Multi-Factor Routing

Route based on multiple conditions:

id: user-onboarding-router
type: router
condition: |
  {{
    $user := .tasks.get_user.output
    if (eq $user.account_type "premium")
      "premium_user"
    else if (eq $user.verification_status "pending")
      "pending_verification"
    else
      "standard_user"
  }}

routes:
  premium_user:
    type: basic
    $use: agent(local::agents.#(id=="premium-onboarding"))
    with:
      user_data: "{{ .tasks.get_user.output }}"

  pending_verification: verification-workflow
  standard_user: standard-onboarding-workflow

default: error-handling-flow

Status-Based Routing

Route based on task completion status and results:

id: processing-status-router
type: router
condition: |
  {{
    $result := .tasks.process_data.output
    $status := $result.status
    $errors := $result.errors

    if (eq $status "success")
      "success"
    else if (and (eq $status "partial") (lt (len $errors) 5))
      "partial_success"
    else if (eq $status "failed")
      "failed"
    else
      "unknown"
  }}

routes:
  success:
    type: aggregate
    outputs:
      result: "{{ .tasks.process_data.output.data }}"
      status: "completed"
      processed_at: "{{ now }}"

  partial_success:
    type: basic
    $use: agent(local::agents.#(id=="error-analyzer"))
    with:
      data: "{{ .tasks.process_data.output.data }}"
      errors: "{{ .tasks.process_data.output.errors }}"
      action: "analyze_and_fix"

  failed:
    type: basic
    $use: tool(local::tools.#(id=="error-handler"))
    with:
      original_input: "{{ .workflow.input }}"
      error_details: "{{ .tasks.process_data.output.errors }}"
      retry_count: "{{ .tasks.process_data.retry_count }}"

default: escalation-handler