> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sndbox.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Build workflows with AI

> Draft workflow graphs, run model instructions mid-workflow, and write complete Code node files with a connected model.

sndbox exposes AI in three deliberately separate places. All three use an [AI connection](/connections/ai), but they affect a workflow differently.

| Surface                       | Use it when                                               | Result                                                   |
| ----------------------------- | --------------------------------------------------------- | -------------------------------------------------------- |
| AI builder                    | You want to create or revise the graph in plain language  | A complete workflow proposal you can review and apply    |
| [AI node](/nodes/ai-prompt)   | A running workflow needs a model answer before continuing | `response`, `usage`, and `model` outputs                 |
| Code editor **Write with AI** | You want a complete Python, HTML, JavaScript, or CSS file | A replacement editor draft, checked live before you save |

## Draft a graph

1. Open a workflow and choose the sparkle button in the top toolbar to open **AI builder**.
2. Select a connected model.
3. Describe the trigger, steps, data flow, and desired result. Include constraints such as “draft the email but do not send it.”
4. Review the proposed node count, connections, validation issues, and summary.
5. Choose **Apply workflow** only when the proposal matches your intent.
6. Configure any deliberately blank credentials, paths, URLs, recipients, or selectors, then validate and run the workflow yourself.

The builder returns a replacement graph, not an execution. It can create built-in nodes, control edges, typed input bindings, and complete Code node source blocks. For a localhost site, it can produce separate HTML, JavaScript, and CSS Code nodes and map each `code` output into a Web Builder node.

<Warning>
  Applying a proposal changes the editor draft. AI does not grant permissions, approve risky actions, invent secret values, or start the workflow. Review side effects and permission changes exactly as you would for a manually built graph.
</Warning>

## Use AI during a run

Add an **AI** node when the next workflow step depends on a live answer. Select a connection, enter or map the instruction, optionally refine the system instruction, and choose the maximum output tokens, creativity, and timeout.

The workflow waits until one of these events occurs:

* The provider returns a response.
* The configured timeout is reached.
* The execution is cancelled.
* The provider rejects the request or the connection is unavailable.

Map `response` into a later text-compatible field. `usage` contains provider-reported token information when available, and `model` records the model ID used for the response. The default timeout is 90 seconds; the runtime accepts 1–300 seconds.

## Write code with AI

Open a Code node, choose **Edit code**, then choose **Write with AI**. Select a connection and describe the complete file or requested change. The current language and editor draft are included as context.

**Generate & replace** replaces only the unsaved draft. The Problems panel immediately checks the returned source. Choose **Save code** or press `Ctrl+S` / `Cmd+S` to commit it to the node; cancel the dialog to keep the previously saved source.

AI-generated code is untrusted code. Inspect it before saving, and review command-execution permission before using Python or JavaScript in run mode. See [Code and Web Builder](/files-and-data/code-and-web-builder) for execution and localhost details.

## Prompting tips

* Name the trigger and final outcome.
* State which external actions must remain drafts or disabled.
* Describe the expected shape of data between nodes.
* For code, request a complete file and state the language, inputs, output format, and error behavior.
* For a site, describe the HTML structure, interactions, styles, and the data each code block should contain.