> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-hive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow triggers and steps reference

> Every Hive workflow trigger and step type: what it does, its settings, defaults and limits, and how steps pass values to each other.

Every workflow has exactly one trigger and at least one step after it. This page lists each type
the builder offers. The name in `code` is the type as it appears in a
[workflow exported from Hive](/developers/workflow-export-format).

## Triggers

The trigger is the first card on the canvas and has the type `trigger`. Select it, then choose
what starts the workflow.

| Trigger | Kind | What starts a run | Needs |
| - | - | - | - |
| **Manual** | `manual` | Someone presses Run. | Nothing else to configure. |
| **In-app form** | `form` | A signed-in teammate submits the form. | A form. |
| **Public form** | `public_form` | Anyone with the form's link submits it, once the workflow is live. | A form. |
| **Schedule** | `schedule` | The deployed workflow runs on an hourly, daily or weekly cadence. | A schedule. |

<Note>
  There is no webhook trigger. To start a workflow from another system, publish a
  [public form](/workflows/schedules-and-forms#public-forms) and post to it through the
  [public form API](/developers/public-form-api).
</Note>

### Forms

A form trigger (`form` or `public_form`) needs a title and 1 to 20 fields.

| Setting | Limit |
| - | - |
| Title | 1-120 characters |
| Description | Up to 500 characters |
| **Confirmation message (optional)** | Public forms only. Plain text, up to 500 characters. |
| Fields | 1-20, each with a unique key |

Each field has a **label** (up to 120 characters), a **key** (lower\_snake\_case, up to 60
characters), an optional **placeholder** (up to 160 characters), a **required** switch, and a type:

| Field type | Accepts |
| - | - |
| **Short text** | Up to 500 characters |
| **Long text** | Up to 5,000 characters |
| **Number** | Any finite number |
| **Email** | A valid address, up to 200 characters |
| **Checkbox** | Ticked or not. A required checkbox must be ticked. |

A field's key is set when the field is created and does not change when you rename its label, so
earlier submissions stay readable. Submissions with unknown fields are rejected.

The public form's confirmation message defaults to "Form submitted! Your response has been
recorded." `{{ }}` placeholders are not filled in, so it cannot repeat answers or anything the
workflow produced. It appears as soon as the submission is accepted, before the workflow has run,
so do not promise an outcome in it.

An in-app form has no shareable link. Once the workflow is deployed, a teammate who can run it
selects **Fill in form** in the builder header (or on the workflow's row in **All workflows**),
fills in the live release's form and selects **Submit form**. The run starts as that teammate.

### Schedule

| Setting | Values |
| - | - |
| Frequency | `hourly`, `daily` or `weekly` |
| Minute | 0-59 (default 0) |
| Hour | 0-23 (default 0). Ignored for hourly. |
| Days of week | Weekly only: one or more days |

A Schedule trigger runs on this cadence in UTC once the workflow is deployed. Saved schedules on the
**Scheduled** tab take over from it and can use any timezone; see
[Schedules and public forms](/workflows/schedules-and-forms#schedules).

## Passing values between steps

A step can read the trigger's input and any earlier step's output:

* In text such as prompts and messages, write a placeholder like `{{trigger.email}}` or
  `{{invoice_lookup.total}}`. Prompt templates are up to 4,000 characters.
* In a rule condition, a loop or a wait, enter a bare dotted path such as `invoice_lookup.total`.

Paths start with the step's id. Inside a loop, the item alias you choose (for example
`{{item.name}}`) names the current item. Under an agent's prompt, an AI condition, an Output value
and a Create PDF title and body, **Insert a value from an earlier step** lists what the steps
before it produce, so you can add a placeholder without typing its path.

## Steps at a glance

| Step | Type | What it does |
| - | - | - |
| **Hive agent** | `agent` | Runs a prompt on an AI model and passes its answer on. |
| **Saved agent** | `saved_agent` | Runs a pinned Agent Studio agent and passes its validated result on. |
| **Parallel agents** | `parallel_agents` | Runs 2 to 5 agents at the same time. |
| **Condition** | `condition` | Compares a value, or asks an AI model, and takes the matching path. |
| **Loop** | `loop` | Runs the steps inside it once per item in a list. |
| **Wait** | `wait` | Pauses for a time, or until a value exists. |
| **Action** | `action` | Records an internal note, or acts in a connected app. |
| **Output** | `output` | Names a value and keeps it in the run's result. |
| **Web search** | `web_search` | Searches the web and passes the findings on. |
| **Generate image** | `image` | Generates an image and saves it to the Library. |
| **Create PDF** | `document` | Builds a PDF from earlier output and saves it to the Library. |

Every step except the trigger also has a title (up to 120 characters), a note (up to 500), a team
comment (up to 500), an **On error** policy, and can be deactivated: a deactivated step stays on the
canvas and is skipped when the workflow runs.

## Hive agent

An `agent` step sends its prompt to a model and passes the answer on.

| Setting | Default | Limit |
| - | - | - |
| Prompt | "Summarise the input from the previous step and return the result." | 4,000 characters |
| **Model** | **Workspace default** | A pinned model must be one your workspace can run |
| **Tools** | None | Up to 20. Web search where your deployment provides it. |
| **Read-only data sources** | None | Up to 20 connected accounts, read only |
| **Structured output** | Off (text answer) | Named fields; string enums up to 100 values |
| **Max Steps** | 3 | 1-25, capped by your deployment |

Later steps read `{{<id>.text}}` for a text answer, or each named field when structured output is
on. If no AI model is configured, a workflow with an agent step cannot be deployed or run, and the
card says why.

## Saved agent

A `saved_agent` step runs a deployed [Agent Studio](/agents/agent-studio) revision, pinned with its
exact output contract. You map its inputs (up to 50), sources, context and accounts (up to 20 each)
explicitly, from an earlier value or a fixed selection. The person running the workflow must still
be allowed to run that agent and must use their **own** sources and accounts. Later steps read the
validated result, for example `{{meeting.output.data.summary}}`.

<Warning>
  Saved agent steps are refused where your workspace does not have live saved agents enabled, and a
  workflow started by a public form cannot run one. The workflow assistant never adds this step.
</Warning>

## Parallel agents

A `parallel_agents` step runs two to five agents at once, for work that splits into independent
parts. Each agent has a **key** (up to 40 characters, unique in the step, not `combined`) and an
optional title, and is one of two kinds:

* **Inline instructions** — the same settings as a Hive agent: prompt, model, tools, structured
  output and read-only data sources. A step reads at most 12 connected accounts across its
  inline agents.
* **A saved Studio agent** — pick a deployed [Agent Studio](/agents/agent-studio) revision in
  **Saved Studio agent for Agent N** and map its inputs, sources, context and accounts exactly as
  in a [Saved agent](#saved-agent) step. **Use inline instructions** switches the agent back.
  The saved agent rules apply here too: the workspace must have live saved agents enabled, and a
  workflow started by a public form cannot run one.

| Read | Gives |
| - | - |
| `{{research.market.text}}` | The text answer of the agent keyed `market` |
| `{{research.market.size}}` | One field, when that agent has structured output |
| `{{research.combined}}` | Every answer as one Markdown document, a `##` heading per agent |

The step succeeds only when every agent succeeds. Each agent retries on its own and keeps its own
run receipt, whether it is inline or saved. A new step starts with two inline agents, `agent_1`
and `agent_2`.

## Condition

A `condition` step sends the run down one of its paths. Choose a **Condition type**. A new
Condition starts as **AI**, with **Force AI to select a path** switched on and two empty
conditions.

### Rule

Pick a value path, an operator and (except for **exists**) a value to compare with.

| Operator | Meaning |
| - | - |
| `equals` / `not_equals` | Same or different value |
| `contains` | The text contains a string |
| `exists` | The value is present (no comparison value) |
| `gt`, `gte`, `lt`, `lte` | Greater / less than (or equal) |

Connect the **true** and **false** branches to the steps each should run.

### AI

Write 1 to 10 conditions in plain text, with `{{ }}` placeholders. The first reads **Go down this
path if**, and each after it **Else if**.

| Setting | Default | Effect |
| - | - | - |
| **Model** | **Workspace default** | As for a Hive agent |
| **Allow multiple conditions** | Off | Off: only the first condition that holds runs. On: every one that holds runs. |
| **Force AI to select a path** | On | On: no Else path, and the step fails if the model picks none. Off: an **Else** path runs when nothing holds. |

Later steps read the chosen paths as `{{route.routes}}` and the model's reason as
`{{route.reason}}`. Each run of an AI condition is one model call, billed like an agent step. A
deploy is refused while a condition is blank. A condition can never be set to continue after a
failure.

<Note>
  An AI condition is not a security check: what it reads, including what a visitor types into a
  public form, can steer its choice. Steps after it still pass every approval and safety check.
</Note>

## Loop

A `loop` runs the steps inside it once for each item of a list.

| Setting | Default for a new step | Limit |
| - | - | - |
| List (value path) | `input.items` | A dotted path |
| Item alias | `item` | Up to 40 characters |
| **Max iterations** | 50 | 1-500 |
| **Collect outputs** | Off | |
| **Parallel execution** | Off | Up to 5 items at once |

A finished loop exposes `{{each.items}}`, `{{each.count}}` and `{{each.truncated}}` (whether the
list was longer than **Max iterations**), where `each` is the loop's id. With **Collect outputs**
on it also exposes `{{each.iterations}}`: one entry per item, in list order. A deploy is refused if
a later step reads `iterations` from a loop that does not collect them.

With **Parallel execution**, items finish in any order. If one fails and nothing continues past it,
running items finish their current step, no new item starts, and the loop fails. A parallel loop
cannot contain a Wait, a Parallel agents step or another parallel loop.

A loop multiplies its body's cost: see [runs and errors](/workflows/runs-and-errors#the-500-step-run-budget).

## Wait

| Mode | Settings | Limit |
| - | - | - |
| For a duration | Seconds (a new step waits 5 seconds) | 1 second to 30 days |
| **Until a value appears** | A value path, optional timeout | Timeout defaults to 24 hours, up to 30 days |

A wait on a value re-checks every 60 seconds and fails the step with "Workflow wait condition timed
out" if the value never arrives. A test run does not wait out a duration.

## Action

An `action` step does one of two things:

* **Internal notification** records a note in Hive's audit trail. Nothing is sent outside Hive. A
  new step posts "The workflow reached this step." to the `general` channel.
* **Integrations** steps act through a connected app: posting a message, creating a record,
  sending an email. They appear in the **Integrations** section of **Add step** for apps your
  workspace has connected, and each needs an account to act through.

An Integrations step lists every field its app takes. Required fields are marked, list fields take
one entry per line, and each value can be text or a placeholder. A run, a deploy and an import all
refuse a step with an empty required field or a field the app does not take.

Your role limits which actions you can put in a workflow you deploy:

| Role | Can deploy |
| - | - |
| **Analyst** | No actions |
| **Operator** | Messages, email, internal notes, pausing campaigns, connected-app actions |
| **Department lead** | Also retrying charges and issuing refunds |
| **Admin** / **Owner** | Also revoking access |

In a production run, every action passes your workspace's
[approval and safety policy](/approvals/review-and-approve). An action that needs approval is
recorded as **Awaiting approval** and the run carries on: the workflow does not pause for the
decision. Writes to a connected app always go to human approval.

## Output

An `output` step gives a value a **key** (up to 80 characters; a new step uses `result`) and the
text or placeholder it holds. The run's result collects every output by key. Two outputs cannot
share a key, and an output cannot be set to continue after a failure.

## Web search and Generate image

These two steps can build their text from the run automatically.

A **Web search** step (`web_search`) searches either:

* **Automatic** (default) — built from the run when the step runs; or
* **Fixed** — a query you type, up to 1,000 characters, searched exactly as written. A fixed query
  cannot contain `{{ }}` placeholders.

It passes on `query`, `text` and `citations` (each with a title and URL).

A **Generate image** step (`image`) uses a prompt that is either **Automatic** (the default for a
new step) or **Manual** (up to 4,000 characters, placeholders allowed). Choose a size:
`1024x1024` (default), `1536x1024` or `1024x1536`.

On **Automatic**, Hive joins the text output of the steps directly before this one, without their
field names: up to 1,000 characters for a search and 4,000 for an image prompt. The text is copied
as it is, not rewritten by a model. The first step inside a loop reads the current item. If none of
those steps produced text, the step fails rather than searching for, or drawing, nothing. The
step's panel says how many steps it reads from.

A Generate image step saves the picture to the root of your [Library](/library/library), named
after its prompt; a test run saves one too. Later steps read `{{<id>.url}}`, `name`, `width` and
`height`. Both steps run only where your deployment has them configured; otherwise the builder says
so and a deploy is refused.

## Create PDF

A `document` step turns Markdown into a PDF and saves it to the Library.

| Setting | Default | Limit |
| - | - | - |
| **Title** | "Workflow report" | 200 characters; the file name and first heading |
| **Body** | | Markdown, 4,000 characters, placeholders allowed |
| **Folder** | **Library** (top level) | Knowledge Base folders are not offered |

Later steps link the file with `{{report.url}}` and name it with `{{report.name}}`. A test run
saves its PDF too, marked as a test. PDFs use standard fonts, so characters outside Western
European alphabets print as `?`.

## On error

Every step except the trigger has an **On error** choice:

| Choice | What happens |
| - | - |
| **Default (up to 3 attempts, then stop)** | Agents, AI conditions, actions, web searches and images retry a transient failure up to 3 attempts; other steps stop at the first failure. |
| **Stop workflow** | Stop at the first failure. |
| **Retry once, then stop** | Two attempts in total. |
| **Continue with empty output** | Carry on without this step's output. |

A refusal — not permitted for your role, not funded, or an account that must be connected first —
always stops the run, whatever this says. See [Runs and errors](/workflows/runs-and-errors) for
retries and budgets.

## Related

<CardGroup cols={2}>
  <Card title="Build a workflow" icon="hammer" href="/workflows/build-a-workflow">
    Start from a brief, a template or a blank draft.
  </Card>

  <Card title="Test and deploy" icon="rocket" href="/workflows/test-and-deploy">
    Try a draft safely, then release it.
  </Card>

  <Card title="Runs and errors" icon="list-check" href="/workflows/runs-and-errors">
    Follow runs, retries and the step budget.
  </Card>

  <Card title="Limits reference" icon="gauge" href="/developers/limits-reference">
    Every limit in one table.
  </Card>
</CardGroup>