Skip to main content
Workflows are the production units of Gloo Forge. Every piece of autonomous work — from a two-step email draft to a forty-step compliance audit — runs as a workflow. The workflow engine provides durable orchestration, governance-gated dispatch, human approval checkpoints, and full observability for every run. Forge supports two distinct run types, each suited to different operational models.

​
🔀 Two Run Types

​
Prescriptive Runs

execute a .lobsterX DAG definition. The Convex interpreter walks the graph deterministically. No LLM tokens are spent on orchestration decisions. Use prescriptive runs when:
  • The process is well-understood and repeatable
  • Steps, roles, and handoffs are known in advance
  • Compliance requires a reproducible, auditable execution trail
  • You need fine-grained control over failure handling and approvals

​
Delegated Runs

give an agent a goal and guardrails, then let it operate autonomously. The agent decides what to do, which tools to use, and when to hand off. Forge enforces cost limits, duration limits, handoff limits, and periodic checkpoints. Use delegated runs when:
  • The task requires adaptive reasoning that cannot be pre-scripted
  • The agent needs freedom to explore, iterate, and course-correct
  • You trust the agent within bounded constraints
  • The outcome matters more than the exact sequence of steps

PRESCRIPTIVE VS DELEGATED

Prescriptive.lobsterX DAG
Step AStep B
↓
Step C
↓
Step D

Declared steps, deterministic graph walk, policy-driven failure. No LLM orchestration cost.

DelegatedGoal + Guardrails
”Review the vendor…”
Cost limit: $50Duration: 1 hrHandoffs: 3 maxCheckpoints: 5m

Autonomous agent, bounded authority, adaptive reasoning. Agent decides next actions.

PrescriptiveDelegated
Definition.lobsterX YAML fileGoal string + guardrails object
Execution modelDAG walk with parallel layersAutonomous agent with bounded authority
Orchestration costZero LLM tokensAgent decides next actions
Failure handlingPer-step policies (halt, skip, retry, escalate)Guardrail trips (cost, duration, handoff limit)
Human checkpointsApproval gates in the DAGHandoff requests from agent
CheckpointsAfter every step completionAt configured intervals
Restart supportRestart from any failed stepNot supported
BranchingBranch from any checkpointNot supported

​
🔄 Workflow Lifecycle

Every workflow moves through a defined lifecycle from authoring to completion.

WORKFLOW LIFECYCLE

Author

Write .lobsterX or configure delegated goal.

Steps, roles, policies, contracts

version→
Deploy

Bind roles to agents. Select gateway.

Harden for single-agent or per-role

trigger→
Execute

Convex walks DAG, dispatches through governance gates.

Checkpoints saved after each step

terminal→
Complete

Audit trail finalized. Token costs bubble up.

Replay and analysis ready

​
📋 Workflow Catalog

The platform provides a centralized workflow catalog. Workflow definitions, deployments, and runs are accessible through the Platform API and operator interfaces. From the catalog, operators can:
  • Browse all registered workflow definitions with search and filtering
  • View the .lobsterX source, DAG visualization, role list, and version history
  • Deploy a workflow by creating a deployment with role bindings and gateway selection
  • Harden a workflow with one click — assigns a single capable agent to every role
  • Start a run with runtime arguments from the launch dialog
  • Monitor active and historical runs with real-time step progression

​
Run Status Board

The Runs view provides a real-time status board for all active and recent runs. Each run shows:
ColumnDescription
Statusrunning, completed, failed, cancelled, paused
ProgressSteps completed / total with visual progress bar
Operator Statusnominal, attention, critical — escalation indicator
Current AgentWhich agent is actively executing
Pending ApprovalsCount of steps awaiting human decision
CostAccumulated token cost for the run
DurationWall-clock time since run start

​
📌 Versioning

Workflow definitions are versioned with integer version numbers. Each version is immutable once deployed. 
name: vendor-risk-review
version: 3
Key versioning behaviors:
  • Pin at run start. When a run begins, the .lobsterX YAML is serialized into the workflowRuns document. The run uses this pinned definition for its entire lifetime, even if a newer version is deployed later.
  • Version history. All versions are preserved. Operators can view any version and compare changes.
  • Deployment binding. Each deployment targets a specific workflow version. Upgrading a deployment to a new version does not affect in-flight runs.
  • Sub-workflow versioning. Steps with workflow_ref can pin a specific child version via workflow_version. If omitted, the latest active version is used.
Versioning is integer-based by design. There is no semantic versioning. Increment the version number whenever the step graph, roles, policies, or contracts change.

​
🔗 Role Bindings

Abstract roles in a .lobsterX file are resolved to concrete agents through a three-tier fallback at dispatch time.
1

Deployment role bindings (highest priority)

The deployment configuration maps role names to agent identifiers: { "risk_analyst": "claude-senior-analyst" }. The hardening process writes these bindings automatically, assigning one capable agent to all roles.
2

Embedded agent_id

If the .lobsterX role section includes an agent_id field, it is used directly. This is common when the AI generation pipeline matches agents during workflow creation.
3

Role name as fallback

The role name itself is used as the agent identifier. This is a last resort and typically requires the gateway to have an agent registered with that exact name.
This abstraction means the same .lobsterX file can execute across different environments — staging with lightweight agents, production with specialized agents — by swapping deployment bindings.
Use the Harden action to quickly bind every role to a single general-purpose agent. This is the fastest path to a working deployment when you are iterating on the workflow definition itself. See the Burgundy Dashboard Guide for the operator experience.

​
🚀 Next Steps