> ## 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.

# Workflow execution

> How a run moves from an authorized trigger through governed node execution, durable waiting and recorded outcomes, and how data flows through each agent dispatch.

A workflow run executes a graph under a recorded identity, input contract, and authority. Convex owns durable coordination. An agent turn can run inline in a Convex action or through a detached driver; procedures have their own execution boundary. Placement changes how work executes, while the run and its recorded outcomes remain in Forge.

## The workflow graph

A workflow is a directed graph of typed nodes joined by edges. It has three parts:

* **The workflow** — its stable identity, owner, description and tags.
* **Published versions** — immutable snapshots. Each publish creates a new version with the next version number; at most one version is active at a time.
* **The draft** — the editable workspace. The Console graph editor, the HTTP API and the Workflow Architect all edit the draft; publishing copies the draft's nodes and edges into a new version.

A production run pins the active version at launch; a test run pins the draft.

**Node identity is explicit.** Every node has a stable logical ID. Publish, reset, fork and snapshot restore keep a node's ID when they copy it within the same workflow, so its run history follows it. A genuinely new node gets a new ID: deleting a node and recreating a lookalike does not inherit the old node's history.

### Node types

| Node | Type value | What it does |
| - | - | - |
| **Agent** | `produce` | Work assigned to an AI agent or a person. An AI agent runs a governed turn; when the assignee is a person, the run waits for their answer through a human task. Output can be validated against a declared schema. Use `produce` when you author graphs through the API. |
| **Router** | `router` | Evaluates conditions — rule-based or model-based — and activates the matching outgoing branches. Runs inline. |
| **Join** | `join` | Gathers outputs from parallel branches. With `all`, it waits for every branch: ungrouped branches merge their fields by name, and branches whose edges share a collect group are gathered into one array named after the group, one element per branch, ordered by branch name. A failed branch in a group fails the join. With `any`, branches are interchangeable alternatives with identical shapes. |
| **Publish** | `publish` | Emits a terminal output — an event, artifact or webhook — and completes its branch. |
| **Procedure** | `procedure` | Runs a pinned procedure version in a sandbox as a model-free, deterministic step. See [Built-in procedures](https://docs.gloo.com/forge/build/built-in-procedures.md). |
| **Notify** | `notify` | Resolves its recipients — the run starter, the workflow owner, a person, an org unit's members or a Slack channel — records one notification per recipient and channel (bell, Slack or email), and completes. Delivery happens afterwards. It fails with `notify_dispatch_failed` when nothing is deliverable or more than 50 recipients resolve. |

### Edges

After a node completes, each outgoing edge is evaluated:

* **Unconditional edges** are always active; the downstream node becomes eligible.
* **Conditional edges** are evaluated against the completed node's output, for example `output.score > 0.8`. Routers are their main users.
* **Error edges** activate only when the upstream node fails, so you can route failure handling.

### Example: a code review pipeline

1. **analyze-code** — Agent node assigned to an AI agent.
2. **severity-check** — Router: high severity goes to human review, low to auto-fix.
3. Parallel branches: **human-review** (Agent node assigned to a person, prompted in Slack) and **auto-fix** (Agent node assigned to a Factory Worker).
4. **merge-results** — Join, waiting for all branches.
5. **post-summary** — Publish to a webhook.

### Concurrency

Before an AI-assigned Agent node is dispatched, it takes a concurrency slot for its agent. The agent definition's maximum concurrency (default `1`) caps how many dispatches of that agent can run at once; slots are taken and released atomically.

## Execution phases

From trigger to recorded outcome

The orchestrator dispatches ready work, waits durably for its results, and classifies the run from recorded execution evidence.

<ol />

## Start a run

A production run pins an immutable published workflow version. A test run references its selected draft. Launch validates declared workflow inputs before execution; a rejected launch does not become a running workflow.

Scheduled triggers are live. The evaluator claims due work, and the fire path re-reads the trigger before launching. Paused, changed, or no-longer-authorized triggers must still pass their current checks. Use [Schedules](https://docs.gloo.com/forge/console/production/workflow-schedules.md) to inspect the trigger and the resulting run; the existence of a schedule alone does not prove a run launched.

Launch authorization and node dispatch authorization are separate boundaries. Permission to start a workflow does not grant every downstream tool or credential.

## Walk the graph

Readiness is evaluated from graph state rather than a fixed list of precomputed layers. Conditions select reachable branches, joins coordinate their declared inputs, and error edges route failure handling. A node that is waiting on an approval, human answer, or detached result is still owned work; waiting does not imply the graph is finished.

The orchestrator resolves declared inputs from upstream outputs before dispatch. File inputs use recorded file bindings. Connection and capability resolution checks the authority for the current dispatch rather than accepting a credential identifier emitted by an agent.

## Govern and wait

| Decision | What happens next |
| - | - |
| Pass | Dispatch continues with its resolved authority. |
| Block | The attempt records refusal evidence; eligible error handling can run. |
| Hold | The owner parks durably on a human task and approval release contract. |

An approved hold authorizes its specific continuation. The resumed owner still performs the operation and records its result. Approval does not prove that an external effect occurred. See [Governance pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md) and [Approval lifecycle](https://docs.gloo.com/forge/run/approvals-and-hitl.md#approval-lifecycle).

## Execute agents and procedures

Agent configuration combines the selected definition, pinned workflow constraints, allowed tools, skills, and current dispatch facts. The turn records its thread so Console can display messages and tool activity.

For a structured agent turn:

1. Stream text with the output contract and the allowed tool set.
2. Parse the final text and validate it against the declared schema.
3. If parsing or validation fails, request structured repair from the same conversation context.
4. Accept only a valid result, then record its output and usage, including repair usage when present.

Repair is a model call; it is not an authorization retry or permission to repeat an external write. A workflow's error handling and retry ownership must be evaluated separately.

For file outputs, the agent uses `file_put` to write and bind the file, then returns the recorded file identifier in its structured output. A filename mentioned in prose is not a workflow file binding.

Inline and detached agents run the same turn logic. The transports own message delivery, tool callbacks, cancellation, and execution placement. See [Data flow end to end](#data-flow-end-to-end).

On validation failure, a person-assigned step re-opens its task. An inline AI agent on a workflow
that uses outcome routing is re-prompted with the validation feedback, at most 5 times per run
attempt, and only when its rejected turn called no tool; otherwise the node fails with a validation
error. A detached agent's rejected output always fails the node. Error edges can route the recovery.
See [Let an agent correct a rejected output](https://docs.gloo.com/forge/build/compose-a-workflow.md#let-an-agent-correct-a-rejected-output).

### Agent memory on workflow nodes

An AI agent on an Agent node remembers across runs when its agent definition turns memory on (`memory.type` set to `session`, `persistent` or `vector`; absent or `none` is off). The same rule applies to inline nodes, detached nodes and debug attempts.

* **Recall.** Before the turn, Forge retrieves up to 5 of the agent's long-term memories (from the run's project, plus memories with no project) and up to 3 facts, and puts them in front of the node prompt under a `## Your memory` heading, within 8,000 characters. When the budget is exceeded, long-term memories are dropped first, then facts. If retrieval fails, the node runs without memory.
* **Proven cases.** An AI-assigned Agent node can set `autoInjectCases` from 0 to 5 (absent or 0 is off). Recall then also searches the knowledge the agent can read for active cases graded `proven`, and adds that many under a `## Proven cases` heading, each with its `[ref:k…]` citation ref. A case the agent cites earns a use and an outcome, like a cited search hit. Cases share the 8,000-character budget and are dropped last. The setting lives on the node, so one agent can use cases in one step and not another. An out-of-range value is refused when the node is saved, and blocks publish with `AUTO_INJECT_CASES_OUT_OF_RANGE`.
* **What was recalled.** A production run records each recalled memory, fact and case per node, so the run inspector shows what the agent saw. Debug attempts recall but record nothing.
* **Record.** When the step completes, Forge extracts the noteworthy facts, decisions and actions from the node's prompt and output (each cut to 4,000 characters) and stores them as the agent's memory. A failed step records one failure episode instead. Person-completed steps, non-Agent nodes and debug attempts record nothing. On a factory run, the factory manager's step memory is recorded too.

### Trusted knowledge inputs

A procedure input may declare `trustedKnowledgeContext: true` with exactly one upstream object
source. This tells dispatch to replace the upstream agent's claimed knowledge context with evidence
recorded by that source node's `knowledge_search` call. The agent's refs, excerpts, scores, and
terminal status are not treated as authority.

For each workflow search, Forge records a server-owned retrieval marker and the exact bounded native
excerpts that were displayed. At dispatch, the resolver selects the newest marker from the source
node's effective, non-superseded completion lineage. The result is one of:

| Status | Meaning |
| - | - |
| `relevant` | One to eight recorded native hits passed every current authority and integrity check. |
| `no_relevant_results` | The authorized search completed without a native hit. |
| `permission_denied` | The requested knowledge scope was denied. This is distinct from an empty search. |
| `invalid` | No trustworthy current marker exists, or recorded evidence no longer passes its fences. |

A partial restart downstream of retrieval keeps the surviving source completion, so it reuses that
completion's recorded terminal and excerpts. Restarting from the retrieval node supersedes the old
completion and requires the new search marker; a new empty, denied, invalid, or relevant terminal
wins. Late or legacy rows cannot revive evidence from a retired attempt.

Relevant context remains fail closed at use time. Forge rechecks the retrieving agent's current
`knowledge:read` authority, run-scoped namespaces, source restrictions, and each case's active grade.
It recomputes native citation refs and rejects the whole context if rows are missing, mixed,
malformed, over the eight-hit limit, moved, retired, deleted, newly restricted, or otherwise
unresolvable. The recorded excerpt remains immutable when source text later changes because it
captures what the retrieval agent actually saw. Federated results stay external and do not become
trusted native context.

For the Freshservice triage workflow, trusted knowledge supplies evidence to the
routing and field-selection procedures. The Freshservice records of the declared Knowledge source
supply allowed values and relationships; they do not supply narrative policy. A separate narrative agent writes the private
summary. The apply procedure then revalidates proposed fields against the same records and
issues at most one combined ticket `PUT` with `single_attempt`; notes and requester replies are
reported as separate effects.

Operators publish this graph only through the governed draft authoring flow after reviewing the
source-owned release graph and confirming the Knowledge source and the Knowledge grants. Repository
fixtures contain no production workflow, source, credential, draft, or version identifiers, and
building or merging them does not install a Freshservice workflow or perform a live ticket write.

## Completion and recovery

Read both run status and handling evidence. On the current execution-evidence contract, a fully covered graph with a handled failure can finish as `completed` with `handlingSummary.disposition: "failure_handled"`. An unresolved failure yields `failed`; cancellation is recorded separately. Older runs without this evidence can retain legacy status semantics. The failed node's details remain useful even when a handler completed successfully.

Do not infer that a provider write failed solely because the observer timed out. Read the recorded attempt, completion, and effect evidence before retrying. Detached execution has its own completion and deadline paths; watchdogs provide recovery for lost or stalled ownership rather than a promise of immediate completion.

## Data flow end to end

Every agent dispatch — not only workflow nodes — follows the same path from trigger to recorded result.

### 1. Trigger and dispatch site

| Trigger | What dispatches the agent |
| - | - |
| Chat message | The channel's bound agent |
| Factory Manager chat | The factory's manager agent |
| Factory Worker task | The worker assigned to the task |
| Copilot run analysis | The copilot agent |
| Workflow Agent node | The node's assigned agent |
| Scheduled workflow | The schedule evaluator launches the run; the orchestrator then dispatches its nodes |

Agents are prepared **per dispatch**, not kept as long-lived instances, so each turn uses the agent's current prompt, skills, tools and constraints. A change to an agent definition takes effect on its next dispatch.

### 2. Composition

The dispatch site composes the agent's configuration from its definition:

1. Load the agent definition. Only `executionModel: "native"` (or no value) composes.
2. Resolve the prompt, including a prompt-library reference when the definition has one, plus any per-call extension.
3. Resolve skills: the agent's permitted skills, intersected with any skills the workflow node requests, within the skill token budget: the node's `maxSkillTokens` hint, else the agent's `constraints.maxSkillTokens`, else 32,000 tokens. An `always` skill's content goes into the system prompt; an `on_demand` skill appears in a menu and is loaded with the `load_skill` tool.
4. Merge the agent's permitted tool sets into one tool set. If an active skill declares allowed tools, any other tool call returns a refusal the model can see and adapt to; `load_skill` is always allowed.
5. Build the language model from the agent's routing tier, or a per-call override.
6. Attach usage recording, so every turn's tokens are attributed to the agent and, for workflows, to the run and step.

For chat, factory and copilot dispatches, composition records an `agent_dispatch_composed` audit event with the resolved skills, tool sets, model and warnings. For workflow nodes, the governance decision records the same capability summary instead.

### 3. Governance on every dispatch

Every dispatch surface runs the Trust Fabric gate sequence before the agent executes — see the [Governance pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md) for the gates. The sequence is fail-fast: one `block` stops execution, `hold` waits for a person, `pass` continues. When a gate blocks, the remaining gates are recorded as skipped rather than omitted, and a gate that does not apply to the dispatch is recorded as not applicable. An agent with no definition is itself a block (`agent_not_found`). Each decision records its disposition, per-gate results, scope constraints and the capabilities composed for the dispatch.

### 4. Agent turn and tool calls

The turn runs in a durable thread — one per workflow node, or one per chat session — and every prompt, tool call, tool result and response is saved for audit. A step cap bounds each turn: 10 model steps for an inline turn, and for a detached turn the agent's `constraints.maxToolCalls`, which defaults to 10. Token deltas stream to the Console as the agent writes.

Each tool call is logged with its status: `started`, `completed`, `failed`, `blocked` or `refused_by_skill_constraint`. A sandbox is a tool, not a layer: only dispatches given `sandbox_action` can reach one. See [Configure a sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md).

### 5. Persist and advance

| Surface | What is recorded after the turn |
| - | - |
| Workflow node | The step's output, cost, status, timing and thread; token attribution to the agent, run and step; the concurrency slot is released and the orchestrator advances. |
| Chat turn | The thread with the response and tool messages; token attribution to the agent and user; the Console updates live; channel and long-term memory when configured. |
| Factory operation | The thread; the task moves forward (for example in progress to in review); progress posts to the factory channel; factory-scoped token attribution. |

### Where to look

| Question | Where it is recorded | Where you see it |
| - | - | - |
| Why was this dispatch allowed, held or blocked? | The governance decision | **Trust Fabric → Decisions** |
| What did the agent have available? | The composition audit event or the decision's capability summary | **Observe → Events**, **Trust Fabric → Decisions** |
| What tools did it call? | The tool execution log and the thread | **Observe → Traces**, the run detail |
| What did it cost? | Token events | **Analytics → Cost**, the step's trace |
| What did it produce? | The step result and execution events | The run detail |

## Read next

* [Run a workflow](https://docs.gloo.com/forge/console/production/workflows)
* [Built-in procedures](https://docs.gloo.com/forge/build/built-in-procedures.md)
* [Governance pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md)
* [Approval lifecycle](https://docs.gloo.com/forge/run/approvals-and-hitl.md#approval-lifecycle)


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