Deployments.ai Docs
Platform

Workflows

Define deterministic multi-step workflows, release them as immutable versions, and run executions with agent, tool, and approval steps.

A workflow is a fixed graph of steps that the platform runs in order: call an agent, call a tool, ask a person to approve, branch on data, or emit a notification. Use a workflow when the order of work must not depend on a model's choices, for example "draft with an agent, wait for approval, then call the tool that publishes."

Lifecycle

ResourceScopeWhat it is
Workflow definitionEnvironmentA mutable draft document. status is active or archived.
Workflow releaseEnvironmentAn immutable copy of the draft with a releaseNumber and a contentHash.
Workflow executionEnvironmentOne run of one release, pinned to its content hash.
Step attemptExecutionOne attempt at one step, with its input, output, and error.
Workflow approvalExecutionA pending decision created by an approval step.

Publishing takes the definition's expectedDefinitionVersion, increments the release number, and stores the exact document with a SHA-256 contentHash. Executions start only from active releases. Starting from an archived release fails with 409 workflow_release_unavailable.

Definition document

{
  "schemaVersion": 1,
  "name": "Publish weekly summary",
  "slug": "publish-weekly-summary",
  "entryStepId": "draft",
  "steps": [
    { "id": "draft", "type": "agent", "agentDeploymentId": "dep_123", "next": "review" },
    {
      "id": "review",
      "type": "approval",
      "prompt": "Publish this summary?",
      "timeoutSeconds": 86400,
      "onApproved": "publish",
      "onRejected": "done",
      "onExpired": "done"
    },
    {
      "id": "publish",
      "type": "tool",
      "agentDeploymentId": "dep_123",
      "toolName": "cms.pages.publish",
      "approvalStepId": "review",
      "next": "done",
      "onFailure": "escalate"
    },
    {
      "id": "escalate",
      "type": "escalation",
      "target": "editors",
      "message": "Publishing failed.",
      "next": "done"
    },
    { "id": "done", "type": "end" }
  ]
}
Step typeFieldsWhat it does
agentagentDeploymentId, input, next, onFailureSubmits a turn to the deployment and waits for the child run.
toolagentDeploymentId, toolName, input, approvalStepId, next, onFailureCalls one tool through the deployment's release and authorization.
approvalprompt, timeoutSeconds, onApproved, onRejected, onExpiredCreates an approval and waits for a decision.
branchcondition, onTrue, onFalsePicks the next step from execution input or an earlier step's output.
notificationchannel, target, message, next, onFailureRecords a workflow-notification.requested event.
escalationtarget, message, next, onFailureRecords a workflow-escalation.requested event.
endoutcomeCompletes the execution with outcome as its output.

Validation rules

RuleLimit
Steps per definition1 to 500
Document size192 KiB
Step IDsUnique. Lowercase, start with a letter, at most 64 characters ([a-z][a-z0-9_-]{0,63}).
prompt, message, target1 to 32,000 characters
timeoutSeconds60 to 2,592,000 (30 days)
GraphentryStepId names a declared step. Every edge names a declared step. No cycles. Every step is reachable from the entry.
Success pathsagent, tool, notification, and escalation steps need next. Only end steps finish successfully.
BranchesA branch can read only the output of a step that can come before it, and never its own.
approvalStepIdNames an approval step that can come before the tool step.

Inputs and conditions

An agent or tool step receives its own input object when it sets one. Otherwise it receives the execution's input. The platform does not template values into input.

A branch condition has a left operand and an operator. The operand reads { "source": "input" } or { "source": "step", "stepId": "..." }, with an optional path of up to 32 keys or array indexes. Operators are exists, truthy, equals, and not-equals. equals and not-equals compare right as canonical JSON.

Step outputs available to branches:

StepOutput
agent{ messageId, runId } of the completed child run
tool{ status, outputSummary, externalOperationId }
approval{ outcome }, which is approved, rejected, or expired
branch{ conditionResult }, which is true or false
notification{ channel, target, emitted: true }
escalation{ target, emitted: true }

How steps run

  • Agent steps submit a turn to the deployment on the workflow channel, with the step input as JSON content and the execution's workspace. The deployment must be running, and its manifest must allow the workflow trigger. The step waits until the child run completes or fails.
  • Tool steps run synchronously through the same release, grant, and tool policy that an agent run of that deployment uses. The tool must be declared in the deployment's release, and the release must allow the workflow trigger. The input must match the tool's input schema. A deny decision fails the step. A require_approval decision fails the step unless approvalStepId names an earlier approval step whose outcome was approved. Tools that return an asynchronous operation, and client-executed tools, fail the step.
  • Approval steps create a workflow approval. Without timeoutSeconds the approval does not expire. An approval that expires follows onExpired.
  • Notification and escalation steps record a semantic event and continue. They do not send messages themselves. Subscribe a webhook endpoint to workflow-notification.requested or workflow-escalation.requested to act on them.

A failed step follows onFailure. Without onFailure, or when an approval expires without onExpired, the execution fails.

Executions

Execution statusMeaning
queued, runningAdvancing to or running a step.
waiting-for-agent, waiting-for-tool, waiting-for-approval, waiting-for-deliveryWaiting on a child run, a tool, a person, or an event step.
completed, failedFinished. output or error is set.
canceling, canceledCancellation requested, then done.

Step attempts move through queued, running, waiting, and then succeeded, failed, or canceled.

Start an execution with an optional input object of up to 64 KiB and an optional workspaceId of an active workspace. Each step output is limited to 64 KiB. An execution fails with workflow_context_too_large when its stored step outputs exceed 192 KiB as JSON.

Cancel with the execution's expectedVersion. Cancellation is final for the workflow. A child run or tool call already in progress can still finish, and the workflow ignores its result.

Permissions

ActionCapability
Read definitions, releases, executions, and step attemptsworkflows:read
Create, update, publish, and archiveworkflows:write
Start and cancel executionsworkflows:execute
Read and resolve workflow approvalsapprovals:read, approvals:write

Use it

  1. Create the definition from a file, then publish it.

    deployments workflow create --definition "$(cat workflow.json)"
    deployments workflow release $WORKFLOW_ID --expected-definition-version 0
  2. Start an execution of the release.

    deployments workflow-execution start --release $WORKFLOW_RELEASE_ID --input '{"week":"2026-40"}'
  3. Follow its progress and approve the pending step.

    deployments workflow-execution show $WORKFLOW_EXECUTION_ID
    deployments workflow-execution steps $WORKFLOW_EXECUTION_ID
    deployments workflow-approval approve $WORKFLOW_APPROVAL_ID --execution $WORKFLOW_EXECUTION_ID

Start an execution from the SDK:

import { createClient, createConfig, startWorkflowExecution } from "@deployments-ai/sdk";

const client = createClient(
  createConfig({
    baseUrl: "https://api.example.com",
    headers: { authorization: `Bearer ${process.env.DEPLOYMENTS_API_KEY}` },
  }),
);

const { data, error } = await startWorkflowExecution({
  client,
  path: { workflowReleaseId: process.env.WORKFLOW_RELEASE_ID! },
  headers: { "idempotency-key": crypto.randomUUID() },
  body: { input: { week: "2026-40" } },
});

Reference

On this page