Skip to main content

3. Run lifecycle

This page follows one run through the engine. The example is an approval workflow: load a record, have a model summarise it, ask a person to approve, then record the decision. Every workflow follows the same path; only the steps differ.

Registration​

A developer writes the definition as a JSON file and commits it. The build pipeline sends it to the engine's Metadata API. The engine checks it and stores it in Azure SQL under its name and version. This happens once per version, not per run.

Step 1: start​

An application, a person in the UI, a timer, or an incoming message calls the Workflow API: "start engagement_approval with input {engagement_id: 42}". The engine creates a run, gives it an id, and hands it to the interpreter.

Step 2: first system task​

The interpreter reads the definition and looks at the first task. It is a CALL_TOOL task: "get engagement 42". This is a system task, so the engine does it itself. It calls the tool through the gateway, stores the result on the run, and writes a history row.

Step 3: model task​

The next task is LLM_CHAT. The engine sends the record and an instruction text to a model in Foundry and stores the reply.

Step 4: notification task​

The next task is HTTP: post a card to Teams with the summary and the run id. The engine makes the call.

Step 5: human gate​

The next task is HUMAN. The engine records the step as in progress and stops. Nothing runs. Durable Task Scheduler holds the run's position. The run can wait for hours or days without using any compute.

Step 6: decision​

The approver clicks Approve on the card. The Teams bridge calls the Task API: "task gate on run 42 is COMPLETED with output {decision: approve}". The engine wakes the run and continues.

Step 7: branch​

The next task is SWITCH on the decision. The interpreter picks the approve branch, which contains one CALL_TOOL task: "approve engagement 42". The engine calls it.

Step 8: completion​

No tasks remain. The interpreter writes the run's output and status COMPLETED to history. Anyone can read the run, its steps, and every input and output from the API or the UI.

Variant: worker task​

Suppose step 2 were "parse the engagement PDF". Parsing has no API, so it is a worker step type, parse_pdf, implemented by the platform's document worker. The interpreter would put a message on the parse_pdf queue and wait, as in step 5. The document worker, polling that queue, would take the message, parse the PDF, and post the result to the Task API. The run would continue exactly as after step 6.

Variant: failure​

Each task type has retry settings. A failed API call is retried with a delay. A worker that dies mid-task loses its lock and the message returns to the queue. A person who does not answer in time triggers the timeout policy: remind, fail, or keep waiting. If the run fails, the engine can start a named failure workflow, for example one that notifies operators.

Archival​

After the retention period, a daily job moves the run's records from Azure SQL to Blob. The run stays readable through the API.

The following pages describe each part in the same order: definitions, task types, API, interpreter, system tasks, workers, human gates, events, history.