Workflow runtime
Learn about the different task runtimes
A runtime determines how your task's code is executed. By default, Airplane executes tasks on
the standard runtime in which code is executed on a server, similar to how you would execute a
script locally. For long-running tasks, Airplane supports the workflow runtime which enables
developers to write orchestration logic as code.
Comparison
The following table compares the two runtimes:
Configuring a runtime is an advanced feature. If you are new to Airplane, start with the
standard runtime.
StandardDefault | WorkflowBeta | |
---|---|---|
General use case | Run scripts on servers | Orchestrate long-running processes |
Execution time | Up to 12 hours | Up to 60 days |
Programming model | Arbitrary | Deterministic and side-effect free |
Resumable | No | ✅ |
Retries | No | ✅ |
Child runs | ✅ | ✅ Up to 1000 child runs |
Prompts | ✅ | ✅ |
Sleep | ✅ | ✅ |
Self-hosting | ✅ | ✅ - Requires the v2 agent. See Self-hosting. |
Configurable timeout | ✅ | (Coming soon) |
Network and file I/O | ✅ | No - See Common invalid operations. |
Language support | JavaScript, Python, Shell, Docker | JavaScript (Python coming soon) |
Configuring a runtime
The workflow runtime is currently in beta, and minor details may change. We'd love to hear any
feedback or requests at hello@airplane.dev.
Tasks have a
runtime
field that defaults to "standard"
. This can be overridden to "workflow"
in your task's configuration:typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6// The line below configures this task to use the workflow runtime:7runtime: "workflow",8},9async () => {10// Add your workflow code here.1112return "Hello, world!";13}14);
javascriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6// The line below configures this task to use the workflow runtime:7runtime: "workflow",8},9async () => {10// Add your workflow code here.1112return "Hello, world!";13}14);
Workflow runtime overview
Unlike the standard runtime, the workflow runtime can arbitrarily pause and resume runs. This
happens automatically whenever a run is waiting for external operations to complete. This offers a
few important benefits over standard runs:
- Workflow runs can execute for much longer—up to 60 days!
- Workflow runs do not consume resources while waiting for operations to complete. Airplane does not charge for compute time on hosted agents, but customers who run self-hosted agents benefit from these resource savings.
- Workflows runs that encounter unexpected errors—such as the underlying server dying—are safely resumed elsewhere without losing any progress.
Pausing and resuming are performed automatically by Airplane. Pausing is not an explicit operation,
but instead implicitly based on the operations that a workflow can perform (e.g. waiting for a child
run to complete or for a prompt to be submitted).
The workflow runtime offers these features by running code in a restricted environment where the
only external operations allowed are those exposed by the Airplane SDK (e.g.
executing tasks and built-ins,
creating prompts, etc.). The runtime maintains a history of the output returned by
each of these operations and—if the workflow is paused—can resume the workflow by replaying those
outputs instead of re-performing the operation.
This is a concept known as the durable programming and popularized by products like
Azure Durable Functions
and Temporal. Under the hood, the workflow runtime runs on Temporal, allowing
you to write durable programs with all the benefits of Airplane Tasks.
In order to resume workflow runs, the runtime requires that runs are:
- Deterministic: When run with the same execution history, a workflow must always perform the same operations in the same order.
- Side-effect free: Workflows cannot perform side-effects (e.g. directly performing API requests), otherwise those side-effects would get executed every time the workflow is resumed. Instead, workflows should use the Airplane SDK perform side-effects, such as executing other tasks.
We discuss common sources of non-determinism and side-effects below.
Limitations
As mentioned earlier, there are a few restrictions on runs within the workflow runtime:
- Runs must be deterministic.
- Runs must be side-effect free.
- The only external operations allowed are those exposed by the Airplane SDK.
For the most part, the runtime mocks out common sources of non-determinism. For example,
Math.random
and the
Date
constructor are both mocked such that they return deterministic values. Other libraries that
generate randomness—such as those that generate random UUIDs—cannot be used.Common sources of side-effects include performing network I/O (e.g. HTTP requests via
fetch
) and file I/O (e.g. trying to
read/write files to disk via the fs
package).Instead, execute a standard-runtime task that performs the desired operation. For example,
instead of directly performing a
fetch
call in a workflow, move the fetch
call to a JS task and
call that (or use the REST built-in).Since the vast majority of Node.js APIs
produce side effects, all Node.js APIs are disabled within workflows. When Airplane builds a task
for the workflow runtime, it will produce an error if it detects that your code is using a Node.js
APIs.
There are a couple of notable exceptions:
- All of the
console
methods, such asconsole.log
, are allowed. - Environment variables can be accessed via
process.env
.
All of the methods exposed by the Airplane SDK—such as executing tasks or built-ins and creating
prompts—are safe to call from within the workflow runtime. In other words, the operations exposed by
the SDK are what allow you your workflow to perform side-effects.
Self-hosting
The workflow runtime requires a sufficiently recent version of the Airplane agents.
To check, open the team settings page and confirm your
agent's version is prefixed by
v2
:
If you are not running
v2
agents, you can upgrade by following the
Self-hosted agents instructions.The Docker agent does not support the
v2
agent format. If you are running
Docker agents and wish to self-host workflows, you will need to deploy one of the other agents.