What Is an AI Workflow? (And Why Typed Pipelines Beat One-Off Prompts)
An AI workflow is a compiled graph of typed steps — planning, generation, review, assembly — that you can run, memoize, publish to /w/{slug}, and expose as API and MCP. Here is how Wavemaker defines it.
An AI workflow is a durable recipe for media production: not one prompt, but a compiled graph of typed steps that scrape, plan, generate, review, mix, and deliver — with explicit control flow when quality or humans need a say. On Wavemaker, that graph is a WorkflowSpec; the AI workflow builder is where you author it, and the Hub is where published workflows become runnable apps at /w/{slug}.
Workflows vs. chat: frozen structure, predictable cost
New workflow entry: describe, blank canvas, Import from ComfyUI, or remix a template.
Managed chat is ideal when the path should stay flexible: the orchestrator reads your brief and chooses tools each turn. That flexibility has a tradeoff — the exact sequence varies run to run, and cost is harder to cap before work starts.
A workflow inverts the contract:
- Structure is visible. Every block, wire, and combinator is on the canvas (or in the JSON tab). Map fan-out, Best of N selection, Retry Until quality loops, and Approval Gates are first-class nodes — not hidden retry logic.
- Types are enforced. Ports only connect when artifact types match (
image,storyboard,rendered_video, and ten other closed types). The compiler rejects graphs that would fail mid-run. - Money is bounded. Compile computes a cost envelope; submission holds credits to a hard stop factor; settlement charges actual node spend. Unchanged upstream nodes memoize — re-runs after a tweak do not re-bill work that already succeeded.
If you are building something others will run — a template for your team, a productized ad pipeline, an API your agent calls — you want the workflow shape.
The compile gate: nothing runs uncompiled
Every surface shares one compiler: visual save, JSON edit, agent emit_spec, POST /workflows/compile in CI, and publish. The pipeline is:
- Schema parse — Zod validates
specVersion: 1shape. - Inlining (publish mode) — nested subworkflows resolve and inline up to depth three; leftover subworkflow nodes are publish errors.
- Typecheck — port wiring, param ranges, condition paths, map scope (
$item), no forward references (cycles are impossible by construction). - Safety annotation — generative-media blocks land in
moderatedNodeIds; runtime moderation is fail-closed and cannot be opted out in the spec. - Cost envelope — upper-bound credits with documented fan-out assumptions; runs hard-stop at 1.25× the envelope.
If any step fails, you get machine-readable diagnostics — not a partial run that dies on step seven. That is the compile gate: execution starts only on a CompiledWorkflow.
What lives inside a spec
Blocks are version-pinned manifests (generate_image@1, review_image@1, …) with typed inputs/outputs, params, optional binding slots for LoRAs and voices, and adapters that call the same core tools as chat — one media path, no second-quality stack.
Combinators are language features, not hacks:
| Combinator | Role |
|---|---|
| sequence | Ordered steps |
| map | Fan out over a list (e.g., one branch per storyboard scene) |
| retryUntil | Regenerate until a condition on review facts passes (max five attempts) |
| bestOfN | Up to six candidates; highest scoreBy wins |
| branch | Conditional then/else paths |
| approvalGate | Pause for human approve (webhook kernel_run.awaiting_approval) |
Workflow inputs you promote in the spec panel become — simultaneously — the Hub form, POST /api/v1/w/{slug}/runs body fields, and the wf_<slug> MCP tool schema.
Style (WorkflowSpec.style) optionally locks visual medium, look anchor, review calibration, voice persona, music profile, aspect ratio, and up to three style reference images — seeded into the same WorkflowContext fields treatments use, so workflow runs honor style like chat does.
Authoring surfaces, one IR
Three editors, one JSON:
- Visual builder —
/workflows/{id}React Flow canvas, spec panel, run rail, publish modal. Start at /workflows/new or the AI workflow builder landing. - Workflow copilot — SSE agent with compiler-in-the-loop tools; invalid specs never stream to the canvas.
- JSON tab — raw spec with the same diagnostics.
ComfyUI imports are a fourth on-ramp: JSON or PNG metadata transpiles creative intent onto platform blocks; Comfy nodes never execute on Wavemaker (import guide).
Run, memoize, publish
Runs execute in waves — one Inngest step per wave, node completions checkpointed inside the wave. Identical block + params + input hashes hit the org-scoped memo cache (BYOK vs platform key does not change the artifact; retry and Best-of-N attempts ≥2 get instance salt so a rejected image cannot memo-loop).
When ready, publish freezes an immutable version, runs moderation on spec text and sample images, and lists on the Hub. Access mode is Open (forkable, embeddable, 10% royalty on foreign runs from the platform share) or Premium (creator price 1–1,000 credits per run, 80/20 creator/platform split on success only). Details: Publishing and earning.
Public runners see /w/{slug} — input JSON Schema, estimate preview, remix lineage, showcase gallery — without leaking premium graph internals.
When to reach for a workflow
Reach for a workflow when:
- The same pipeline should run fifty times with different inputs (UGC ads, catalog stills, episodic content).
- Quality contracts (
retryUntil,bestOfN) must be explicit and auditable. - Legal or brand policy needs an approvalGate before expensive video steps.
- You want slug-run API, signed webhooks, idempotency keys, or MCP
wf_<slug>for agents.
Stay in chat when the user should steer turn-by-turn with minimal upfront structure.
A concrete mental model: Music Video on the canvas
Open the Music Video template from /workflows/new and you see the pattern most teams want: acquisition and planning blocks at the left, a Map over board.scenes, and inside each scene an enrich → Best of N image → review → animate chain. Nothing here is special-cased — it is the same IR your private spec uses. Swap generate_music for a user-upload binding, insert an approvalGate before compose_scenes, or pin a character LoRA on image.generate; every edit re-runs the compile gate on save.
That template also shows why typed ports matter: you cannot wire a brief port into a video_clip input. The error surfaces in the editor, not after a twenty-minute render. For operators, the same spec can be validated in GitHub Actions via POST /api/v1/workflows/compile before anyone clicks Run.
Builder, Hub, and chat: three launch surfaces
Authoring happens in the builder; distribution happens on the Hub /w/{slug} app page (estimate, form, remix, showcase). A third surface is chat home: pin a published workflow in the composer and Wavemaker can direct-run when the spec has a single primary text input, or open the run form with your prompt prefilled — without sending the request through the video orchestrator. That keeps “run my Hub ad workflow from chat” one click, while full multi-input specs still land on the app page where JSON Schema drives the form.
External integrators meet the same published head via GET /api/v1/w/{slug} and POST /w/{slug}/runs, plus MCP run_hub_workflow and dynamic wf_<slug> tools when builder mode is enabled (MCP builder post).
Where to go next
- Tour the builder: Build an AI Video Pipeline Visually
- Platform docs: Workflows overview, Running workflows
- API shape: Workflows as API endpoints
- Pillar index (September): Workflow platform field guide
Frequently asked questions
- What is an AI workflow in Wavemaker?
- A WorkflowSpec: typed blocks wired by ports, plus optional control flow (Map, Retry Until, Best of N, Branch, Approval Gate). It must compile before it runs, produces artifacts with provenance, and can be published as a Hub app at /w/{slug} with REST and MCP surfaces.
- How is a workflow different from a single chat generation?
- Chat uses a ReAct orchestrator to pick tools turn by turn. A workflow freezes the tool sequence, types, and quality contracts in the graph. Runs are quoted up front, memoize unchanged steps, and settle to actual node costs — better for products, APIs, and repeatability.
- Do I need to draw the graph by hand?
- No. You can describe the pipeline in natural language (workflow copilot), remix a template, import ComfyUI creative intent, or start blank on the visual builder at /ai-workflow-builder.
- What does the compile gate actually block?
- Invalid port types, forward references, publish-mode subworkflow leaks, safety annotation for generative blocks, and a cost envelope ceiling. Nothing executes until compileWorkflow succeeds — same compiler in the editor, CI, and publish.
