Workflow SDK

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
• packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md
• packages/cli/src/modules/mcp/tools/workflow-builder/sdk-reference-content.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts

The n8n Workflow SDK is a specialized TypeScript/JavaScript library designed to facilitate the programmatic construction and modification of n8n workflows. It serves as a domain-specific language (DSL) for defining workflow graphs, including nodes, triggers, and their interconnections, without requiring manual JSON manipulation.

The SDK is primarily utilized by AI agents and developers to generate executable code that n8n can interpret into functional automation. It provides a static, restricted subset of TypeScript/JavaScript to build a static graph; it does not execute the workflow itself but rather defines the blueprint for n8n's execution engine.

Sources: packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:27-31, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:25-27

Architecture and Core Components

The SDK architecture revolves around a chainable builder pattern. Nodes are defined as constants and then composed into a workflow through an exported default object.

Composition Logic

The workflow generation follows a specific sequence:

1. Node Declaration: Every node (utility or service) is defined using node(), trigger(), ifElse(), switchCase(), merge(), or splitInBatches() functions.
2. Workflow Initialisation: A workflow('id', 'name') object is created.
3. Graph Composition: Nodes are added to the workflow using .add(node) and connected using .to(target).

The diagram above shows the relationship between node declaration and the final workflow composition chain.
Sources: packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:374-386, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:46-70

Node Types and Factory Functions

The SDK provides dedicated factory functions to ensure type safety and valid configuration structures:

Function	Usage
trigger()	Defines entry points (e.g., manual trigger, webhooks, schedules).
node()	Defines standard action nodes (e.g., HTTP Request, Slack, Gmail).
ifElse()	Creates a two-way branch (True/False).
switchCase()	Creates a multi-way branch based on cases.
merge()	Combines data from multiple branches.
splitInBatches()	Handles looping and batch processing.
languageModel()	Defines sub-nodes for AI agents.

Sources: packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:329-350, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:333-350

Workflow Building Rules

Expression Handling

Dynamic data in the SDK must be wrapped in the expr() function. These expressions use double curly braces {{ }} to access runtime variables like $json, $input, or specific node outputs via $('NodeName').

• Correct: expr('Hello {{ $json.name }}')
• Correct: expr("{{ $('Webhook').item.json.field }}")
• Incorrect: Backtick template literals are not allowed within the SDK code builder.

Sources: packages/cli/src/modules/mcp/tools/workflow-builder/sdk-reference-content.ts:24-34, packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:313-327

Connectivity and Item Flow

The SDK enforces specific rules for data flow to prevent item multiplication or unwanted execution behavior:

• Item Count Tracing: If Node A returns N items, Node B will run N times by default.
• Execute Once: For nodes that should only run once regardless of input (e.g., a final summary notification), the parameter executeOnce: true must be set in the node configuration.
• Merge Indices: Inputs for the merge() node are zero-based. Use .input(0) for the first input and .input(1) for the second.

Diagram showing parallel branch convergence into specific 0-indexed merge inputs.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:88-105, packages/cli/src/modules/mcp/tools/workflow-builder/sdk-reference-content.ts:42-45

Specialized Techniques

AI Agent Sub-nodes

AI Agents utilize a specific sub-node pattern where components like models, memory, and tools are attached directly to the agent node configuration rather than chained.

const aiAgent = node({
  type: '@n8n/n8n-nodes-langchain.agent',
  version: 3.1,
  config: {
    name: 'AI Assistant',
    parameters: { promptType: 'define' },
    subnodes: { 
      model: openAiModel, 
      tools: [calculatorTool],
      memory: windowBufferMemory 
    }
  }
});

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:285-300, packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:435-442

Document Processing and Binary Data

The SDK handles binary data preservation using specific patterns. Nodes such as documentLoader can use Data Source: Binary to process files directly.

• Extraction: Extract from File requires checking file types (MIME/extension) via an IF or Switch node before processing.
• Preservation: Since many nodes drop binary data by default, the SDK recommends using parallel branches or the "Include Other Input Fields" setting to ensure binary properties like attachment_0 are not lost.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:47-60, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:100-115

Web App Architecture (SPA)

The SDK supports serving Single Page Applications via webhooks. The recommended pattern is:

1. Webhook Trigger: Receives the request.
2. Code Node: Injects data into a base64-encoded JSON placeholder within an HTML template.
3. Respond to Webhook: Sends the HTML with Content-Type: text/html.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:7-25

Credential Management

Credentials in the SDK are handled via the newCredential() helper. This prevents hardcoding sensitive information and allows n8n to prompt the user for setup after the workflow code is generated.

• Selection: newCredential('Credential Name', 'credential-id') is used for existing credentials.
• Placeholders: newCredential('Suggested Name') is used when a new credential is required.

Sources: packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:195-210, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:505-510

Summary

The Workflow SDK is a robust tool for programmatic workflow definition, focusing on type safety, clear graph composition, and standardized data handling. By enforcing strict rules on expressions, node wiring, and credential management, it ensures that generated code is consistently valid and executable within the n8n environment.