Overview

A workflow is TypeScript that runs without a person watching it. You write the code, push it, and register it. Urai then keeps the record of every run and the rules that each run obeys: which secrets the code can read, which hosts it can reach, whether it can call a model, and whose identity it acts as.

Workflows run on the uraiJS sandbox, the same runtime that runs your libraries and tools. Deployment is a git push.

When to use a workflow

Urai gives you three ways to run your own code. They differ in who starts the work and how much of it there is.

Use	When
Agent	A person is in the conversation and the answer comes back to them.
Library or tool	One function call does the work.
Workflow	Something fires, several things must happen in order, and each one can fail on its own.

A workflow is the right shape when a webhook arrives at 03:00 and four things must happen before anyone wakes up.

How a run works

A run is durable. Urai keeps its state in the database, so a run survives a restart and can wait for days without holding anything open.

The execution model has four rules:

1. The run() method of your workflow class is the coordinator. It runs again from the top on every tick.
2. A step that has already finished returns its stored result. It does not run again.
3. The first step that has not finished suspends the tick. Urai dispatches that step, stores the result, and starts the next tick.
4. Nothing runs and nothing is held open between ticks.

This is why the coordinator must be deterministic. Every network call, model call, clock read, and random value belongs inside a step.

The parts

Part	What it is
Definition	The workflow code you pushed. One uraiJS project can hold several workflow classes.
Workflow	A registered definition plus its envelope. The envelope holds the allowed secrets, the network allowlist, chat access, and the run-as identity.
Trigger	A webhook that starts runs of one workflow. It carries a URL, a secret, and default arguments.
Run	One execution. It carries the input, the status, the result, and every step.
Approval	A point where the run stops and waits for a person.

The envelope belongs to the workflow, not to the trigger. Several triggers can start the same workflow, and none of them can widen what it may do.

Where to go next

1. Write a workflow. Scaffold the project, write the steps, run it on your machine, and push it.
2. Register and secure it. Decide what a run is allowed to do.
3. Triggers and runs. Start runs from a webhook or from your own code, and watch them.
4. Human approvals. Stop a run until someone says yes.

The Reference page holds every endpoint, object, and CLI command in one place.