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

# WakerFlow Workflow Orchestration

> Use the WakerFlow multi-agent orchestration engine to break complex tasks into multiple Phases, assign them to different Wakers, and flexibly control the execution order with orchestration primitives.

WakerFlow is a multi-agent orchestration engine that breaks down complex AI automation tasks into multiple phases and steps, completed collaboratively by different Wakers. When a task requires multi-perspective, multi-step processing, WakerFlow lets you break the task into multiple phases (Phase), assign the most suitable Waker to each step, and flexibly control the execution order.

## WakerFlow List Page

Click "WakerFlow" in the left navigation bar to enter the list page:

* **List area**: Shows all created WakerFlows, with each record displaying the name, description, latest run status, and time.
* **New button**: Click to enter the creation flow.
* **Search and filter**: Supports searching by name and filtering by status.

## Creating a WakerFlow

Click "New WakerFlow" to enter the creation flow. QoderWake supports natural-language-driven creation:

<Steps>
  <Step title="Click New">
    Click the "New" button on the list page.
  </Step>

  <Step title="Describe the flow">
    In the creation interface that pops up, describe the flow you want in natural language. For example: "Every morning at 9, have the security auditor check yesterday's code changes, then have the fix engineer resolve any issues found, and finally have the test engineer verify."
  </Step>

  <Step title="Generate the script">
    The system automatically generates an orchestration script containing multiple phases.
  </Step>

  <Step title="Enter Studio">
    After generation, you automatically enter the Studio interface, where you can further adjust and refine it.
  </Step>
</Steps>

You can also choose to start from a blank template and write the script manually.

**Comparison of creation methods:**

| Method                    | Operation                                                                   | Use case                              |
| ------------------------- | --------------------------------------------------------------------------- | ------------------------------------- |
| Natural language creation | Enter a flow description, and the system generates the script automatically | Quick prototyping, simple flows       |
| Blank template            | Write a JavaScript script from scratch                                      | Complex logic, precise control        |
| Template-based            | Select a preset template and modify it                                      | Quick adaptation for common scenarios |

## WakerFlow Studio

WakerFlow Studio provides switching between three function Tabs — WakerFlow, Run History, and Settings — via the top Tab bar.

### Canvas Tab

The default view of the WakerFlow detail page is the Studio canvas:

* **Left canvas area**: Visualizes the workflow structure as a flowchart, containing each Phase and Worker node and the connections between them. You can browse the entire flow by dragging and zooming.
* **Right Chat panel**: Provides a conversation area for interactive debugging with the WakerFlow, where you can modify the flow structure through natural language instructions.
* **Top Tab bar**: Provides switching between three function Tabs — WakerFlow, Run History, and Settings.

Click any node on the canvas, and the right panel displays the node's detailed configuration, including:

* Node type (Phase / Worker / Parallel, etc.).
* Associated Waker information.
* Input and output parameters.
* Execution configuration (timeout, retries, etc.).

### Script Tab

The Script Tab provides a code editor for directly writing and modifying the WakerFlow's JavaScript script:

* **Code editor**: Supports syntax highlighting and autocomplete.
* **Save button**: Click to save after editing.
* **Right Chat panel**: Remains available, so you can edit code and get help through conversation at the same time.

### Run History Tab

The Run History Tab shows all execution history of the WakerFlow:

* **Run list**: Displays each run in reverse chronological order, including the run ID, trigger method, start time, duration, and final status.
* **Status labels**: Pending / Running / Waiting / Completed / Failed / Cancelled.
* **Detail expansion**: Click a run record to view phase progress, the status of each Worker, log output, and time statistics.
* **Human-in-the-loop prompt**: When an `askUser` node is encountered during a run, the input prompt is displayed here.

<Note>
  A running WakerFlow displays the execution status of each node in real time (in progress, completed, waiting, etc.), distinguished by color and icon.
</Note>

### Settings Tab

The Settings Tab manages the global configuration of the WakerFlow:

* **Basic information**: Edit the name and description.
* **Trigger configuration**: Add and manage triggers; each WakerFlow supports up to 5 triggers.
* **Auto-run settings**: Configure whether to run automatically after saving, the timeout, etc.
* **Run parameters**: Define parameters that can be passed in at runtime.

## Orchestration Primitives

WakerFlow is written in JavaScript and provides 6 orchestration primitives:

| Primitive                   | Description                | Purpose                                                |
| --------------------------- | -------------------------- | ------------------------------------------------------ |
| `phase(title, detail?)`     | Declares the current phase | Organizes the logical structure of the workflow        |
| `log(message, level?)`      | Writes a progress message  | Run monitoring; level: info/warn/error/success         |
| `worker(instruction, opts)` | Dispatches a single task   | Assigns a task to a specified Waker to execute         |
| `parallel(tasks, opts?)`    | Barrier concurrency        | All tasks run in parallel and return once all complete |
| `pipeline(tasks, opts?)`    | Pipeline                   | Tasks flow through multiple phases in sequence         |
| `askUser(question)`         | Human-in-the-loop          | Pauses execution and waits for user input              |

**worker example:**

```javascript theme={null}
const result = await worker('Analyze the security risks of this PR', {
  label: 'security-review',
  resolve: { kind: 'waker', wakerId: 'security-auditor-001' }
})
```

**parallel example:**

```javascript theme={null}
const reviews = await parallel([
  () => worker('Review from a security perspective', { resolve: { kind: 'waker', wakerId: 'security-expert' } }),
  () => worker('Review from a performance perspective', { resolve: { kind: 'waker', wakerId: 'perf-expert' } }),
])
```

## Orchestration Tips

* Divide Phases sensibly, with each Phase representing a logically complete stage; 3-5 Phases is ideal.
* Set a meaningful label for each worker to make it easy to track in the run history.
* Use a schema to constrain the worker's return format, ensuring stable downstream processing.
* Add askUser at key steps to request human intervention on failure.
* Get the flow working with simple workers first, then gradually add complexity.