Natural Language Workflow Copilot: Describe the Pipeline, Confirm the Spend

Describe a pipeline in plain language — “scrape the product URL, write three ad variants, best-of-three seed frames with review ≥ 7, animate the winner, add music, approval before final render” — and the workflow copilot turns that into a WorkflowSpec diff you approve. It is not a generic chatbot: it is a compiler-in-the-loop agent on POST /api/v1/workflows/agent, paired with the AI workflow builder dock.

Human-confirmed spend (load-bearing)

Two rules separate copilot from reckless agents:

1. Invalid specs never reach the canvas — the route re-validates server-side before streaming the spec event (R-35).
2. propose_run never holds credits — it validates inputs against saved head and renders AgentRunCard with a fresh quote from kernel-run-quote.ts (same path as submit). Only your Run click triggers hold + wave execution.

Authoring is free; runs are the billed unit (D-12). The copilot’s system prompt encodes run etiquette — never claim a run started.

Tool loop: catalog → draft → validate → emit

Up to twelve SSE turns with tools such as:

• read_block_catalog — typed blocks, combinators, prices
• validate_spec / emit_spec — compiler diagnostics, repair loop
• search_hub, list_model_assets, list_byok_providers (names only)
• estimate_run, list_runs, get_run, propose_run

Platform tools are org-scoped with tenancy asserts and truncated text — injection-hardened system prompt. Events: text, tool, spec, run_proposal, error, done, plus : ping heartbeats every 15s.

Workflow copilot — describe a pipeline and review the assembled graph.

Editor UX: change sets, not silent edits

AgentDock renders streamed markdown, tool activity, and a change set — added/removed/changed nodes. You apply or discard; the canvas never mutates without confirmation.

History lists Neon conversations for this workflow + recent chats; New chat archives old threads. Describe-it on /workflows/new binds conversation to the created spec before navigate. Legacy localStorage transcripts migrate once.

Comfy import can prefill copilot input with “not imported” report lines — still human-send (import post).

Quality and cost guidance in prompts

Registry key kernel.compiler.system (guide mode) steers the agent to:

• Interview before build when shape/cost is ambiguous
• Recommend retryUntil, bestOfN, approvalGate patterns with cost impact
• Never invent credit numbers — use estimate_run

Repair prompts use kernel.compiler.repair on validate failures.

Deep dives: Quality contracts, Best of N, Approval gates.

draft_workflow for Cursor and Claude

External agents call draft_workflow MCP — same loop core, no persistence, returns compiles, spec, diagnostics, estimated_credits. Pair with ?tools=builder mode (agent-driven workflows).

Published workflows expose run_hub_workflow / estimate_workflow by slug — copilot inside the editor is for authoring; MCP slug run is for operations.

When copilot vs manual canvas

Situation	Prefer
Greenfield pipeline, unfamiliar blocks	Copilot interview → validate
Surgical wire change on large template	Manual + spec panel
Import report gaps	Copilot prefill from import
Compliance-critical structure	Manual + explicit approvalGate nodes

Where to go next

• Docs: Workflow copilot, Building workflows
• What is an AI workflow?
• Workflow platform field guide
• Open builder: /ai-workflow-builder

SSE reliability and heartbeats

Long tool phases (catalog read, validate repair loops) emit : ping every 15s so proxies do not drop the stream. Clients should treat error events as terminal for that turn; done resets for the next user message. AgentDock surfaces tool start/ok/error rows — operators can screenshot tool feeds when filing bugs.

Tenancy and injection posture

Platform tools truncate text and assert org tenancy on every list/search. list_byok_providers returns names and status only — never secrets. System prompt treats tool output as data, not instructions — standard LLM injection hardening for Hub search results embedded in replies.

describe-it on /workflows/new

Creating via natural language binds Neon conversation to the new spec id before editor navigation — history follows the workflow, not the session URL. Comfy import residue prefills copilot input via sessionStorage consume-once — still requires human Send (import ComfyUI).

Registry tuning

Operators may override kernel.compiler.system and kernel.compiler.repair in Prompt Registry at /admin#prompts — guide mode steers quality-pattern recommendations without code deploy. Document internal overrides in runbooks; public blog assumes shipped defaults.

Change set apply conflicts

Applying copilot change sets on dirty canvas merges with optimistic lock — save-first when If-Match version conflicts. AgentRunCard quote path requires saved head — dirty canvas triggers save-before-estimate in UI.

Platform tool caps

List tools cap results and truncate strings — copilot may ask you to narrow Hub search. Large block catalog reads are chunked in tool loop — expect multi-turn interviews for complex pipelines (music video + approval + Best of N per scene).

draft_workflow vs in-editor agent

draft_workflow MCP returns spec without persisting — useful in CI generating starter graphs. In-editor agent persists conversations and binds to spec id — choose surface based on whether you need Neon history (agent MCP builder).

Field notes

Copilot interviews reduce bad publishes — ask it to estimate before propose_run when stakeholders ask ‘how much?’ Estimates use the same envelope as submit; memo reduces actuals after first successful run. When copilot proposes quality contracts, accept change set then visually inspect Map nesting — LLMs occasionally over-nest retryUntil inside bestOfN inside Map, exploding envelopes. Manual trim after apply is normal.

Platform links worth bookmarking

The AI workflow builder landing orients new authors; /workflows/new is the authenticated entry. Published runners live at /w/{slug} with JSON Schema exposed on GET /api/v1/w/{slug}. Hub discovery is /hub. Kernel contracts are unauthenticated at GET /api/v1/openapi.json and GET /api/v1/workflow-spec-schema. Docs cluster: workflows overview, building workflows, running workflows, publishing and earning. Comfy transpile honesty: /comfyui and import ComfyUI workflows. API integrators: workflows as API endpoints and agent-driven MCP builder. Next step for this topic: open /workflows/new and apply the pattern from natural language workflow copilot, then publish to /hub when the run is stable.

Glossary (quick)

WorkflowSpec — canonical IR JSON. Compile gate — validate before run/publish. Open royalty — 10% to creator on foreign settled platform credits. Premium — creator-priced runs with 80/20 success split. Memoization — content-addressed skip for unchanged blocks. approvalGate — human pause with webhook. bestOfN — parallel candidates, scoreBy winner. Lineage — fork/remix parent attribution. Slug run — execute published workflow by Hub slug without chat orchestrator.

Accessibility and language

Copilot accepts plain-language constraints — ‘no readable text in frames’ aligns with platform text protocol when downstream blocks honor review calibration. Still validate in run output; copilot does not replace review_image blocks. Non-English briefs work when blocks support multilingual prompts — publish moderation still scans spec text language-agnostically.

Takeaways

• SSE agent with validate_spec before emit_spec — invalid graphs never apply silently.
• propose_run is side-effect-free; Run button holds credits.
• Neon stores author-private conversation drafts per workflow.
• Shared quote path with submit via kernel-run-quote.ts.
• draft_workflow MCP exposes drafting without persistence for external agents.
• Comfy import can prefill copilot with unsupported-node lists — human Send required.
• Registry keys kernel.compiler.system and kernel.compiler.repair tune behavior.
• Recommend quality contracts with cost awareness — never invent credit numbers.
• Open /ai-workflow-builder Assistant dock to try on a template.

One-line reminder

Published workflows at /w/{slug} use the same kernel runtime as private editor runs — gates, memoization, Open 10% royalty, and Premium 80/20 splits do not change because the runner discovered the workflow from chat, Hub, or API. The AI workflow builder remains the authoritative place to add or move approvalGate, bestOfN, retryUntil, style locks, covers, and showcase-worthy outputs before you publish.