feat(core): Implement wrapping of regular nodes as AI Tools (#10641)

Co-authored-by: JP van Oosten <jp@n8n.io>

packages/core/package.json

@@ -44,6 +44,7 @@
     "file-type": "16.5.4",
     "form-data": "catalog:",
     "lodash": "catalog:",
+    "@langchain/core": "0.2.18",
     "luxon": "catalog:",
     "mime-types": "2.1.35",
     "n8n-workflow": "workspace:*",
@@ -54,6 +55,7 @@
     "ssh2": "1.15.0",
     "typedi": "catalog:",
     "uuid": "catalog:",
-    "xml2js": "catalog:"
+    "xml2js": "catalog:",
+    "zod": "catalog:"
   }
 }

packages/core/src/CreateNodeAsTool.ts

@@ -0,0 +1,296 @@
+/**
+ * @module NodeAsTool
+ * @description This module converts n8n nodes into LangChain tools by analyzing node parameters,
+ * identifying placeholders, and generating a Zod schema. It then creates a DynamicStructuredTool
+ * that can be used in LangChain workflows.
+ *
+ * General approach:
+ * 1. Recursively traverse node parameters to find placeholders, including in nested structures
+ * 2. Generate a Zod schema based on these placeholders, preserving the nested structure
+ * 3. Create a DynamicStructuredTool with the schema and a function that executes the n8n node
+ *
+ * Example:
+ * - Node parameters:
+ *   {
+ *     "inputText": "{{ '__PLACEHOLDER: Enter main text to process' }}",
+ *     "options": {
+ *       "language": "{{ '__PLACEHOLDER: Specify language' }}",
+ *       "advanced": {
+ *         "maxLength": "{{ '__PLACEHOLDER: Enter maximum length' }}"
+ *       }
+ *     }
+ *   }
+ *
+ * - Generated Zod schema:
+ *   z.object({
+ *     "inputText": z.string().describe("Enter main text to process"),
+ *     "options__language": z.string().describe("Specify language"),
+ *     "options__advanced__maxLength": z.string().describe("Enter maximum length")
+ *   }).required()
+ *
+ * - Resulting tool can be called with:
+ *   {
+ *     "inputText": "Hello, world!",
+ *     "options__language": "en",
+ *     "options__advanced__maxLength": "100"
+ *   }
+ *
+ * Note: Nested properties are flattened with double underscores in the schema,
+ * but the tool reconstructs the original nested structure when executing the node.
+ */
+
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import {
+	NodeConnectionType,
+	type IExecuteFunctions,
+	type INodeParameters,
+	type INodeType,
+} from 'n8n-workflow';
+import { z } from 'zod';
+
+/** Represents a nested object structure */
+type NestedObject = { [key: string]: unknown };
+
+/**
+ * Encodes a dot-notated key to a format safe for use as an object key.
+ * @param {string} key - The dot-notated key to encode.
+ * @returns {string} The encoded key.
+ */
+function encodeDotNotation(key: string): string {
+	// Replace dots with double underscores, then handle special case for '__value' for complicated params
+	return key.replace(/\./g, '__').replace('__value', '');
+}
+
+/**
+ * Decodes an encoded key back to its original dot-notated form.
+ * @param {string} key - The encoded key to decode.
+ * @returns {string} The decoded, dot-notated key.
+ */
+function decodeDotNotation(key: string): string {
+	// Simply replace double underscores with dots
+	return key.replace(/__/g, '.');
+}
+
+/**
+ * Recursively traverses an object to find placeholder values.
+ * @param {NestedObject} obj - The object to traverse.
+ * @param {string[]} path - The current path in the object.
+ * @param {Map<string, string>} results - Map to store found placeholders.
+ * @returns {Map<string, string>} Updated map of placeholders.
+ */
+function traverseObject(
+	obj: NestedObject,
+	path: string[] = [],
+	results: Map<string, string> = new Map(),
+): Map<string, string> {
+	for (const [key, value] of Object.entries(obj)) {
+		const currentPath = [...path, key];
+		const fullPath = currentPath.join('.');
+
+		if (typeof value === 'string' && value.startsWith("{{ '__PLACEHOLDER")) {
+			// Store placeholder values with their full path
+			results.set(encodeDotNotation(fullPath), value);
+		} else if (Array.isArray(value)) {
+			// Recursively traverse arrays
+			// eslint-disable-next-line @typescript-eslint/no-use-before-define
+			traverseArray(value, currentPath, results);
+		} else if (typeof value === 'object' && value !== null) {
+			// Recursively traverse nested objects, but only if they're not empty
+			if (Object.keys(value).length > 0) {
+				traverseObject(value as NestedObject, currentPath, results);
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Recursively traverses an array to find placeholder values.
+ * @param {unknown[]} arr - The array to traverse.
+ * @param {string[]} path - The current path in the array.
+ * @param {Map<string, string>} results - Map to store found placeholders.
+ */
+function traverseArray(arr: unknown[], path: string[], results: Map<string, string>): void {
+	arr.forEach((item, index) => {
+		const currentPath = [...path, index.toString()];
+		const fullPath = currentPath.join('.');
+
+		if (typeof item === 'string' && item.startsWith("{{ '__PLACEHOLDER")) {
+			// Store placeholder values with their full path
+			results.set(encodeDotNotation(fullPath), item);
+		} else if (Array.isArray(item)) {
+			// Recursively traverse nested arrays
+			traverseArray(item, currentPath, results);
+		} else if (typeof item === 'object' && item !== null) {
+			// Recursively traverse nested objects
+			traverseObject(item as NestedObject, currentPath, results);
+		}
+	});
+}
+
+/**
+ * Builds a nested object structure from matching keys and their values.
+ * @param {string} baseKey - The base key to start building from.
+ * @param {string[]} matchingKeys - Array of matching keys.
+ * @param {Record<string, string>} values - Object containing values for the keys.
+ * @returns {Record<string, unknown>} The built nested object structure.
+ */
+function buildStructureFromMatches(
+	baseKey: string,
+	matchingKeys: string[],
+	values: Record<string, string>,
+): Record<string, unknown> {
+	const result = {};
+
+	for (const matchingKey of matchingKeys) {
+		const decodedKey = decodeDotNotation(matchingKey);
+		// Extract the part of the key after the base key
+		const remainingPath = decodedKey
+			.slice(baseKey.length)
+			.split('.')
+			.filter((k) => k !== '');
+		let current: Record<string, unknown> = result;
+
+		// Build the nested structure
+		for (let i = 0; i < remainingPath.length - 1; i++) {
+			if (!(remainingPath[i] in current)) {
+				current[remainingPath[i]] = {};
+			}
+			current = current[remainingPath[i]] as Record<string, unknown>;
+		}
+
+		// Set the value at the deepest level
+		const lastKey = remainingPath[remainingPath.length - 1];
+		current[lastKey ?? matchingKey] = values[matchingKey];
+	}
+
+	// If no nested structure was created, return the direct value
+	return Object.keys(result).length === 0 ? values[encodeDotNotation(baseKey)] : result;
+}
+
+/**
+ * Extracts the description from a placeholder string.
+ * @param {string} value - The placeholder string.
+ * @returns {string} The extracted description or a default message.
+ */
+function extractPlaceholderDescription(value: string): string {
+	const match = value.match(/{{ '__PLACEHOLDER:\s*(.+?)\s*' }}/);
+	return match ? match[1] : 'No description provided';
+}
+
+/**
+ * Creates a DynamicStructuredTool from an n8n node.
+ * @param {INodeType} node - The n8n node to convert.
+ * @param {IExecuteFunctions} ctx - The execution context.
+ * @param {INodeParameters} nodeParameters - The node parameters.
+ * @returns {DynamicStructuredTool} The created tool.
+ */
+export function createNodeAsTool(
+	node: INodeType,
+	ctx: IExecuteFunctions,
+	nodeParameters: INodeParameters,
+): DynamicStructuredTool {
+	// Find all placeholder values in the node parameters
+	const placeholderValues = traverseObject(nodeParameters);
+
+	// Generate Zod schema from placeholder values
+	const schemaObj: { [key: string]: z.ZodString } = {};
+	for (const [key, value] of placeholderValues.entries()) {
+		const description = extractPlaceholderDescription(value);
+		schemaObj[key] = z.string().describe(description);
+	}
+	const schema = z.object(schemaObj).required();
+
+	// Get the tool description from node parameters or use the default
+	const toolDescription = ctx.getNodeParameter(
+		'toolDescription',
+		0,
+		node.description.description,
+	) as string;
+	type GetNodeParameterMethod = IExecuteFunctions['getNodeParameter'];
+
+	const tool = new DynamicStructuredTool({
+		name: node.description.name,
+		description: toolDescription ? toolDescription : node.description.description,
+		schema,
+		func: async (functionArgs: z.infer<typeof schema>) => {
+			// Create a proxy for ctx to soft-override parameters with values from the LLM
+			const ctxProxy = new Proxy(ctx, {
+				get(target: IExecuteFunctions, prop: string | symbol, receiver: unknown) {
+					if (prop === 'getNodeParameter') {
+						// Override getNodeParameter method
+						// eslint-disable-next-line @typescript-eslint/unbound-method
+						return new Proxy(target.getNodeParameter, {
+							apply(
+								targetMethod: GetNodeParameterMethod,
+								thisArg: unknown,
+								argumentsList: Parameters<GetNodeParameterMethod>,
+							): ReturnType<GetNodeParameterMethod> {
+								const [key] = argumentsList;
+								if (typeof key !== 'string') {
+									// If key is not a string, use the original method
+									return Reflect.apply(targetMethod, thisArg, argumentsList);
+								}
+
+								const encodedKey = encodeDotNotation(key);
+								// Check if the full key or any more specific key is a placeholder
+								const matchingKeys = Array.from(placeholderValues.keys()).filter((k) =>
+									k.startsWith(encodedKey),
+								);
+
+								if (matchingKeys.length > 0) {
+									// If there are matching keys, build the structure using args
+									const res = buildStructureFromMatches(encodedKey, matchingKeys, functionArgs);
+									// Return either the specific value or the entire built structure
+									return res?.[decodeDotNotation(key)] ?? res;
+								}
+
+								// If no placeholder is found, use the original function
+								return Reflect.apply(targetMethod, thisArg, argumentsList);
+							},
+						});
+					}
+					// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+					return Reflect.get(target, prop, receiver);
+				},
+			});
+
+			// Add input data to the context
+			ctxProxy.addInputData(NodeConnectionType.AiTool, [[{ json: functionArgs }]]);
+
+			// Execute the node with the proxied context
+			const result = await node.execute?.bind(ctxProxy)();
+
+			// Process and map the results
+			const mappedResults = result?.[0]?.flatMap((item) => item.json);
+
+			// Add output data to the context
+			ctxProxy.addOutputData(NodeConnectionType.AiTool, 0, [
+				[{ json: { response: mappedResults } }],
+			]);
+
+			// Return the stringified results
+			return JSON.stringify(mappedResults);
+		},
+	});
+
+	return tool;
+}
+
+/**
+ * Asynchronously creates a DynamicStructuredTool from an n8n node.
+ * @param {IExecuteFunctions} ctx - The execution context.
+ * @param {INodeType} node - The n8n node to convert.
+ * @param {INodeParameters} nodeParameters - The node parameters.
+ * @returns {Promise<{response: DynamicStructuredTool}>} A promise that resolves to an object containing the created tool.
+ */
+export function getNodeAsTool(
+	ctx: IExecuteFunctions,
+	node: INodeType,
+	nodeParameters: INodeParameters,
+) {
+	return {
+		response: createNodeAsTool(node, ctx, nodeParameters),
+	};
+}

packages/core/src/DirectoryLoader.ts

@@ -40,14 +40,20 @@ export type Types = {
 export abstract class DirectoryLoader {
 	isLazyLoaded = false;
 
+	// Another way of keeping track of the names and versions of a node. This
+	// seems to only be used by the installedPackages repository
 	loadedNodes: INodeTypeNameVersion[] = [];
 
+	// Stores the loaded descriptions and sourcepaths
 	nodeTypes: INodeTypeData = {};
 
 	credentialTypes: ICredentialTypeData = {};
 
+	// Stores the location and classnames of the nodes and credentials that are
+	// loaded; used to actually load the files in lazy-loading scenario.
 	known: KnownNodesAndCredentials = { nodes: {}, credentials: {} };
 
+	// Stores the different versions with their individual descriptions
 	types: Types = { nodes: [], credentials: [] };
 
 	protected nodesByCredential: Record<string, string[]> = {};

packages/core/src/NodeExecuteFunctions.ts

@@ -159,6 +159,7 @@ import { InstanceSettings } from './InstanceSettings';
 import { ScheduledTaskManager } from './ScheduledTaskManager';
 import { SSHClientsManager } from './SSHClientsManager';
 import { binaryToBuffer } from './BinaryData/utils';
+import { getNodeAsTool } from './CreateNodeAsTool';
 
 axios.defaults.timeout = 300000;
 // Prevent axios from adding x-form-www-urlencoded headers by default
@@ -2780,12 +2781,6 @@ async function getInputConnectionData(
 				connectedNode.typeVersion,
 			);
 
-			if (!nodeType.supplyData) {
-				throw new ApplicationError('Node does not have a `supplyData` method defined', {
-					extra: { nodeName: connectedNode.name },
-				});
-			}
-
 			const context = Object.assign({}, this);
 
 			context.getNodeParameter = (
@@ -2853,6 +2848,18 @@ async function getInputConnectionData(
 				}
 			};
 
+			if (!nodeType.supplyData) {
+				if (nodeType.description.outputs.includes(NodeConnectionType.AiTool)) {
+					nodeType.supplyData = async function (this: IExecuteFunctions) {
+						return getNodeAsTool(this, nodeType, this.getNode().parameters);
+					};
+				} else {
+					throw new ApplicationError('Node does not have a `supplyData` method defined', {
+						extra: { nodeName: connectedNode.name },
+					});
+				}
+			}
+
 			try {
 				const response = await nodeType.supplyData.call(context, itemIndex);
 				if (response.closeFunction) {

packages/core/test/CreateNodeAsTool.test.ts

@@ -0,0 +1,92 @@
+import { createNodeAsTool } from '@/CreateNodeAsTool';
+import type { IExecuteFunctions, INodeParameters, INodeType } from 'n8n-workflow';
+import { NodeConnectionType } from 'n8n-workflow';
+import { z } from 'zod';
+
+jest.mock('@langchain/core/tools', () => ({
+	DynamicStructuredTool: jest.fn().mockImplementation((config) => ({
+		name: config.name,
+		description: config.description,
+		schema: config.schema,
+		func: config.func,
+	})),
+}));
+
+describe('createNodeAsTool', () => {
+	let mockCtx: IExecuteFunctions;
+	let mockNode: INodeType;
+	let mockNodeParameters: INodeParameters;
+
+	beforeEach(() => {
+		mockCtx = {
+			getNodeParameter: jest.fn(),
+			addInputData: jest.fn(),
+			addOutputData: jest.fn(),
+		} as unknown as IExecuteFunctions;
+
+		mockNode = {
+			description: {
+				name: 'TestNode',
+				description: 'Test node description',
+			},
+			execute: jest.fn().mockResolvedValue([[{ json: { result: 'test' } }]]),
+		} as unknown as INodeType;
+
+		mockNodeParameters = {
+			param1: "{{ '__PLACEHOLDER: Test parameter' }}",
+			param2: 'static value',
+			nestedParam: {
+				subParam: "{{ '__PLACEHOLDER: Nested parameter' }}",
+			},
+		};
+		jest.clearAllMocks();
+	});
+
+	it('should create a DynamicStructuredTool with correct properties', () => {
+		const tool = createNodeAsTool(mockNode, mockCtx, mockNodeParameters);
+
+		expect(tool).toBeDefined();
+		expect(tool.name).toBe('TestNode');
+		expect(tool.description).toBe('Test node description');
+		expect(tool.schema).toBeDefined();
+	});
+
+	it('should use toolDescription if provided', () => {
+		const customDescription = 'Custom tool description';
+		(mockCtx.getNodeParameter as jest.Mock).mockReturnValue(customDescription);
+
+		const tool = createNodeAsTool(mockNode, mockCtx, mockNodeParameters);
+
+		expect(tool.description).toBe(customDescription);
+	});
+
+	it('should create a schema based on placeholder values in nodeParameters', () => {
+		const tool = createNodeAsTool(mockNode, mockCtx, mockNodeParameters);
+
+		expect(tool.schema).toBeDefined();
+		expect(tool.schema.shape).toHaveProperty('param1');
+		expect(tool.schema.shape).toHaveProperty('nestedParam__subParam');
+		expect(tool.schema.shape).not.toHaveProperty('param2');
+	});
+
+	it('should handle nested parameters correctly', () => {
+		const tool = createNodeAsTool(mockNode, mockCtx, mockNodeParameters);
+
+		expect(tool.schema.shape.nestedParam__subParam).toBeInstanceOf(z.ZodString);
+	});
+
+	it('should create a function that wraps the node execution', async () => {
+		const tool = createNodeAsTool(mockNode, mockCtx, mockNodeParameters);
+
+		const result = await tool.func({ param1: 'test value', nestedParam__subParam: 'nested value' });
+
+		expect(mockCtx.addInputData).toHaveBeenCalledWith(NodeConnectionType.AiTool, [
+			[{ json: { param1: 'test value', nestedParam__subParam: 'nested value' } }],
+		]);
+		expect(mockNode.execute).toHaveBeenCalled();
+		expect(mockCtx.addOutputData).toHaveBeenCalledWith(NodeConnectionType.AiTool, 0, [
+			[{ json: { response: [{ result: 'test' }] } }],
+		]);
+		expect(result).toBe(JSON.stringify([{ result: 'test' }]));
+	});
+});