> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown Workflow Branches

> Route markdown-workflow steps based on step output

Markdown workflows branch on any step's output — jump to a labelled step instead of running linearly.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Markdown Branch"
        In[📝 Request] --> Classify[🤖 step1: Classify]
        Classify --> Branch{branch match?}
        Branch -->|success| Success[✅ handle_success]
        Branch -->|failure| Failure[❌ handle_failure]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff

    class In,Classify agent
    class Branch decision
    class Success success
    class Failure process
```

## Quick Start

**1. Write a branching workflow**

````markdown .praisonai/workflows/classify.md theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
name: classify
---

## step1
Classify the request as success or failure.

```branch
success: [handle_success]
failure: [handle_failure]
```

## handle_failure
Escalate the request.

## handle_success
Reply to the request.
````

**2. Run it**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai workflow run .praisonai/workflows/classify.md
```

When `step1`'s output contains `success`, execution jumps to `handle_success` and skips `handle_failure`.

***

## How It Works

`WorkflowManager` evaluates each step's `branch_condition` against that step's output, then jumps to the first matching next step.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant WorkflowManager
    participant Step

    User->>WorkflowManager: praisonai workflow run classify.md
    WorkflowManager->>Step: Run step1
    Step-->>WorkflowManager: Output "...success..."
    WorkflowManager->>WorkflowManager: Match branch_condition
    WorkflowManager->>Step: Jump to handle_success
    Step-->>WorkflowManager: Reply
    WorkflowManager-->>User: Result
```

| Concept | Where it lives | Behavior |
| - | - | - |
| `branch` block | Fenced block under a step | Maps a match value → `[next_steps]` |
| `next_steps` | Frontmatter key | Steps to run if no branch matches |
| Match rule | Step output | First key found in the output wins |

***

## Configuration Options

| Option | Form | Description |
| - | - | - |
| ` ```branch ` | Fenced block | Dict of `match: [next_steps]` |
| `next_steps:` | Frontmatter key | Fallback next steps if no branch matches |
| `Task(routing=...)` | Python | Equivalent via `TaskRoutingConfig(branches=..., next_steps=...)` |

**Equivalent Python:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Task
from praisonaiagents.workflows.workflow_configs import TaskRoutingConfig

Task(
    name="step1",
    description="Classify the request",
    routing=TaskRoutingConfig(
        branches={"success": ["handle_success"], "failure": ["handle_failure"]},
    ),
)
```

***

## Common Patterns

**Success/failure classifier** — jump to a handler based on outcome:

````markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
## step1
Classify as success or failure.

```branch
success: [handle_success]
failure: [handle_failure]
```
````

**Score-based fanout** — route on a threshold match in the output:

````markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
## score
Score the submission and state "premium" or "standard".

```branch
premium: [premium_path]
standard: [standard_path]
```
````

**No-op fallback** — when nothing matches, execution continues linearly to the next step, so a missing branch never stalls the workflow.

***

## Best Practices

> [accordion] Name branch targets after real steps
>
> Every value in a `branch` block must reference an existing `## step`. Undefined targets are skipped.

> [accordion] Make the match value explicit in step output
>
> Instruct the step to state the match keyword clearly ("Reply with success or failure") so the branch matches reliably.

> [accordion] Keep one branch block per step
>
> Use a single `branch` block per step for a clear one-to-many jump. Use `next_steps` frontmatter for the default path.

***

## Related

> [card] [Conditional Execution](https://praison.ai/docs/features/conditions.md)
>
> Task when / then\_task / else\_task syntax

> [card] [YAML Workflows](https://praison.ai/docs/features/yaml-workflows.md)
>
> Full YAML workflow reference

> [card] [Workflow Routing](https://praison.ai/docs/features/workflow-routing.md)
>
> Python AgentFlow routing

> [card] [Tasks](https://praison.ai/docs/concepts/tasks.md)
>
> Task fields reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.