AI Assist

Generate a complete workflow from a description, or get intelligent suggestions for the next nodes in an existing workflow.

AI Assist is built into the Agent Builder editor. It understands the current state of your canvas and uses that context to produce relevant results — not generic templates.

---

Opening AI Assist

Click the sparkle (✦) icon in the right action bar of the editor. The AI Assist panel opens on the right side of the canvas. The icon is highlighted in blue when the panel is active.

---

Two modes

Generate

Start from a description. Get a complete, ready-to-run workflow.

Type a plain-English description of the workflow you want to build, then click Generate Workflow. The AI returns a full graph with nodes, edges, and configs. The generated workflow replaces the current canvas.

Example prompts:

• "Classify an incoming support ticket as billing, technical, or general, then route it to the right agent for each category"
• "Retrieve relevant documents from the knowledge base, summarize them with an agent, and output the summary"
• "Loop until the agent's output quality score exceeds 0.8, up to 5 retries"

Canvas replacement

Generate replaces the existing canvas. If your canvas already has nodes, you will see a confirmation dialog before the replacement happens.

A canvas history snapshot is automatically taken before the replacement — use Ctrl+Z (Undo) to revert to the previous canvas if the generated workflow isn't what you wanted. This undo snapshot is in the editor's in-memory history and is separate from the versioning system's persistent snapshots.

What happens after generation:

1. The AI returns a graph (nodes + edges + configs).
2. The editor validates the generated graph (checking expression syntax, empty classify class lists, node count limits) and surfaces any warnings in the toast notification. The graph is still applied — warnings are informational, not blocking.
3. Nodes are automatically laid out on the canvas using BFS depth levels — no manual positioning needed.
4. The graph is saved immediately as a draft.
5. You can then edit any node's config to refine the result.

---

Suggest

Already have a workflow? Get AI suggestions for what to add next.

Describe what you want to add or improve, and the AI returns additional nodes that fit the existing workflow. The suggested nodes are placed to the right of your current graph without overwriting anything.

Example prompts:

• "Add a guardrails check before the final agent"
• "Add a human approval step if the classification confidence is low"
• "Insert a transform node to strip HTML from the input before the agent processes it"

What happens after suggestion:

1. The AI analyses your existing workflow and the prompt.
2. It returns a set of new nodes and edges.
3. New nodes are appended to the right of the existing canvas (offset by the current max X coordinate + 100px).
4. Connect the suggested nodes to your existing graph by drawing edges from the relevant connectors.

---

Switching modes

Use the Generate / Suggest tabs at the top of the AI Assist panel to switch between modes. The text area and button update to match the selected mode.

---

Context passed to the AI

Mode	What the AI sees
Generate	Your text description + the workflow catalog (available node types)
Suggest	Your text description + the full current graph (all nodes, edges, and configs) + the catalog

This means Suggest mode is context-aware — it won't recommend node types you've already used heavily if a different type would fit better, and it can reference specific nodes in your graph by name.

---

API endpoints

AI Assist is powered by two backend endpoints:

POST /api/v1/agent-workflows/generate

Generate a complete workflow graph from a text description.

Request body:

{
  "description": "Classify a ticket then route to the right agent",
  "catalog_id": null
}

Response:

{
  "graph": {
    "nodes": {
      "start": { "id": "start", "type": "start", "name": "Start", "config": {} },
      "classify_1": { "id": "classify_1", "type": "classify", "name": "Classify Ticket", "config": { "categories": "billing, technical, general" } },
      "agent_billing": { "id": "agent_billing", "type": "agent", "name": "Billing Agent", "config": { "system_prompt": "You handle billing queries..." } },
      "end_1": { "id": "end_1", "type": "end", "name": "End", "config": {} }
    },
    "edges": {
      "e1": { "id": "e1", "source": "start", "target": "classify_1", "condition": null },
      "e2": { "id": "e2", "source": "classify_1", "target": "agent_billing", "condition": "billing" }
    }
  }
}

The editor automatically converts this format (dict-keyed nodes, source/target edges) into the canvas format (arrays, from/to edges) and applies auto-layout.

---

POST /api/v1/agent-workflows/{id}/suggest-nodes

Suggest nodes to add to an existing workflow.

Request body:

{
  "description": "Add a guardrails check before the final agent",
  "current_graph": {
    "nodes": [...],
    "edges": [...]
  }
}

Response: Same {graph: {nodes, edges}} structure as /generate, but only containing the new nodes and edges to add. The editor merges these into the existing canvas.

---

Tips for better results

• Be specific about routing logic: "If confidence < 0.7, route to human review; otherwise proceed" produces better if_else config than "add branching".
• Name your agents: "a billing specialist agent" rather than "an agent" results in a more useful node name and system prompt.
• Describe failure paths: Mention what should happen when something goes wrong. The AI will add appropriate guardrail or fallback nodes.
• Iterate with Suggest: Start with a simple Generate, then use Suggest to layer in complexity (error handling, loops, human steps) incrementally.