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

# Workflows and runs

> How work runs in Forge: workflows you draft and publish as versions, node types, runs and their six statuses, triggers, human tasks, outcomes and files.

A **workflow** is a graph of steps that describes a piece of work. A **run** is one execution of a
published version of that graph. Forge records every step of a run as it happens, so a run can
wait for a person, survive a redeploy, and be inspected after it ends.

## Workflows: draft, publish, version

You edit a workflow as a **draft**. **Publish** turns the draft into a new, immutable **version**
and makes it the version new runs use. Runs already in progress keep the version they started on,
so publishing never changes a run mid-flight. You can test-run a draft before you publish it, and
roll back by activating an earlier version.

Publishing also checks what the version will act as: you must be allowed to use every agent the
graph runs and every company Credential a step names. A publish you are not entitled to is refused
and the draft is left untouched.

A workflow you no longer need can be retired (it stops accepting runs) or deleted. Delete moves it
to **Trash**, where it can be restored for 30 days; only **Delete permanently** removes it and its
versions.

You can build a workflow yourself in the graph builder, or ask the
[Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md) to draft one from a description.

## Node types

Each step in the graph is a node. Forge Console labels the six node types as follows:

| Console label | Stored type | What it does |
| - | - | - |
| Agent | `produce` | Hands the step to a worker. An agent worker is dispatched through Trust Fabric; a person receives the step as a human task. |
| Router | `router` | Chooses the next branch, by rules or by an AI decision between named routes. |
| Join | `join` | Waits for parallel branches and combines their outputs. |
| Procedure | `procedure` | Runs a pinned [procedure](https://docs.gloo.com/forge/concepts/procedures.md): deterministic code in a sandbox, with no model call. |
| Notify | `notify` | Notifies people or Slack channels by bell, Slack or email, and completes. |
| Publish | `publish` | Delivers a final output, such as an event or webhook, and ends its branch. |

In the builder, an Agent node's **Assigned to** field offers **AI**, **Human** and **Role**. When
the step is assigned to a person, the run waits for that person's answer before it continues.

## Runs

A run is pinned to the version it started on (or to the draft, for a test run). It records which
steps ran, in what order, what each produced, what it cost, and the governance decisions made
along the way. A run has one of six statuses:

| Status | Meaning |
| - | - |
| `running` | The run is in progress, including while it waits for a person. |
| `completed` | The run finished. |
| `failed` | The run ended in failure. |
| `cancellation_requested` | Someone asked to cancel the run; it is stopping. |
| `cancelled` | The run was cancelled. |
| `paused` | A delegated run was paused. It cannot be resumed; cancelling still ends it. |

A run starts in `running`; there is no queued status. A run's **execution outcome** is separate from its
status: it explains how execution ended, for example **Completed normally** or **Completed with
handled error**.

To try again after a run ends, rerun it with changed inputs or restart it from an eligible step.
Both create a new attempt; they do not resume the old one.

## Triggers and schedules

A run starts in one of these ways:

* **Manually**, from the workflow in Forge Console.
* **From the API or MCP**, by dispatching the workflow.
* **On a schedule**: a cron expression with a timezone, or a single one-shot time, set on the
  workflow's **Schedule** tab. A schedule does not start a run while its workflow is paused, and a
  retired workflow accepts no new runs.
* **From an inbound event**, such as a call to the workflow's ingress URL or an email route.

Creating or changing a trigger checks your authority against the published version, just as
publishing does. Read [Scheduling and triggers](https://docs.gloo.com/forge/run/scheduling-and-triggers.md) and
[Ingress](https://docs.gloo.com/forge/run/ingress.md).

## Human tasks

When a run reaches an Agent node whose worker is a person, or Trust Fabric holds an action for
approval, Forge creates a [human task](https://docs.gloo.com/forge/run/approvals-and-hitl.md#human-tasks) and waits. It
appears in the assignee's **My Work**; the linked page lists every kind and how each is answered.

## Outcomes

*Outcome* has four meanings in Forge: how a run ended, how its execution got there, a work outcome
that a completed run achieved, and a Trust Fabric decision's disposition. Qualify the word when you
use it. Read [Four meanings of outcome](https://docs.gloo.com/forge/concepts/outcomes.md#four-meanings-of-outcome).

## Delegated work

An agent can hand work to another agent: a sub-agent task, or a consultation in which it asks
another agent a question. Both appear under **Production → Delegated Work**. A delegated run, by
contrast, gives an agent a goal, a budget and a deadline rather than a fixed graph; start one from
**Production → Runs** with **+ Delegated Run**. Delegated work never holds a question for a person:
an agent that needs a person asks through a human task.

## Files

Every Agent step receives two file tools: `file_put` stores a file and returns its file ID, and
`file_get` reads only the files the step is authorized to read. Steps pass file IDs to each other, not file contents. Read
[Files and bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md).

## Cost

Every run records the model usage and cost of its steps, and attributes it to the worker that did
the work. Open a run to see its cost, and see totals under **Analytics → Cost**. Read
[Budgets and cost](https://docs.gloo.com/forge/run/budgets-and-cost.md).

## Where you see it

> [tab] Forge Console
>
> * **Production → Workflows**: the catalog, each workflow's **Graph**, **Versions**, **Runs** and **Schedule** tabs, and the builder.
> * **Production → Runs**: every run, with its graph, timeline, outputs, cost and trust receipt.
> * **Production → My Work**: your open human tasks.
> * **Production → Approvals** and **Production → Delegated Work**.

> [tab] HTTP API
>
> * `GET /api/v3/workflows`, `POST /api/v3/workflows/{workflowId}/publish-draft` and `GET /api/v3/workflows/{workflowId}/versions`
> * `POST /api/v3/workflows/dispatch` to start a run
> * `GET /api/v3/runs`, `GET /api/v3/runs/{runId}` and `POST /api/v3/runs/{runId}/cancel`
> * `POST /api/v3/workflows/{workflowId}/triggers` for a schedule
>
> See the [API reference](https://docs.gloo.com/forge/reference.md).

> [tab] MCP
>
> * `forge_run_workflow_and_wait` starts a run and waits for it.
> * `forge_list_runs`, `forge_get_run` and `forge_cancel_run` inspect and stop runs.
> * `forge_list_my_work` and `forge_handle_human_task` answer human tasks.
> * `forge_ask_workflow_architect` builds or changes a workflow.
>
> See the [Forge MCP server](https://docs.gloo.com/forge/reference/mcp-server.md).

## Related

> [card] [Compose a workflow](https://docs.gloo.com/forge/build/compose-a-workflow.md)
>
> Build a graph, choose node types and publish it.

> [card] [Use the Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md)
>
> Describe the work and review the drafted graph.

> [card] [Workflows in Console](https://docs.gloo.com/forge/console/production/workflows)
>
> Catalog, builder, versions and lifecycle.

> [card] [Runs in Console](https://docs.gloo.com/forge/console/production/runs.md)
>
> Inspect, cancel and rerun runs.

> [card] [Approvals and human tasks](https://docs.gloo.com/forge/run/approvals-and-hitl.md)
>
> How Forge waits for people.

> [card] [Observability](https://docs.gloo.com/forge/run/observability.md)
>
> Watch runs and schedules in production.

See also [Workforce](https://docs.gloo.com/forge/concepts/workforce.md) for who does the work,
[Trust Fabric](https://docs.gloo.com/forge/concepts/trust-fabric.md) for what may run, and
[System architecture](https://docs.gloo.com/forge/architecture/system-overview.md) for how runs execute.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.