Workflow User Guide

Guide navigation map

When onboarding a new team, start with Quickstart to build the first functioning graph quickly, then use this guide as the operating baseline for how workflows should be designed, validated, and promoted. After that, move to Use Case Patterns to select a concrete workflow shape, then review Execution Model and Edges & Data Flow so route behavior is deterministic under failure conditions. Use Capabilities and Features for platform-level tradeoffs and Foundation and Future for strategic design posture.

Who this guide is for

This guide is intentionally cross-functional. Engineers use it to build and maintain graph logic. Operators use it to run workflows and handle incidents. Business-system owners and governance stakeholders use it to inspect branch behavior, approvals, and accountability. The goal is one shared language for control boundaries so technical and non-technical owners are reviewing the same runtime model.

Purpose of this guide

The purpose is to make workflow behavior predictable at scale. That includes deterministic routing, explicit activation and slot boundaries, legal/consent checks where needed, and practical account/billing operations that remain stable while workflows evolve. If a team follows this guide, they should be able to move from pilot to production without relying on hidden assumptions.

Account, auth, and billing operations

Treat account and billing setup as part of production readiness, not as an afterthought. Start with Sign Up, then continue through Account settings, Pricing, and Terms and policy pages so onboarding, consent handling, and runtime controls stay aligned.

In practice, the minimum stable baseline is: create the account with required legal and beta acknowledgments, confirm sign-in and recovery paths, enable 2FA and backup codes, validate billing ownership before trial conversion, and verify that policy-sensitive workflow branches re-check acceptance state before execution. Teams that do this upfront avoid most account, billing, and consent-related surprises later.

For incident readiness, run a routine recovery drill through /reset-password, confirm ownership of reset channels, and verify that session revocation and credential rotation can be completed quickly. For subscription changes, confirm cancellation authority and export critical artifacts before downgrades or closure events.

Build sequence (recommended)

1. Define the workflow contract in one sentence

Write a single sentence that states:

• what enters the workflow
• what decisions are made
• what exits the workflow
• what side effects are permitted

If this sentence is unclear, the graph will usually become unclear and difficult to operate.

2. Design the entry path first

Before building advanced branches, verify a deterministic start path exists:

• input source node has real payloads
• starting node is in Ready state (required for run start)
• first downstream node can become eligible
• no accidental Activated/Delay gating blocks initial progression
• path preconditions (schema, optional fields, acceptance state) are explicit

3. Place core nodes before edge-case branches

Start with a minimum path:

Input/Buffer -> Processing -> Decision (if needed) -> Writer

Add retries, escalations, and approval paths only after the base route executes reliably.

4. Wire slots deliberately with a slot map

Do not rely on memory. Use a quick mapping record per edge:

• source output slot
• target input slot
• expected shape
• fallback behavior if value is missing

5. Add activation edges for release control

If a node should not execute immediately on data arrival, use:

1. Activated flag
2. activation edge from a gate/approval node

This is especially important for Writer/API side effects and compliance-sensitive actions.

Flag quick reference for build reviews:

• Optional (O, blue): configured per input slot. Slot can be empty without blocking execution.
• Activated: configured per node. Node still requires activation signal even when data is present.
• Keep (K, green): configured per input slot in general; for Buffer nodes, Keep applies across all slots when selected.
• Delay: configured per node. Execution is deferred by graph steps/cycles (not wall-clock seconds).

Activation control rule:

• Configure Activated and activation edges together on release-gated branches.

For deeper implementation guidance and failure patterns, see Crucial Workflow Mechanics.

6. Validate with realistic payload sets

Test with payload classes, not a single happy path:

• missing optional fields
• malformed JSON fields
• out-of-range values
• model low-confidence responses
• stale acceptance or policy state

7. Add bounded recovery behavior

Every retry branch must have an upper bound and deterministic fallback.

Typical pattern:

• Decision pass -> continue
• Decision fail -> retry
• max reached -> fallback/quarantine/escalation

8. Add governance and acceptance checks where needed

For workflows with policy-sensitive writes:

• validate legal/policy acceptance state before write branches
• route missing/stale acceptance to a re-acknowledgment branch
• retain acceptance version and timestamp references in run metadata

Role-based operating model

Engineering owner responsibilities

