Introduction

A workflow is a graph of steps you build once in Studio and then run from outside the platform. Where running an agent is a single call to a single agent, a workflow chains several of them together with branching, loops, variables, and — where a decision needs a person — a human approval step.

You build the graph visually in Studio; everything in this section is about the half your integration touches: how a run is started, what it reads as input, when it becomes runnable at all, and what a run in flight looks like from the outside.

The shape of an integration

1. Build and save the graph in Studio (see Building a workflow).
2. Publish it. Until then, nothing outside Studio can run it — see Publishing.
3. Trigger it — from your own code with an API key, from another system with a signed webhook, from a person submitting a hosted form, or on a schedule. See Triggers.
4. Collect the result — synchronously for short runs, or by polling the run id for long ones. See the Workflows API reference.

Runs are durable

A workflow run is not an HTTP request that dies when your connection does. Starting a run creates a durable execution record, identified by an executionId, that keeps going in the background:

• The 30-second synchronous endpoint is a convenience, not a lifetime. If a run exceeds it you get a 504 — but the run keeps executing, and the executionId in that 504 body is how you collect it afterwards. This is deliberately unlike POST /agents/:agentId/run, which cancels its upstream run on timeout.
• Every run appears in Studio's Activity tab with its per-node status, whichever way it was triggered.
• A run that is still queued, running, paused, or awaiting_approval counts as in flight, and in-flight runs are what the concurrency ceiling below counts.

Concurrency ceiling

Each organization has a cap on how many workflow runs can be in flight at once. On the community plan that cap is 10; on the cloud and enterprise plans it is unlimited.

The ceiling is enforced identically on every external trigger — API, webhook, form, and schedule — so a burst on one path cannot starve another. A run rejected by it gets HTTP 429 and a durable record with status concurrency_limit_reached, so the Activity tab can explain what happened. Nothing is billed for it.

What this section does not cover

Authoring the graph itself — the node palette, wiring ports, configuring a node's prompt — is a Studio UI activity, not an API surface, and is not documented here. Building a workflow covers only the parts of that authoring which change what your integration sees.

Where to go next

• Building a workflow — the node types, and how input reaches them.
• Triggers — API, webhook, form, and recurrence.
• Publishing — why an unpublished workflow returns 409, and what a version pin is.
• Human review — what a run parked on an approval looks like.
• Workflows API reference — the endpoints themselves.