# Workflow

> > This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to regenerate.

# Workflow

> This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to regenerate.

Creates a workflow — a state-machine definition (named states, allowed transitions, guards, and per-state automation) that tasks live in. State and transition dispatch references (`agent_id`, `orchestration_id`, `tool_id` inside an `on_enter` block) accept `{ "ref": "LogicalId" }` expressions to point at agents, orchestrations or tools declared in the same template, so a workflow plus the agents and tools that service its states can deploy as one stack. Mirrors the workflows REST contract (`states`, `transitions`, `payload_schema`).

## Syntax

```yaml
type: workflow
properties:
  name: String
  description: String
  states: Object[]
  transitions: Object[]
  payload_schema: Object
```

## Output

The physical resource ID is the **public ID** of the created resource. Reference it from other resources with a `ref` expression:

```yaml
      some_field:
        ref: MyWorkflow
```

## Properties

**`name`**

Human-readable name for the workflow, unique within the project

_Required_: Yes
_Type_: String

---

**`description`**

Optional description of what the workflow models

_Required_: No
_Type_: String
_Nullable_: Yes

---

**`states`**

Named states. Exactly one must be `initial: true`; any number may be `terminal: true`. A `kind: human` state parks the task until a transition fires; an `on_enter` block dispatches one agent generation or orchestration run on entry.

_Required_: Yes
_Type_: Array of Object

---

**`transitions`**

Named, directional moves between states. Each has `from` (source states) and `to` (one target), an optional JSON Logic `guard`, and an optional `requires_approval` gate.

_Required_: Yes
_Type_: Array of Object

---

**`payload_schema`**

Optional JSON Schema describing a task's payload

_Required_: No
_Type_: Object
_Nullable_: Yes

---