Skip to content

Your first workflow

This walks through compiling a workflow on your own web app: record what you do, compile it, replay it, and read the report. It takes about five minutes and makes zero model calls. Web is the quickest substrate to start on; the same record, compile, replay loop drives native Windows, macOS, or Linux applications and RDP or Citrix sessions by choosing a backend.

Here is the loop you are about to run — record once, replay deterministically, and watch the run heal or halt under drift:

Record, compile, and replay a workflow with OpenAdapt

Prerequisites and install

  • Python 3.10-3.12. The engine declares requires-python >=3.10,<3.13. Check yours with python --version (on some systems python3 --version).
  • macOS, Linux, or Windows. This walkthrough selects the Playwright-driven browser capability, so it has no OS-specific steps. Its matching Chromium provisions automatically on the first web action; native, RDP, and Citrix paths do not install it.
  • Use a virtual environment. It keeps the install isolated and avoids the stale-package problems a shared or Conda base environment causes.

Install the CLI for your shell — the quoting around openadapt[browser] differs per shell, and getting it wrong is the most common first failure:

python3 -m venv .venv && source .venv/bin/activate
pip install 'openadapt[browser]'

The quotes matter: unquoted square brackets are glob characters in zsh (no matches found) and can misbehave in bash. Single or double quotes both work here.

py -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install "openadapt[browser]"

PowerShell accepts single or double quotes; double quotes are shown for consistency with cmd.exe.

py -m venv .venv && .venv\Scripts\activate.bat
pip install "openadapt[browser]"

Use double quotes. cmd.exe passes single quotes through literally, so pip install 'openadapt[browser]' fails with an Invalid requirement error that starts with 'openadapt.

The browser walkthrough on this page needs no extra system packages. To later record or replay native Linux applications (--backend linux), install the AT-SPI runtime and build prerequisites first (Debian/Ubuntu):

sudo apt-get install \
  gcc pkg-config python3-dev libcairo2-dev libgirepository-2.0-dev \
  gir1.2-atspi-2.0 libatspi2.0-0
pip install 'openadapt[linux]'

The built-in driver uses X11; Wayland requires an operator-approved XDG portal session.

Or use the installer script from the landing page, which installs uv if needed and sets up a persistent openadapt command:

curl -fsSL https://openadapt.ai/install.sh | sh -s -- browser

No app to record against yet?

You do not need your own target to try the loop. The engine bundles MockMed, a synthetic demo clinic app (fake data only): openadapt flow demo-record --out rec serves it locally and records the canonical triage demo, and openadapt flow replay bundle with no --url serves it again as the replay target. It is a local development fixture, not a production workflow or product outcome — but it is a real, running web app, so every step below works against it unchanged.

1. Record

record --backend web --url opens a headed browser pointed at your app and watches what you do: real clicks, typing, key presses, and scrolls. It writes the same recording format that compile consumes.

openadapt flow record --backend web --url https://your.app --out rec

(Omitting --backend defaults to web with a printed notice; production profiles require it explicitly.)

Perform the task once. When you are done, press Ctrl+C or close the browser window to finish. The recording is written to rec/.

Record a clean demonstration

Do the task the way you want it replayed: one clear path, no dead ends. The compiler treats your demonstration as evidence of intent, so a tidy run compiles into a tidy workflow.

2. Compile

openadapt flow compile rec --out bundle --name my-task

Compilation turns the recording into a workflow bundle: an ordered list of steps, each carrying the evidence needed to re-find its target (a template crop, an OCR label, geometry landmarks — the capability ladder) and postconditions derived from what the demo actually changed on screen. Write-shaped clicks (save, submit, create, delete) are auto-classified as irreversible so they refuse to act on a low-confidence match.

3. Lint

openadapt flow lint bundle

lint reports coverage gaps before you trust the bundle: clicks that act with no identity check, steps that assert nothing, writes that may be under-classified. Each finding carries a severity. It is advice, not a gate. See Write and enforce a policy for the certify gate that refuses an unsafe bundle outright.

A nonzero exit here is expected, not broken

lint exits 1 when any finding reaches error severity — an unarmed or vacuous irreversible step. That is the safety boundary working: it is telling you a write-shaped click would act without a wrong-record guard. Review the findings, then continue to step 4; replay still runs, and the certify gate is where a failing bundle is actually refused. All exit codes are listed in Run outcomes and halt reasons.

4. Replay

openadapt flow replay bundle --url https://your.app

Recorded parameter values are the defaults; override any of them with --param key=value. The run is deterministic and local. On the healthy path it makes zero model calls and finishes in seconds. replay exits 0 on success and 1 on a halt — a halt is the fail-closed refusal to guess, not a crash.

5. Read the report

Each replay writes a timestamped run directory under runs/ containing an illustrated REPORT.md and a machine-readable report.json. The report tells you, per step, which rung of the resolution ladder resolved the target, whether the identity check was armed and what it verified, which postconditions passed, and any heals that were applied. See What you get and Read and audit run reports. Every outcome and halt reason the report can show is defined in Run outcomes and halt reasons.

What is next