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

# Write your first multi-agent workflow in YAML

> Build a multi-agent coding workflow in YAML: a planner, an implementer and a reviewer that sends work back, checked locally, then run on your machine.

By the end of this guide you have one workflow file in which three agents share a task: a planner writes the plan, an implementer builds it, and a reviewer approves the change or sends it back with feedback. You check it on your own machine without signing in, then run it against a real repository.

The handoffs are declared in the file, not left to a prompt. The reviewer answers through a JSON schema, and the workflow routes on that answer with CEL.

## Before you begin

* The `reliant` CLI, v1.21 or later (`reliant version`). Validating, linting and scenario runs need no account and no network.
* A git repository with a test you can run. This guide uses a two-file Python project with a `greet.py` and a unittest.
* For the last two steps: a signed-in CLI ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)) and a connected machine that holds the repository ([Run a machine from the terminal](https://docs.reliantlabs.io/cli/run-a-machine.md)).

**1. Create the workflow file**

Save this as `.reliant/workflows/plan-build-review.yaml`. Reliant finds workflows by their `name:`, so give the file the same name.

```yaml .reliant/workflows/plan-build-review.yaml theme={null}
name: plan-build-review
title: Plan, build, review
description: A planner agent writes a plan, an implementer builds it, and a reviewer approves the change or sends it back.

inputs:
  max_rounds:
    type: integer
    default: 3
    min: 1
    max: 5
    description: Most implement-and-review rounds before the run stops

entry: [plan]

nodes:
  # Agent 1: read-only planning on the chat's own thread, so the plan
  # stays in the conversation the next agents fork from.
  - id: plan
    type: workflow
    ref: builtin://agent
    args:
      mode: plan
    thread:
      mode: inherit
      inject:
        role: user
        content: |
          Plan this change before anyone writes code. Read the relevant code,
          then list the files to touch, the steps in order, and how to test it.

  # Agents 2 and 3 take turns until the reviewer approves.
  - id: build_loop
    type: loop
    while: outputs.verdict != 'approve' && iter.iteration < inputs.max_rounds
    inline:
      entry: [implement]
      outputs:
        verdict: "{{has(nodes.review.response) && nodes.review.response != null ? nodes.review.response.verdict : 'changes_requested'}}"
        feedback: "{{has(nodes.review.response) && nodes.review.response != null ? nodes.review.response.feedback : ''}}"
      nodes:
        - id: implement
          type: workflow
          ref: builtin://agent
          args:
            mode: auto
          thread:
            mode: fork
            inject:
              role: user
              content: |
                Implement the plan above (round {{iter.iteration + 1}}). Run the tests you touch.
                {{iter.iteration > 0 ? 'The reviewer asked for changes:\n' + outputs.feedback : ''}}
          # Save the implementer's summary where the reviewer can read it.
          save_message:
            role: assistant
            content: "Implementation, round {{iter.iteration + 1}}:\n{{output.response_text}}"

        - id: review
          type: workflow
          ref: builtin://structured-agent
          args:
            mode: auto
            max_turns: 40
            tools: ["view", "tag:shell"]   # read and run, no edit tools
            system_prompt: You review code changes. You never change files.
            response_tool_name: submit_review
            response_schema:
              type: object
              required: [verdict, feedback]
              properties:
                verdict:
                  type: string
                  enum: [approve, changes_requested]
                feedback:
                  type: string
                  description: What must change, or why the change is ready
          thread:
            mode: fork
            inject:
              role: user
              content: |
                Review the implementation above against the plan. Read the diff and
                run the tests. Submit approve only if it is correct and complete.
      edges:
        - from: implement
          default: review

  # A CEL edge routes on the loop's final verdict.
  - id: done
    type: save_message
    outcome: success
    args:
      role: assistant
      content: "Approved after {{nodes.build_loop._iterations}} round(s)."

  - id: needs_attention
    type: save_message
    outcome: failure
    args:
      role: assistant
      display_style: warning
      content: |
        Not approved after {{nodes.build_loop._iterations}} round(s). Last review:
        {{nodes.build_loop.feedback}}

edges:
  - from: plan
    default: build_loop
  - from: build_loop
    cases:
      - to: done
        condition: nodes.build_loop.verdict == 'approve'
        label: approved
    default: needs_attention
```

Here is how the three agents hand off work:

* **The planner** runs `builtin://agent` in `plan` mode, which gives it read-only tools. It shares the run's thread (`inherit`), so its plan stays in the conversation.
* **The implementer and the reviewer** each `fork` that thread. Each one starts with the plan but works in its own context. The `save_message` on `implement` copies the implementer's summary back to the shared thread, where the reviewer reads it.
* **The reviewer** runs `builtin://structured-agent`, which keeps prompting until the model calls `submit_review` with an answer that fits the schema. Its tool list has no edit tools, but `tag:shell` can still run commands.
* **The loop** sends work back. Its `while` reads the verdict, and the reviewer's `feedback` is injected into the implementer's next round. `iter.iteration < inputs.max_rounds` bounds the loop.
* **The last edge** sends an approval to `done` and anything else to `needs_attention`. `outcome:` on those two nodes decides whether the run succeeded.

Each field is listed in the [workflow schema](https://docs.reliantlabs.io/reference/workflow-schema.md) and [node types](https://docs.reliantlabs.io/reference/nodes.md) references.

**2. Validate and lint it**

`validate` checks structure, CEL and types. `lint` checks whether the workflow still behaves when nobody is watching it.

```bash terminal theme={null}
reliant workflow validate
reliant workflow lint
```

```text theme={null}
Validating 1 workflow(s)

  ✓ plan-build-review.yaml (plan-build-review)
      Lint warning: [scenario-none] the workflow has no scenarios, so none of its triggers or endings is tested (add scenarios under .reliant/workflows/plan-build-review/scenarios/) https://docs.reliantlabs.io/workflows/lint#scenario-none
...
✅ All workflows valid
```

The next step clears the one warning. [Lint rules](https://docs.reliantlabs.io/workflows/lint.md) describes every rule.

**3. Test the send-back path with a scenario**

A scenario runs the real workflow engine with mocked agent results, so you can check the loop without spending tokens. This one has the reviewer request changes once and then approve. Mock each agent by its node path:

```yaml .reliant/workflows/plan-build-review/scenarios/approved_on_second_round.yaml theme={null}
name: approved_on_second_round
description: The reviewer requests changes once, then approves

events:
  - node: plan
    output:
      response_text: "1. Add a --verbose flag to cli.py. 2. Test it in test_cli.py."
  # Round 1
  - node: build_loop.implement
    output:
      response_text: "Added --verbose. Tests pass."
  - node: build_loop.review
    output:
      completed: true
      response:
        verdict: changes_requested
        feedback: "test_cli.py never runs the command with --verbose."
  # Round 2
  - node: build_loop.implement
    output:
      response_text: "Added a test that runs the command with --verbose."
  - node: build_loop.review
    output:
      completed: true
      response:
        verdict: approve
        feedback: "The flag works and is tested."

expect:
  outcome: completed
  completed: [plan, build_loop, done]
  not_reached: [needs_attention]
  node_outputs:
    build_loop:
      verdict: approve
      _iterations: 2
  messages:
    done:
      content_contains: ["Approved after 2 round(s)."]
```

Add a second scenario, `never_approved.yaml`, with `inputs: {max_rounds: 1}`, one `changes_requested` review and `expect: {outcome: failed, completed: [needs_attention]}`, so both endings are tested. Then run them:

```bash terminal theme={null}
reliant workflow scenario run
```

```text theme={null}
Running 2 scenario(s) across 1 workflow(s)

  ✓ plan-build-review/approved_on_second_round (664ms)
  ✓ plan-build-review/never_approved (40ms)
...
✅ All scenarios passed
```

`reliant workflow lint` now reports `0 lint error(s), 0 warning(s)`. The scenario file format is in [Testing workflows](https://docs.reliantlabs.io/workflows/testing.md).

**4. Run it on your machine**

Start a run from the repository. `--project-path .` finds the Reliant project for this folder, or creates one. `--follow` streams events until the run ends.

```bash terminal theme={null}
reliant workflow run plan-build-review --project-path . \
  --input max_rounds=2 \
  --message "Add a --shout flag to greet.py that prints the greeting in upper case, with a unittest test (run tests with python3 -m unittest)." \
  --follow --timeout 25m
```

```text theme={null}
Workflow "plan-build-review" triggered
  Chat/Execution ID: 414eee72-c07d-4806-8186-5c7e25f8fb02
  Title:             plan-build-review · Add a --shout flag to greet.py that prints the greeting in… (listed under Runs)
{"event":"workflow_started",...,"workflow_name":"plan-build-review",...}
{"event":"node_started",...,"node_id":"call_llm",...}
...
{"event":"node_completed",...,"node_id":"done",...}
{"event":"workflow_completed",...,"new_state":"completed",...,"outcome":"success"}
```

The run is listed under **Runs** in the app, not in your sidebar. It runs on the machine that holds the folder. Add `--daemon` to choose a different one.

**5. Verify the result**

Check the run's verdict, then check the code the agents changed:

```bash terminal theme={null}
reliant workflow status 414eee72-c07d-4806-8186-5c7e25f8fb02
git diff --stat && python3 -m unittest
```

```text theme={null}
Execution 414eee72-c07d-4806-8186-5c7e25f8fb02
  Workflow:  plan-build-review
  Status:    COMPLETED
  Outcome:   ✓ SUCCESS
...
 greet.py      | 17 +++++++++++++----
 test_greet.py | 30 +++++++++++++++++++++++++++---
 2 files changed, 40 insertions(+), 7 deletions(-)
Ran 4 tests in 0.001s

OK
```

`Outcome: SUCCESS` means the run ended at `done`, so the reviewer approved. `Status` alone says only that the run finished: a run that ends at `needs_attention` is also `COMPLETED`, with `Outcome: FAILURE`. Here the reviewer approved round 1. Your scenario covers the send-back path.

## What this does not do

* **It does not commit, push or open a pull request.** The changes stay in your working tree for you to review. To publish a branch, add a [`git_publish`](https://docs.reliantlabs.io/reference/nodes#publish-branch) node.
* **The approval is a model's judgment.** The reviewer runs the tests it chooses to run. To make your test command the gate, add a `run` node and route on its `exit_code`, as [Get It Right](https://docs.reliantlabs.io/guides/get-it-right.md) does.
* **Turning off edit tools is not a sandbox.** The reviewer can still change files through the shell. Read the diff before you keep it.

## Troubleshooting

> [accordion] cycle detected: implement -> review -> implement
>
> An edge cannot point back to an earlier node, because a workflow's edges must not form a cycle. `validate` refuses one with `remove one of the edges to break the cycle`. Put the nodes that repeat inside a `type: loop` node and end the loop with its `while` condition, as `build_loop` does above.

> [accordion] no machine has synced this project's workflows yet
>
> The first `reliant workflow run --project-path` on a new folder creates the project before its machine has synced `.reliant/workflows/`. Wait a few seconds and run the same command again. Check that the machine is connected with `reliant daemon list`.

> [accordion] \[scenario-none] the workflow has no scenarios
>
> A warning, not an error. Add a scenario under `.reliant/workflows/<name>/scenarios/`, where `<name>` is the workflow's `name:`, not its file name.

## Next steps

> [card] [Require human approval](https://docs.reliantlabs.io/guides/workflows/require-human-approval.md)
>
> Pause the run for a person before the implementer's work is kept.

> [card] [Test workflows with scenarios](https://docs.reliantlabs.io/guides/workflows/test-workflows-with-scenarios.md)
>
> Cover every trigger and ending before you ship a workflow.

> [card] [Multi-agent patterns](https://docs.reliantlabs.io/workflows/patterns.md)
>
> Parallel agents with join, proposer and critic turns, and a model per role.

> [card] [Get It Right](https://docs.reliantlabs.io/guides/get-it-right.md)
>
> The built-in version of this loop, with lint, test and build gates.


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