> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/workflows/stages-and-routes.md).

# Stages and routes

Configure workflow responsibilities, Consensus and Quality Gate outcomes, review loops, and completion routes.

A stage represents a responsibility or an automated operation. A route defines which outcome moves work to the next stage. Build the ordinary path and its exceptions together so every active item has a destination and an accountable owner.

## Before you begin

* Write the annotation and acceptance policy, including how to handle ambiguous and invalid sources.
* Identify annotators, reviewers, and workflow managers.
* Prepare the ontology, source data, and any required models or approved benchmarks.
* Decide how existing in-flight work should be handled before changing an active workflow.

## Available stages

| Stage            | Responsibility                                                                                                                       | Routes to configure                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Project**      | Entry point for project work.                                                                                                        | Initial execution stage.                                       |
| **Annotate**     | Human labeling or correction.                                                                                                        | Next required check or stage.                                  |
| **Review**       | Human acceptance decision.                                                                                                           | Approved and Rejected.                                         |
| **Consensus**    | Independent annotations and agreement evaluation.                                                                                    | Pass and Fail; connect Fail to a Review stage.                 |
| **Quality Gate** | Comparison with an approved benchmark key.                                                                                           | Pass, Fail, and Not evaluated.                                 |
| **Model**        | Configured model inference.                                                                                                          | Supported completion or failure handling for that model stage. |
| **Agent**        | Work by a service you host: it receives each task by webhook, reads and saves its annotations with the SDK, then completes the task. | One route, taken when the service completes the run.           |
| **Logic**        | Routing by configured annotation or property rules.                                                                                  | Rule matches and fallback.                                     |
| **Sampling**     | Random split by a configured percentage.                                                                                             | Sampled and Unsampled.                                         |
| **Webhook**      | Delivery of a configured event to an HTTPS endpoint.                                                                                 | Success and Failure.                                           |
| **Archive**      | Terminal set-aside destination.                                                                                                      | No onward route.                                               |
| **Complete**     | Terminal successful destination.                                                                                                     | No onward route.                                               |

See [Agent stage](/documentation/workflows/agent-stage.md) to set up an Agent stage and the service it calls.

Use additional named Review stages for specialist or final review. Use an Annotate stage for rework when labels need correction. A display name such as “Expert Review” or “Rework” describes that stage's role; it does not introduce a different stage type.

The normal starting path is:

```
Project → Annotate → Review → Complete
```

The exact controls available to an operator depend on the stage, assignment, permissions, and current item state.

## Add Consensus and Quality Gate

**Consensus** collects independent human submissions, waits for all required votes, and checks agreement against a representative answer. Configure **Required votes**, **Must agree**, and **Answer similarity**. The canvas shows **Pass** for agreement and **Fail** for a result needing adjudication. **Connect Consensus Fail to a Review stage.** See [Consensus](https://docs.unitlab.ai/documentation/qa/consensus) for assignment, comparison, and Review and Refine instructions.

**Quality Gate** checks a submission against an approved hidden answer key. Configure one threshold and three separate outcomes: **Pass**, **Fail**, and **Not evaluated**. Missing or incompatible reference evidence must not be interpreted as a successful benchmark result. See [Quality Gate](https://docs.unitlab.ai/documentation/qa/quality-gate) for answer-key preparation and scoring.

Use [QA Overview](https://docs.unitlab.ai/documentation/qa/qa-overview) to distinguish agreement, benchmark evaluation, validation findings, and human approval. Use [QA Workflows](https://docs.unitlab.ai/documentation/qa/qa-workflows) for complete operating patterns.

## Build and configure the graph

1. Open a project's **Workflows** tab for its active graph, or open a reusable workflow from the workspace Workflows page.
2. Use **Add Stages** to place the required stages on the canvas.
3. Connect each stage's output to the appropriate downstream input. Use the outcome shown by the output handle rather than relying on visual position alone.
4. Select each node to configure its name, eligible members, assignment behavior, or automated settings.
5. Inspect every required outcome, including fallback, rejection, failure, and unavailable-comparison paths.
6. Use **Save & Apply**. Review validation and impact information before the change takes effect.
7. Exercise representative items with the roles that will operate the workflow.

Use clear stage names so the canvas, queues, and item history tell the same story. Configure allowed self-assignment, manager overrides, unassigned-work visibility, and skipping only where those controls are supported for the selected stage.

## Example: annotation with reference checks

```mermaid
flowchart TD
  P[Project] --> A[Annotate]
  A --> Q[Quality Gate]
  Q -->|Pass| R[Review]
  Q -->|Fail| A
  Q -->|Not evaluated| R
  R -->|Approved| C[Complete]
  R -->|Rejected| A
```

This example requires final human review for both passed and unbenchmarked work. Failed work returns for correction. If your policy permits automatic completion after a passed benchmark, configure that decision explicitly; a passing score does not inherently complete the item.

## Design review and exception routes

| Outcome                          | Operating rule                                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------------------------- |
| Review Approved                  | Continue to the next required stage or Complete.                                                |
| Review Rejected                  | Return to a correction stage with clear feedback and an eligible owner.                         |
| Consensus Fail                   | Send to Review for adjudication of the frozen submissions.                                      |
| Quality Gate Fail                | Correct the submission or investigate the reference and policy.                                 |
| Quality Gate Not evaluated       | Follow the explicit unbenchmarked-work path and investigate missing evidence where required.    |
| Processing or automation problem | Inspect the stage's error and supported recovery action; do not equate failure with acceptance. |
| Invalid or excluded source       | Follow the configured set-aside policy, such as Archive.                                        |

## Apply changes to active work

Replacing a project's workflow can affect items already in progress. Review the impact information and any proposed reset to Project. Preserve active Consensus assignments and review tickets where supported; some Consensus runtime settings cannot change while work is active. A new eligibility pool does not automatically replace existing assignments.

Follow [Change a live workflow](https://docs.unitlab.ai/documentation/workflows/change-a-live-workflow) before changing stage identity or routing for an active project.

## Verify the finished graph

Confirm that work can enter the graph, eligible users can claim it, saves remain in the current stage, submissions take the intended route, rejected work can return for review, and every required QA outcome is exercised. Confirm that Complete and Archive have distinct policy meanings.

## Next steps

* [Assignment and stage actions](https://docs.unitlab.ai/documentation/workflows/assignment-and-stage-actions)
* [Review, rework, and escalation](https://docs.unitlab.ai/documentation/workflows/review-rework-and-escalation)
* [QA Workflows](https://docs.unitlab.ai/documentation/qa/qa-workflows)