1. Maintain deterministic branch logic and schema contracts.
2. Keep retries bounded and side-effect routes idempotent where possible.
3. Version workflow changes with clear run-impact notes.
4. Validate branch behavior under dependency-failure scenarios.

Operations owner responsibilities

1. Monitor run health and branch-level failure distribution.
2. Own escalation paths for blocked queues and fallback branches.
3. Track run and cost trends after each workflow revision.
4. Coordinate incident retrospectives using run evidence.

Business and policy owner responsibilities

1. Review approval rules for customer-impacting actions.
2. Confirm acceptance/consent requirements remain current.
3. Validate communication and remediation outcomes for sensitive workflows.
4. Approve policy-class changes before production rollout.

Deterministic release checklist

Design readiness

• workflow contract is clear and reviewable in one sentence
• external write points are explicitly identified
• risk classes are defined before branch implementation

Validation readiness

• representative payload suites exist for each branch class
• loops have max iteration bounds and termination fallbacks
• optional slots are blocking unless deliberately optional

Production readiness

• high-impact writes are behind approval-release controls
• acceptance and policy checks are enforced at runtime
• rollback criteria and owner on-call paths are documented

Scale readiness

• reusable subflows have explicit input/output contracts
• change review uses export + diff practices
• run and cost analytics are reviewed on a recurring cadence

Full platform setup by view/tab

Network View (authoring tab)

1. Model the directed graph with explicit branch outcomes.
2. Configure node variants, slot contracts, and flags (Optional, Activated, Keep, Delay).
3. Add schemas where downstream decisions or writes require typed guarantees.
4. Insert activation edges for review/release control before sensitive actions.

Automate View (operations tab)

1. Configure schedules and event triggers for production run entry points.
2. Set iteration variables and run parameters for batch processing.
3. Define escalation ownership for failed or blocked branches.
4. Monitor run history and replay outcomes before scaling volume.

Apps View (user-facing tab)

1. Define input forms, validation behavior, and expected user flow.
2. Route uncertain/high-risk outcomes into review paths.
3. Keep outbound side effects behind explicit approval branches.
4. Preserve clear result and status feedback for end users.

MCP View (tooling tab)

1. Attach only the MCP servers optional for each workflow context.
2. Scope tool availability by branch where possible.
3. Add fallback behavior for unavailable tools.
4. Keep invocation traces in run evidence for auditability.

Schemas View (contract tab)

1. Create schemas using one of three builders: Raw JSON, Visual builder, or From JSON inference.
2. Mark optional fields and constraints before attaching to Conversation nodes.
3. Validate schema changes against Decision and Writer branches before production promotion.
4. Keep schema versions documented in release notes for audit and rollback clarity.

Functions View (tool contract tab)

1. Define function name, description, typed parameters, and return shape.
2. Keep function scope narrow and deterministic.
3. Attach only optional functions to Conversation nodes per branch.
4. Monitor function failure rates and update contracts with version discipline.

Marketplace View (reuse tab)

1. Import reusable workflow assets and review their input/output contracts.
2. Assign ownership for each imported asset before production use.
3. Validate imported assets under your own policies, not only publisher defaults.
4. Track asset version adoption and deprecate stale dependencies deliberately.

Settings View (control tab)

1. Configure runtime defaults and workspace conventions.
2. Store API key references and OAuth mapping names without hardcoding in nodes.
3. Review sensitive setting changes during release approvals.
4. Keep environment-specific settings isolated by workspace.

Integrations View (connectivity tab)

1. Configure MCP endpoints, OAuth integrations, and custom API key references.
2. Attach integration references to Reader/Writer/Conversation/Code nodes explicitly.
3. Route auth and dependency failures to deterministic fallback branches.
4. Use least-privilege scopes and rotate credentials on schedule.

Workspace View (organization tab)

1. Define ownership boundaries by team, domain, or environment.
2. Keep naming and promotion standards consistent across workflows.
3. Use export + Git diff workflows for change review before promotion.
4. Maintain explicit rollback owner and incident-response ownership paths.

Files and permissions tab

1. Register file/directory handles needed for Reader/Writer behavior.
2. Verify path conventions for local download (./) versus directory writes.
3. Standardize naming/versioning conventions for reusable modules.
4. Review permissions, ownership, and incident contacts regularly.

Portability, versioning, and model swapping

JSON and bundle/zip export patterns

