Business workflows
A business workflow is a process drawn on a canvas: steps assigned to roles, people, agent actors or code, decisions with outcomes, triggers that start runs, live animated runs with a reviewable output, and an inbox for the people in the loop. An agent actor on a step is a cortex agent with an execution contract. It does the step, records its output, and the process moves on or waits for a person. Everything about a workflow is data, so a new process, trigger or actor needs no code.
The objects
| Object | What it is |
|---|---|
| Definition | Task, decision and end nodes with edges, drawn on the Workflows canvas. Append-only version history with restore; publish and unpublish are explicit. |
| Step assignment | Exactly one owner per task or decision: a role (any member holding it may act), a person, an agent actor, an endpoint (a code step on the fork), or a sub-process (a reusable definition such as an approval chain). |
| Trigger | A listener that starts a run: an email matching a query, an in-product form (a document upload), a schedule, or a data condition on the project's database. Events are de-duplicated on a key; the triggering document or message lands in the run's context. |
| Run | A live instance. The canvas animates the current node, agent steps post progress lines while they work, and each completed step keeps its output for the steps after it. |
| My Work | The inbox of human steps assigned to the signed-in person or their roles. Completing a task is one form. |
| Actor | An agent whose manifest carries an actor block (which connectors it may use, or judgment only) and an execution contract in its persona: what to produce for each step it owns, the exact output keys, and the degradation rule when a connector is unavailable. |
Where the engine runs
The workflow engine is an endpoint family on the shared platform engine, inherited by every fork. Definitions, runs, tasks and listeners are stored in the project's own relational target database, next to the governed data the steps read, and follow the project wherever it is moved or delivered (Deployments and environments). The product reaches the engine through one thin proxy with an action allow-list and server-side identity stamping. A browser never chooses in whose name a step is completed, and an application shared with a viewer gets only the run surface (start, complete, read), never authoring.
How an agent step executes
- A run reaches a step assigned to an actor. The engine files an agent task with the task text, the outcomes it may choose, the triggering event and the outputs of earlier steps.
- A worker claims the task and fetches the actor's manifest. The execution contract says what to produce, the manifest's tools are the fork endpoints the worker may call, and the capabilities say whether it may touch a connector (mail, calendar) or is judgment only.
- The worker grounds its answer in the project's data, posts progress lines the canvas shows on the pulsing node, and completes the task with an outcome from the allowed list and the output keys the contract names. Decision steps require an outcome.
- The process continues. A human gate is the next step being assigned to a role or a person.
Two kinds of worker exist: the agent fleet (headless, for judgment-only steps and steps without a connector) and a local session with connectors. The actor's capabilities decide the routing. An endpoint step that fails three times leaves the run open and visible so a person can act.
Interruptions, crashes and long waits
A run has no in-memory state. Every run is a row in the project's own database holding its copy of the definition graph, the edges fired so far, the accumulated context, the log and a version counter, and every step is a task row with its status, owner and result. Each transition is a database write, so a crash of any platform component leaves every run exactly where it was, and the next component to look at it continues from the rows.
| What is interrupted | What happens |
|---|---|
| A human step, for hours, days or weeks | Nothing expires. The task stays open in My Work and the run stays running with the waiting node highlighted, for as long as it takes. A role assignment lets any member holding the role act, so one absent person does not block the process. A person with access can cancel the run; cancelling closes its open tasks as skipped |
| A code step (an endpoint) fails or the executor crashes mid-step | The failure is written on the task as a progress line and the step is retried on the next sweep, about once a minute. After three failures the run stays open and visible with the errors on the step, for a person to fix the cause and re-run or cancel. A crash between claiming and completing leaves the task claimed by the executor identity, which the next sweep picks up again; idempotency of the endpoint's own side effects is the endpoint author's responsibility |
| An agent step whose worker dies | A claim expires after twenty minutes without completion and the task returns to the queue for another worker. Progress lines already posted stay on the task |
| Two workers complete steps of the same run at once | Advancing a run is a compare-and-swap on the run's version. The second writer re-reads the run and replays its edge, or is told the process advanced concurrently and must retry. A completed task is never completed twice |
| A trigger fires twice for the same event | Events are de-duplicated on a key (a message id, a form submission), so a redelivered email or a repeated poll starts one run |
| The definition changes while runs are open | Each run keeps the graph it started with. A definition with running instances cannot be deleted or restored to an earlier version until they finish or are cancelled |
| A sub-process is cancelled | The parent's step records it and the parent run waits for a person to complete or cancel it |
Nothing is lost on a crash, and nothing is retried silently. Every retry, failure and claim appears on the task and in the run's log, which the canvas and the run's output panel show. What does not exist yet is a due date or reminder on a human step; see Security and operations.
The Workflow Assistant
Every project carries a Workflow Assistant, stamped onto the fork automatically. It designs a process from a plain-language description (steps, decisions, owners, the trigger), explains a running instance, and answers "who is waiting on what" from the run data. It works through tools only, so what it reports about a run is what the engine recorded (Agents and MCP).
When it designs a process it applies these patterns:
- Score with a model or an agent, route the risky outcomes to a human gate and let the rest continue (Models and machine learning).
- Put approvals in a reusable sub-process so every workflow shares one chain.
- Give every decision at least two outcomes, and every task exactly one owner.
- Keep the run's evidence in the outputs: an agent that read data records what it read (a written analysis, a count, a flag that a write happened), so the run view shows the side effects.
Where the safeguards apply
An actor is bounded by its execution contract, which fixes what it must produce and how it degrades, and by the step's outcomes, which fix what it may decide. The human gate after it is the review. The runtime safeguards on Safeguards and correctness (tools-only grounding, the verifier pass, the ledger) apply to an agent's answers in the chat and through the evaluation surface. That surface is also how an actor is tested: an agent test asks the actor the question a step would ask and asserts on the answer, the tool calls and the verdict (Tests and health).
Mapping from graph-engine concepts
| Runtime concept | In cortex |
|---|---|
| Graph of nodes with state | A workflow definition; the run's context and each step's output are the state |
| Tool-calling agent node | A step assigned to an agent actor; its tools are the manifest's endpoints |
| Conditional edge | A decision node with named outcomes; the actor or the person picks one |
| Human in the loop | A step assigned to a role or a person; the My Work inbox |
| Trigger or event source | A listener: email, form, schedule, data condition |
| Sub-graph | A sub-process step |
| Retry and failure policy | Endpoint steps retry three times and then hold the run open for a person |
| Versioning | Append-only definition history with restore |
| Observability | Live canvas, progress lines per step, the run's outputs, the safeguard ledger for agent answers |
A team that already runs an external process engine keeps it and connects it to cortex over MCP (Agents and MCP). A team starting on cortex designs the process on the canvas, or asks the Workflow Assistant to design it, and adds actors by writing manifests.
Asking for a workflow
A "new workflow" card on the Board requests one, filed from "New task" or from a requirement in Docs whose text describes a process with approvals or human gates (Requirements and knowledge). The fleet designs the definition, authors the actors' manifests and any endpoint steps, publishes it, and hands the run surface back with tests for the requirement it satisfies.