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

# Workflows

> Program-backed, versioned orchestration with durable runs, approvals, signals, callbacks, and bound Noorle resources

A **Workflow** is a published Program that Noorle can run durably and reuse.
The Program source defines the control flow. A Workflow adds bindings, schemas,
immutable versions, activation, and a durable run history around that source.

Every run is pinned to one published version. Noorle records completed effects
and waits so a run can recover after a process restart or deploy without blindly
repeating work that has already been recorded.

<Note>
  Customer Workflows are **Program-backed**. The earlier graph designer and
  Restate-backed customer Workflow runner have been retired. There is no graph
  definition or execution-engine selector on the current Workflow path.
</Note>

## The object model

| Object                | What it owns                                                                    |
| --------------------- | ------------------------------------------------------------------------------- |
| **Draft**             | Mutable intent, Program source, entrypoint, resource bindings, and JSON schemas |
| **Published version** | An immutable, compiled snapshot of the draft and its bound resource identities  |
| **Active version**    | The default published version used when a caller does not request a version     |
| **Run**               | One durable execution, pinned to the version selected when it starts            |
| **Automation**        | A separate trigger that decides when to start the Workflow                      |

The distinction between a Workflow and an Automation is deliberate: the
Workflow says **what** happens; the Automation says **when** it starts.

## When to use one

Use a Workflow when the process should be authored, reviewable, repeatable, and
durable. Typical reasons include:

* a known sequence of capability or Agent calls;
* a human decision in the middle;
* a timer, external signal, or third-party callback;
* a child Workflow whose completion matters to its parent;
* a process that must keep its version and progress across a deploy.

Use an [Agent](/docs/learn/concepts/agents) when the next action should be chosen at
run time from what the model discovers. The two compose: a Program can call a
bound Agent, and an Agent can invoke an attached Workflow as a tool.

An Agent can also author a one-off **procedure**. A procedure uses the same
Program model but is transient, tied to the current turn, and cannot park on a
durable wait. Publish it as a Workflow when it needs reuse, versioning, or
durability.

## Programs and bindings

The Program is Rune source with a public async entrypoint, usually `main`. It
can express ordinary control flow and call only resources explicitly bound to
the draft:

| Binding                                     | Program surface                                  |
| ------------------------------------------- | ------------------------------------------------ |
| Capability — built-in, plugin, or connector | `tools::<capability_handle>::<tool_alias>(args)` |
| Agent                                       | `agents::<agent_handle>(request)`                |
| Knowledge base                              | `knowledge::<knowledge_handle>(query)`           |
| Child Workflow                              | `workflows::<workflow_handle>(input)`            |

Noorle assigns immutable handles from resource identity. Display names remain
for people; renaming a resource does not silently retarget Program source.

Programs do not receive ambient network, filesystem, secret, clock, or random
access. Bind a capability for external work, use a connector for credentialed
APIs, and use the declared Program host functions for time and IDs. Do not put
credentials in Program source.

## From draft to durable run

```mermaid theme={"dark"}
flowchart LR
    D["Draft<br/>intent + source + bindings + schemas"] --> C["Compile and dry-run"]
    C --> P["Publish immutable version"]
    P --> A["Activate a version"]
    A --> R["Start version-pinned runs"]
```

The Portal can generate or patch a draft from intent. Advanced authoring exposes
the Rune source and the exact declarations available from current bindings.
Compile checks the source and bound surface. Dry-run validates sample input and
derives the effect manifest, execution outline, policy, and topology without
dispatching host effects.

Publishing creates a new immutable version; it does not rewrite an older one.
Editing the draft later has no effect on running executions. Activating a
version selects the default for future starts, while an existing run keeps its
original pin.

## Durable waits

Published Workflows can use four durable wait operations:

| Operation                | Resumes when                                        |
| ------------------------ | --------------------------------------------------- |
| `sleep(ms)`              | The recorded timer fires                            |
| `await_approval(prompt)` | An authorized person submits a decision             |
| `wait_for_signal(name)`  | An authenticated caller delivers that named signal  |
| `wait_for_callback(id)`  | A caller posts to the signed, per-wait callback URL |

A run may also wait for a child Workflow. While parked, no Program process has
to remain alive. The durable run record owns the wait, its resolution, and the
next activation.

Approval, signal, and callback waits do not have an implicit timeout. They stay
waiting until resolved or until the run is canceled.

## Where Workflows can start

* Manually from the Portal.
* From an Agent that has the Workflow attached.
* From an MCP gateway that has the Workflow attached.
* From the Management API.
* From a schedule Automation attached to an Agent and an active Workflow.
* From another published Workflow through a child binding.

Workflows expose no generic inbound URL that starts a run. A callback URL only
resumes a particular run already parked on `wait_for_callback`.

## Next

* [Create and run a Workflow](/docs/run/workflows/overview)
* [Author and publish](/docs/run/workflows/node-types)
* [Understand runs and versions](/docs/run/workflows/state-machine)
* [Use approvals and signals](/docs/run/workflows/human-in-the-loop)
* [Resume with callbacks](/docs/run/workflows/webhooks)

***

Next: [WebAssembly Plugins](/docs/learn/concepts/webassembly) — custom logic in a sandbox.