---
question: What is a workflow, and where can it run?
kind: overview
---

> **You are reading the v2.x docs (engine modules). New projects use v3.** [Read this page in v3](/capabilities/build/workflows/overview) · [Migrate from 2.x to 3.0](/capabilities/upgrade/migrate-to-3)

# Workflows

A workflow is business logic in a module: one named intent, such as "summarize an entity" or "reward long-term customers". It reads the knowledge graph, calls integrations, and returns structured data. Agents use it as tools, the engine API serves it over HTTP, and, on ABI 3.x in a NATS project, Nexus and other modules start it by name.

A workflow comes in two forms. Both live in the module's code:

- **A class.** `Workflow[Parameters]` from `naas_abi_core.workflow`, under the module's `workflows/` folder, with a plain `run(parameters)` method. `abi new workflow` writes one. It works on ABI 2.x and 3.x.
- **A durable workflow.** A method of the module decorated with `@workflow`: a job with a typed input and output whose steps are checkpointed, so a retried run skips the steps that finished. It can fan out and start child runs of other modules' workflows. ABI 3.x only, in a NATS project. See [Write a durable workflow](/v2/capabilities/build/workflows/write-a-durable-workflow).

The two meet on ABI 3.x in a NATS project: every workflow class whose `run()` is implemented and takes a parameters model is also published as the durable workflow `workflow.<slug>`, where the slug is the class name in snake case (`CustomersWorkflow` is `workflow.customers_workflow`). It can then be started, scheduled, monitored and cancelled like a `@workflow`.

<!-- matrix -->

## Where a workflow runs

- **Agents** call a class through its tools, or another module's workflow through a tool of their own.
- **The engine API** runs a class at `POST /workflows/<slug>`, on ABI 2.x and 3.x.
- **Nexus** starts any durable workflow from System › Jobs (**Run now**), and scripts holding the engine's key start them at `/api/workflows` (ABI 3.x, NATS).
- **Other modules**, and the module itself, start a durable workflow by name with `get_workflow(name)`, or as a child run with `ctx.call` inside another workflow (ABI 3.x, NATS).
- **Schedules and events** start it through `Cron`, `Every` and `OnEvent` triggers (ABI 3.x, NATS). On ABI 2.x, and on 3.x without NATS, a schedule is a [Dagster](/v2/capabilities/build/applications/dagster) orchestration (legacy on 3.x).

The tasks for each are in the table above.

## Which line has what

| | ABI 2.x | ABI 3.x without NATS | ABI 3.x with NATS |
|---|---|---|---|
| Workflow class, agent tools, `POST /workflows/<slug>` | Yes | Yes | Yes |
| `@workflow`, `workflow.<slug>`, System › Jobs, `/api/workflows` | No | No | Yes |
| Schedules | Dagster | Dagster (legacy) | `Cron`, `Every`, `OnEvent` |

## Key concepts

- **`run(parameters)`.** The class's logic. It takes the parameters model (`WorkflowParameters`, a Pydantic model) and returns a dict, a list of dicts or a Pydantic model.
- **Discovery.** At startup the engine loads every `Workflow` subclass under the module's `workflows/` folder and builds it with `New()` or an empty `<Name>WorkflowConfiguration()`. A class whose configuration needs arguments is skipped (logged at debug level).
- **Durable runs.** A started run is recorded with its status, input, steps and output, and shows in System › Jobs. It is delivered at least once, so a workflow must be safe to repeat. Durable runs need ABI 3.x with NATS, the default of `abi new project` on 3.x.
- **The published class.** `workflow.<slug>` has one step, `run`, one attempt and one run at a time. `nats.workflows.bridge: false` turns the publishing off, and a class whose `run` is `async` is not published.
- **Calling `run()` directly.** An agent tool, the kernel route or your own code calls the class in process: that call is not a durable run, is not recorded and is not limited.
- **Workflow or pipeline.** A workflow returns data. A [pipeline](/v2/capabilities/build/knowledge-graph/creating-a-pipeline) returns RDF for the knowledge graph, and is published as `pipeline.<slug>` the same way.

The Nexus Marketplace shows a **Workflow Templates** tile marked Coming soon.