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

# 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, other modules start it by name, and Nexus starts it from the System app.

A workflow comes in two forms, both in the module's code:

- **A class.** `Workflow[Parameters]` (`naas_abi_sdk.workflow`, extra `naas-abi-sdk[workflows]`) under the module's `workflows/` folder, with an `async def run(parameters)` method. `abi new workflow` writes one, with a test beside it.
- **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 on other modules. See [Write a durable workflow](/capabilities/build/workflows/write-a-durable-workflow).

The two meet: every workflow class 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 tool, or another module's workflow through a tool of its own.
- **Nexus** starts any durable workflow from System › Jobs (**Run now**), and scripts holding the instance's `ABI_API_KEY` start them at `/api/workflows`.
- **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.
- **Schedules and events** start it through `Cron`, `Every` and `OnEvent` triggers.

The tasks for each are in the table above.

## Key concepts

- **`run(parameters)`.** The class's logic, `async`. It takes the parameters model (`WorkflowParameters`, a Pydantic model) and returns a JSON-serializable value or a Pydantic model.
- **Discovery.** The module finds every `Workflow` subclass under its `workflows/` folder and builds it after `on_initialized`, with `New(module)` or an empty `<Name>WorkflowConfiguration()`. A class it cannot build stops the module from starting, unless it is bound in `on_initialized` with `self.expose_workflow(name, instance)`.
- **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. A module with workflows runs with discovery and declares the `document` service, as `abi new module` writes it.
- **The published class.** `workflow.<slug>` has one step, `run`, one attempt and one run at a time, unless the class sets its triggers and limits with `job = JobSettings(...)`: see [Schedule a workflow](/capabilities/build/workflows/schedule-a-workflow).
- **Calling `run()` directly.** An agent tool 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](/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.
