Documentation / Conception / Guides pratiques / Use the AI assistant

Use the AI assistant

The visual editor's ✨ AI assistant panel turns a plain-language instruction into a workflow graph: it calls POST /api/workflows/assist (apps/api/src/server/api.ts, apps/api/src/server/workflow-assist.ts), which asks an LLM for a spec, validates it, and hands back a graph for you to review — it never writes to disk. This page covers using that panel, both to draft a workflow from scratch and to revise one already open. It assumes you know the dataflow model and can already read/write the DSL by hand — see Your first workflow and Workflow DSL if not — and that you know your way around the rest of the editor; see Use the visual editor.

Prerequisites

  • The API-proxy process needs a configured LLM provider: ASSIST_PROVIDER (default anthropic) and ASSIST_MODEL (default claude-sonnet-4-5), plus that provider's API key (e.g. ANTHROPIC_API_KEY). There's no startup check — an unconfigured provider only fails the first time you click generate. See Environment variables.
  • A workflow open in the editor — new or existing.

Generate a new workflow from a description

  1. From the workflow list, click + New to open the editor on a blank spec (a default trigger, no nodes).
  2. In the ✨ AI assistant panel at the top of the left palette, describe the workflow in the textarea — trigger and outcome, in plain language. The editor's own placeholder is a good template: "on receiving a lab result, compute the eGFR and alert if < 30".
  3. Click ✨ Generate / modify.
  4. Wait for Generating… to clear. On success the graph, trigger and name are all replaced with the model's proposal — see Read the result below.

Revise the current graph with a follow-up instruction

The same panel edits instead of replacing from nothing, as long as there's already something in the editor to work from.

  1. Open an existing workflow in edit mode (✎ Edit), or stay in the editor right after a first generation.
  2. Describe the change, not the whole workflow — e.g. "add a guard that only continues when the count is above 5".
  3. Click ✨ Generate / modify again. The request carries the graph currently shown in the editor — including wiring you haven't saved yet — alongside your instruction, so the model edits from where you left off, not from the file on disk.
  4. Review carefully: a successful response replaces the whole graph (nodes, connections, trigger, name, exposed params, inline values). It's not a surgical merge — re-check parts you didn't ask about before saving.

Read the result

  • On success, the flash reads "Workflow proposed by the AI — check the graph, adjust, then save." Nothing is written to the definition store yet — the assistant only returns a spec for the editor to load; save explicitly once you're satisfied (see below).
  • On failure, the flash shows what the endpoint returned:
    • empty instruction (400) — the textarea was blank; type something.
    • a list of validation errors (422, joined with ·) — the model's two attempts both failed schema or dataflow validation (see What gets validated). Rephrase the instruction, simplify it, or make the remaining fix by hand.
    • Assistant indisponible : … (503) — the LLM call itself failed: most commonly Provider « <name> » non configuré (clé API en variable d'environnement manquante). when ASSIST_PROVIDER's key is missing, or a network error/timeout reaching the provider. Fix the environment (see Environment variables) and retry — your instruction text is preserved in the textarea.

If you generated a new workflow, double-check the filename field next to the save button: it was pre-filled by slugifying the original blank spec's name, and generation doesn't refresh it even though it does replace the name field — rename it to match if the model gave the workflow a different name.

What gets validated before you see it

assistWorkflow (apps/api/src/server/workflow-assist.ts) never hands you raw model output:

  1. It prompts the model with a compact digest of the catalog — every node type's ports, every trigger's eventType, registered object types and conversions — plus your instruction and, if present, the graph currently in the editor.
  2. It parses the model's JSON reply against the WorkflowSpec schema, then runs the same static dataflow validation (validateSpec) used by POST /api/workflows/save.
  3. If either check fails, it retries once, telling the model exactly which checks it failed.
  4. If the second attempt still fails, the endpoint returns 422 with those errors instead of a spec — the editor's graph is left untouched.

Because it's the same schema and the same validateSpec, a generated workflow that loads into the editor is exactly as valid as one you saved by hand — see Workflow DSL and Validate a workflow.

Save what you generated

  1. Adjust anything by hand as usual — wire ports, branch with guards and switch, loop with map, etc.
  2. Optionally simulate it (▶ Simulate) against a forged event before trusting it.
  3. Click 💾 Create the workflow (new) or 💾 Save the YAML (existing) — this independently re-validates and writes to the definition store via POST /api/workflows/save.
  • Use the visual editor — the rest of the editor's affordances (palette, save, simulate) this panel lives inside.
  • Your first workflow — write one by hand end to end, to compare against what the assistant proposes.
  • Workflow DSL — the schema the assistant's output (and yours) must conform to.
  • Validate a workflow — the same static checks, run manually or from the CLI.
  • Simulate a workflow — try a generated graph against sample data before saving it.
  • Use agents in a workflow — agent.* nodes run their own LLM call at runtime; this assistant only shapes the graph at authoring time and shares its low-level client, not its behavior.
  • Environment variables — ASSIST_PROVIDER/ASSIST_MODEL and the provider API keys they depend on.
75 documents7 sectionssource : /docs · généré au build