• use JSON exports for diff-friendly workflow reviews
• use bundle/zip exports for multi-asset migration and handoff
• keep export metadata tied to release notes and ownership records

Git diff and release governance

1. Export workflow artifacts before each production promotion.
2. Review graph diffs alongside code/policy changes in Git.
3. Require approval for branch/control changes affecting high-impact actions.
4. Keep rollback references for the previous known-good artifact version.

Local-first and typed runtime posture

• local-first workflow operation supports tighter control over sensitive contexts
• typed schemas and slot contracts reduce hidden drift
• JSON graph artifacts keep workflow behavior portable and inspectable
• Rust/WASM runtime design supports predictable execution characteristics

Swapping models without rewriting workflows

1. Keep branch and policy logic in graph structure, not provider-specific prompt hacks.
2. Enforce schema contracts so output shape remains stable across model changes.
3. Swap model/provider settings in Conversation configuration.
4. Re-validate quality, latency, and cost by route before broad rollout.

Slot system quick reference

Important reminders:

• Keyboard 0 means bulk connect, not slot 0.
• $ references are 1-based.
• Code APIs are 0-based.

Writer path rules to memorize

When a file "did not download," this is usually a path-prefix issue.

Workflow type guides

Agentic workflow

Use when model reasoning is central.

Core path:

Reader -> Conversation -> Decision(risk/confidence) -> (Auto/Review/Reject) -> Writer

Must-have controls:

• tool allowlists by branch
• deterministic risk classification rules
• explicit human review for medium/high-risk actions

API integration workflow

Use when synchronizing external systems.

Core path:

Reader(API) -> Code(normalize) -> Decision(validate/policy) -> Writer(API)

Must-have controls:

• strict schema/contract checks
• idempotency or replay strategy
• bounded retry and dead-letter handling

Data quality workflow

Use when downstream analytics or operations depend on reliable data.

Core path:

Reader -> Data/Code -> Decision(Quality) -> (Publish/Quarantine/Retry)

Must-have controls:

• measurable quality thresholds
• clear failure classes
• replay-ready quarantine evidence

Acceptance-aware workflow

Use when terms, policy, or consent state changes execution eligibility.

Core path:

Input(Action) -> Decision(acceptance validity) -> (Proceed/Re-ack/Block)

Must-have controls:

• acceptance event logging (version + timestamp + actor)
• stale acceptance detection
• block behavior for missing or invalid acceptance

Common pitfalls and deterministic fixes

Pitfall: workflow does not start

Cause:

• no eligible entry node

Fix:

• ensure first path is Ready/executable with real input data and no hidden precondition failures

Pitfall: node executes with partial context

Cause:

• Optional overused on critical inputs

Fix:

• keep critical slots blocking by default; make optionality explicit and intentional

Pitfall: sensitive write happens too early

Cause:

• direct data edge without release control

Fix:

• add Activated + activation edge from approval branch

Pitfall: wrong data in prompts/templates

Cause:

• slot-index confusion across UI and code

Fix:

• validate slot map and sample data at every critical hop

Pitfall: loops never converge

Cause:

• retry branch unbounded

Fix:

• enforce decision max limits and explicit fallback termination

Pitfall: policy drift causes inconsistent behavior

Cause:

• business/legal logic embedded ad hoc in code

Fix:

• centralize policy classes in Decision nodes and version policy logic with release notes

Production hardening checklist

1. Entry path starts deterministically with representative payloads.
2. All external writes are gated by explicit branch conditions.
3. Retry branches are bounded and observable.
4. Schema-driven validation executes before sensitive downstream writes.
5. Failure branches are testable and have clear owners.
6. Acceptance/policy checks are enforced where workflow risk requires them.
7. Run traces are reviewed before broad rollout.
8. Rollback triggers and escalation paths are documented.

April 2026 rollout templates

Teams using this guide in April 2026 commonly launch:

1. Incident response orchestrations with explicit approval release before customer-facing communication.
2. Finance exception workflows with deterministic reconciliation and adjustment review.
3. Support automations where low-risk actions auto-complete and high-risk actions escalate.
4. Trust-and-safety triage paths combining model classification with human decision nodes.
5. Acceptance-aware flows that block sensitive actions until current policy acknowledgment exists.

Next documents

• Use Case Patterns
• Execution Model
• Edges & Data Flow
• Writer Node
• Runtime, Planes, and Rules