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

# Pipelines

> Chain multiple agents into DAG workflows with parallel execution and human-in-the-loop approval gates.

Pipelines let you chain multiple agent steps into a workflow. Each step runs an agent with its own prompt, tools, and model — and the output of one step feeds into the next.

<Note>
  Pipelines run inside the daemon. Start the daemon with `lukan daemon start -d` before creating pipelines.
</Note>

## Key Features

* **Visual DAG editor** — drag-and-drop flow editor in the Web/Desktop UI
* **Parallel execution** — steps at the same topological level run concurrently
* **Approval gates** — pause the pipeline and wait for human approval before continuing
* **Per-step configuration** — each step can use a different provider, model, and tool set
* **Multiple triggers** — manual, schedule, webhook, event, or file-watch
* **Live progress** — real-time status updates in the UI
* **Export/Import** — share pipelines as JSON files

## Creating a Pipeline

1. Open the Web or Desktop UI
2. Go to **Pipelines** in the sidebar
3. Click **+** to create a new pipeline
4. Set a name, description, and trigger type
5. In the flow editor, click **+ step** to add agent steps
6. Drag handles between steps to create connections
7. Click the **3-dot menu** on each step to configure prompt, model, and tools

## Step Types

### Agent Step

The default step type. Runs an agent with a prompt and optional tool restrictions.

| Field         | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| **Name**      | Display name for the step                                                |
| **Prompt**    | Instructions for the agent. Use `{{input}}` to reference upstream output |
| **Provider**  | LLM provider override (optional)                                         |
| **Model**     | Model override (optional)                                                |
| **Tools**     | Restrict which tools the agent can use (optional)                        |
| **Timeout**   | Max execution time in seconds (default: 120)                             |
| **Max Turns** | Max LLM turns (default: 10)                                              |
| **On Error**  | `stop` (default), `skip`, or `retry:N`                                   |

### Approval Gate

A special step that pauses execution and waits for human approval. See [Approval Gates](#approval-gates) below.

## Connections & Conditions

Connections define the flow between steps. Each connection can have an optional condition:

| Condition    | Description                                                |
| ------------ | ---------------------------------------------------------- |
| **Always**   | Always follow this connection (default)                    |
| **Contains** | Follow if the previous step's output contains a string     |
| **Matches**  | Follow if the previous step's output matches a regex       |
| **Status**   | Follow based on the previous step's status (success/error) |

## Triggers

| Trigger        | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| **Manual**     | Run from the UI or API                                               |
| **Schedule**   | Cron expression or interval (`every:5m`, `every:1h`, `*/10 * * * *`) |
| **Webhook**    | `POST /api/pipelines/{id}/webhook?secret=TOKEN`                      |
| **Event**      | Triggered when a matching system event arrives                       |
| **File Watch** | Triggered when a file or directory changes                           |

## Approval Gates

Approval gates add human-in-the-loop control to your pipelines. When execution reaches an approval step, the pipeline pauses and waits for someone to approve or reject before continuing.

### How It Works

1. Pipeline executes agent steps normally
2. When an approval gate is reached, the step turns **purple** in the UI
3. A notification is sent to the configured channel (optional)
4. The pipeline polls every 2 seconds waiting for a decision
5. On **approve** — the pipeline continues with the next step, passing through the original context
6. On **reject** — the pipeline stops with an error
7. On **timeout** — the pipeline stops with a timeout error

### Approval Sources

You can approve or reject from multiple sources:

| Source       | How                                                       |
| ------------ | --------------------------------------------------------- |
| **UI**       | Click the Approve/Reject buttons on the purple node       |
| **Web Page** | Open `http://your-server/approve/{id}` in a browser       |
| **WhatsApp** | Reply "yes" or "no" to the notification message           |
| **Telegram** | Reply "yes" or "no" to the notification message           |
| **Slack**    | Reply "yes" or "no" in the DM or channel                  |
| **Discord**  | Reply "yes" or "no" in the DM or channel                  |
| **Gmail**    | Click the approval link in the email                      |
| **API**      | `POST /api/pipelines/approvals/{id}/approve` or `/reject` |

### Configuring an Approval Gate

In the flow editor, edit a step and change **Step Type** to **Approval Gate**:

| Field                    | Description                                                           |
| ------------------------ | --------------------------------------------------------------------- |
| **Approval Message**     | Message shown to the approver. Use `{{input}}` for upstream context   |
| **Notification Channel** | Plugin to notify (WhatsApp, Telegram, Slack, Discord, Gmail, or none) |
| **Channel/User ID**      | Where to send the notification                                        |
| **Timeout**              | Seconds to wait before timing out (default: 3600 = 1 hour)            |

### Approval Keywords

When responding via a messaging channel, these keywords are recognized:

| Approve                                       | Reject                                            |
| --------------------------------------------- | ------------------------------------------------- |
| `yes`, `y`, `approve`, `approved`, `ok`, `si` | `no`, `n`, `reject`, `rejected`, `deny`, `denied` |

### Channel ID Reference

| Plugin       | ID Format                                      | How to Find                                   |
| ------------ | ---------------------------------------------- | --------------------------------------------- |
| **WhatsApp** | `5491155551234@s.whatsapp.net` or group JID    | Check plugin logs for `channelId`             |
| **Telegram** | `-1001234567890` (groups) or `123456789` (DM)  | Send a message, check logs                    |
| **Slack**    | `C01ABC123` (channel) or `U01XYZ789` (user DM) | Right-click channel → View Details            |
| **Discord**  | `1234567890123456` (channel or user)           | Right-click → Copy ID (enable Developer Mode) |
| **Gmail**    | `user@example.com`                             | Email address of the approver                 |

## REST API

### Trigger a Pipeline

```bash theme={null}
curl -X POST http://localhost:3000/api/pipelines/{id}/trigger \
  -H "Content-Type: application/json" \
  -d '{"input": "optional trigger input"}'
```

### Cancel a Running Pipeline

```bash theme={null}
curl -X POST http://localhost:3000/api/pipelines/{id}/cancel
```

### List Pending Approvals

```bash theme={null}
curl http://localhost:3000/api/pipelines/approvals/pending
```

### Approve / Reject

```bash theme={null}
# Approve
curl -X POST http://localhost:3000/api/pipelines/approvals/{id}/approve \
  -H "Content-Type: application/json" \
  -d '{"comment": "Looks good"}'

# Reject
curl -X POST http://localhost:3000/api/pipelines/approvals/{id}/reject \
  -H "Content-Type: application/json" \
  -d '{"comment": "Not ready"}'
```

### Get Pipeline Runs

```bash theme={null}
curl http://localhost:3000/api/pipelines/{id}
```

## Export & Import

Export a pipeline as JSON from the flow editor toolbar (download icon). Import by clicking the upload icon in the pipelines sidebar.

The exported JSON includes steps, connections, trigger configuration, and per-step settings — but not run history.