> Node: AI Transform (`ai_transform`) · Action · v1 > Category: AI · Credentials: OpenAI (`openai`) > Updated: 2026-08-16 # AI Transform > Transform data using OpenAI and natural language instructions. ## Overview AI Transform uses OpenAI models to transform workflow data based on natural language instructions. Two modes are available: "Generate Code" sends a sample of items to the LLM which generates JavaScript code that is then executed in an isolated JavaScript sandbox against all items; "Direct Transform" sends each item individually to the LLM for transformation. Supports GPT-5.2, GPT-5, GPT-5 Mini, GPT-5 Nano, GPT-4.1, GPT-4.1 Mini, and GPT-4.1 Nano models. **Category:** AI **Tool Name:** `ai_transform` **Version:** 1 **Appearance:** Icon: `lucide-Brain` | Color: `#8B5CF6` ## Node Type **Action** — processes input items and produces output ## Input / Output | Direction | Port(s) | |-----------|--------| | Input | `Input` | | Output | `Output`, `Error` | ## Credentials This tool requires **OpenAI** credentials. See the [Credentials Guide](https://busybot.net/credentials/openai/) for setup instructions. ### Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | Instructions | `string` | Yes | — | Natural language instructions describing how to transform the data. Supports {{ }} expressions in Direct Transform mode. | | Model | `options` | No | `gpt-4.1-mini` | The OpenAI model to use for transformation. | | | | | | Options: `gpt-5.2`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano` | | Transform Mode | `options` | No | `generateCode` | Generate Code: LLM writes JS executed in sandbox against all items. Direct Transform: LLM transforms each item individually. | | | | | | Options: `generateCode`, `directTransform` | | Sample Size | `number` | No | `3` | Number of items to sample for the code generation prompt (1-10). _(shown when Transform Mode is `generateCode`)_ | | Max Concurrency | `number` | No | `10` | Maximum number of concurrent OpenAI API calls for direct transform mode (1-50). _(shown when Transform Mode is `directTransform`)_ | | Include Input | `boolean` | No | `true` | When true, original input fields are merged into the transformed output. Applies to Direct Transform mode; in Generate Code mode the generated code controls the output shape directly. | | Schema Hint | `string` | No | — | Optional description of the expected output schema to guide the AI transformation. Supports {{ }} expressions in Direct Transform mode. | ## Output Data The transformed data becomes the output item's JSON, and every output item carries an `_meta.aiTransform` block describing the run. Binary data from the input item is forwarded unchanged. In Direct Transform mode there is exactly one output item per input item, and Include Input decides whether the original fields are merged underneath the transformed ones. In Generate Code mode the generated code returns the item array, so the node can emit fewer or more items than it received — for example when the instructions ask it to filter. ```json { "_meta": { "aiTransform": { "model": "gpt-4.1-mini", "mode": "generateCode", "tokensUsed": { "prompt_tokens": 412, "completion_tokens": 96, "total_tokens": 508 }, "generatedCode": "return items.map(item => ({ ...item }));", "sampleSize": 3, "totalItems": 25, "resultIndex": 0 } } } ``` - `model`, `mode` and `tokensUsed` are present in both modes. `mode` is the Transform Mode that produced the item. - Generate Code mode adds `generatedCode` (the JavaScript the model wrote), `sampleSize` (how many items were actually sampled), `totalItems` (how many items the code ran against) and `resultIndex` (the item's position in the returned array). - Direct Transform mode adds `itemIndex` instead — the position of the input item the call was made for. Reference the metadata downstream by expression, e.g. `{{ $json._meta.aiTransform.model }}`. ## Usage Examples - Add a fullName field by combining firstName and lastName - Filter items where status is active - Convert all date strings to ISO 8601 format - Summarize the description field into one sentence - Restructure nested objects into flat key-value pairs - Classify items by sentiment using AI ## Example Configuration Generate Code mode (the default): ```json { "type": "ai_transform", "parameters": { "instructions": "Extract the first and last name from the 'fullName' field and return them as separate 'firstName' and 'lastName' fields.", "model": "gpt-4.1-mini", "transformMode": "generateCode", "sampleSize": 5, "includeInput": false, "schemaHint": "Output fields: firstName (string), lastName (string)" } } ``` Direct Transform mode: ```json { "type": "ai_transform", "parameters": { "instructions": "Analyze the 'reviewText' field and classify the sentiment as 'positive', 'neutral', or 'negative'. Add a 'sentiment' field with the result.", "model": "gpt-4.1", "transformMode": "directTransform", "maxConcurrency": 10, "includeInput": true, "schemaHint": "Output field: sentiment (string, one of: positive, neutral, negative)" } } ``` Minimal required configuration: ```json { "type": "ai_transform", "parameters": { "instructions": "Summarize the 'description' field in one sentence and store it in a 'summary' field." } } ``` All omitted fields fall back to their defaults: `model = "gpt-4.1-mini"`, `transformMode = "generateCode"`, `includeInput = true`, `schemaHint = ""`. Batch field normalization — use `generateCode` when applying a consistent transformation to all records, which is faster and cheaper than per-item calls: ```json { "type": "ai_transform", "parameters": { "instructions": "Normalize the 'phone' field to E.164 format (e.g., +14155552671). Remove any existing formatting characters.", "model": "gpt-4.1-mini", "transformMode": "generateCode", "sampleSize": 3, "includeInput": true, "schemaHint": "Output field: phone (string in E.164 format)" } } ``` Per-item AI classification — use `directTransform` when each item requires independent reasoning by the model: ```json { "type": "ai_transform", "parameters": { "instructions": "Read the 'supportTicket' field and assign a priority level of 'low', 'medium', 'high', or 'critical' based on urgency and impact. Store the result in a 'priority' field.", "model": "gpt-4.1", "transformMode": "directTransform", "maxConcurrency": 5, "includeInput": true, "schemaHint": "Output field: priority (string, one of: low, medium, high, critical)" } } ``` Schema-guided data extraction — use `schemaHint` with `includeInput: false` when you want a clean, reshaped output without the original fields: ```json { "type": "ai_transform", "parameters": { "instructions": "From each record, extract the product name, price as a number, and whether it is in stock as a boolean from the 'rawListing' field.", "model": "gpt-4.1-mini", "transformMode": "generateCode", "sampleSize": 5, "includeInput": false, "schemaHint": "Output fields: productName (string), price (number), inStock (boolean)" } } ``` High-throughput direct transform — for large datasets requiring nuanced per-item reasoning, raise `maxConcurrency` and use a more capable model: ```json { "type": "ai_transform", "parameters": { "instructions": "Translate the 'body' field from its detected language into English. Preserve formatting and tone.", "model": "gpt-5-mini", "transformMode": "directTransform", "maxConcurrency": 25, "includeInput": true, "schemaHint": "Output field: bodyEnglish (string)" } } ``` ### Error Handling | Mode | Behavior | |------|----------| | **stop** | Halts workflow on first error | | **continue** | Skips failed items, passes successful ones through | | **errorPort** | Routes failed items to Error output port | ## Tips Transforms workflow data using OpenAI models guided by natural language instructions, via code generation or direct per-item transformation. Use when you need flexible data reshaping described in plain English rather than explicit field mapping or code. Produces transformed items with optional original field preservation and AI metadata. ### Behavioral notes - **Retry (generateCode only):** If the generated code fails execution, the tool automatically retries once — sending the error message and failed code back to the LLM for correction. - **Expression support (directTransform only):** The `instructions` and `schemaHint` fields support `{{ $json.field }}` expressions in `directTransform` mode, resolved per-item before sending to the LLM. - **Sample size vs concurrency:** `sampleSize` only applies in `generateCode` mode and `maxConcurrency` only applies in `directTransform` mode — set the one that matches the mode you selected. - **Output metadata:** All output items include `_meta.aiTransform` with `model`, `mode`, and `tokensUsed`. `generateCode` mode adds `generatedCode`, `sampleSize`, `totalItems`, and `resultIndex`; `directTransform` mode adds `itemIndex` (the item's zero-based position in the node's input).