From 56545c696c758b3c41cd2a02ad960dc69ab74396 Mon Sep 17 00:00:00 2001 From: ALIENvsROBOT Date: Fri, 14 Aug 2026 12:00:56 +0200 Subject: [PATCH 1/2] feat(ai-tool): expose OpenSERP to n8n agents - Mark the OpenSERP node as usable by n8n AI Agents through the generated tool wrapper. - Document AI-controlled parameters and self-hosted OpenSERP configuration for agent workflows. - Bump the package to version 0.2.0 and enforce the OpenSERP result limit of 100. --- README.md | 38 ++++++++++++++++++++++++++++++++- nodes/OpenSerp/OpenSerp.node.ts | 8 ++++--- package.json | 6 ++++-- 3 files changed, 46 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 882baa7..9d1fa1a 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![npm version](https://img.shields.io/npm/v/@openserp/n8n-nodes-openserp.svg)](https://www.npmjs.com/package/@openserp/n8n-nodes-openserp) [![license](https://img.shields.io/npm/l/@openserp/n8n-nodes-openserp.svg)](https://github.com/openserpapi/n8n/blob/main/LICENSE.md) -n8n community node for OpenSERP. It supports web search, image search, single and batch URL extraction, OpenSERP Cloud account/pricing calls, and Cloud engine capability/status calls. +n8n community node for OpenSERP. It supports web search, image search, single and batch URL extraction, OpenSERP Cloud account/pricing calls, Cloud engine capability/status calls, and use as a tool by n8n AI Agents. ## Install @@ -39,8 +39,44 @@ API Key: leave empty Base URL: http://localhost:7000 ``` +For a server running on another machine, set **Base URL** to that server's root URL, for example `http://openserp-host:7000`. Do not append `/v1` to a self-hosted URL. + The credential test calls `/v1/me` when an API key is present and `/health` when no API key is present. +## Use with n8n AI Agents + +OpenSERP uses n8n's native app-node tool wrapper. The normal OpenSERP node and the generated **OpenSERP Tool** are shipped in this same package; a second repository or npm package is not required. + +1. Install or update to `@openserp/n8n-nodes-openserp@0.2.0` or later, then restart n8n. +2. Add an **AI Agent** and connect a chat model. +3. From the AI Agent's **Tool** connector, add **OpenSERP Tool**. +4. Select the OpenSERP credential, resource, operation, and any limits you want to keep under workflow-owner control. +5. For fields the model should choose, select n8n's **Let the model define this parameter** button. + +Recommended AI-controlled fields: + +- **Query** for web or image search. +- **Region**, **Language**, **Date Range**, **File Extension**, and **Site** when the user's request should determine filters. +- **URL** for single-page extraction. + +Recommended workflow-controlled fields: + +- **Resource** and **Operation**, which define the tool's purpose. +- **Limit**, **Engines**, **Mode**, extraction depth, and timeout, which affect cost, latency, and result size. +- Credentials and base URL. + +For example, configure one OpenSERP Tool as `Search / Mega`, keep `Limit: 10`, `Mode: Balanced`, and `Extract Top Results: false`, then let the model fill **Query**, **Region**, and **Language**. A second tool can be configured as `Extract / Get Content` and let the model fill only **URL**. + +n8n adds a generated tool description based on the selected resource and operation. You can switch it to a manual description when the agent needs stricter routing instructions, for example: `Search the public web for current factual information. Return source URLs with the result.` + +On older self-hosted n8n releases that block community packages from being used as tools, set the following environment variable and restart n8n: + +```text +N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true +``` + +The `$fromAI()` function and the model-fill button only work while the node is connected to an AI Agent as a tool. Keep fixed limits for untrusted prompts so the model cannot create unexpectedly large searches or extraction requests. + ## Operations - **Search: Single** returns one n8n item per web result from one engine. diff --git a/nodes/OpenSerp/OpenSerp.node.ts b/nodes/OpenSerp/OpenSerp.node.ts index c77f1a6..287ddb2 100644 --- a/nodes/OpenSerp/OpenSerp.node.ts +++ b/nodes/OpenSerp/OpenSerp.node.ts @@ -102,7 +102,7 @@ const commonQueryProperties: INodeProperties[] = [ default: '', required: true, placeholder: 'openserp', - description: 'Search query text', + description: 'Search query text. When used as an AI Agent tool, this is the main parameter to let the model fill', }, { displayName: 'Limit', @@ -111,6 +111,7 @@ const commonQueryProperties: INodeProperties[] = [ default: 50, typeOptions: { minValue: 1, + maxValue: 100, }, description: 'Max number of results to return', }, @@ -202,8 +203,9 @@ export class OpenSerp implements INodeType { defaults: { name: "OpenSERP", }, - inputs: ["main"], - outputs: ["main"], + usableAsTool: true, + inputs: [NodeConnectionTypes.Main], + outputs: [NodeConnectionTypes.Main], credentials: [ { name: "openSerpApi", diff --git a/package.json b/package.json index ef96b40..21cd408 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@openserp/n8n-nodes-openserp", - "version": "0.1.5", - "description": "n8n community node for OpenSERP search, image search, extraction, account, and engine status operations.", + "version": "0.2.0", + "description": "n8n community node and AI Agent tool for OpenSERP search, image search, extraction, account, and engine status operations.", "license": "MIT", "author": { "name": "OpenSERP" @@ -23,6 +23,8 @@ "search", "search-api", "image-search", + "ai-agent", + "ai-tool", "seo", "automation" ], From 368dfbb6b706586335692988b1012bc4c577bbcb Mon Sep 17 00:00:00 2001 From: ALIENvsROBOT Date: Tue, 25 Aug 2026 13:44:45 +0200 Subject: [PATCH 2/2] fix(lint): satisfy n8n community node rules - Add the required final period to the AI tool query description. - Remove the disallowed result maxValue while preserving the existing minimum validation. - Restore literal main input and output declarations required for regular n8n nodes. - Follow-up for #1 and PR #2. --- nodes/OpenSerp/OpenSerp.node.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/nodes/OpenSerp/OpenSerp.node.ts b/nodes/OpenSerp/OpenSerp.node.ts index 287ddb2..2bb9355 100644 --- a/nodes/OpenSerp/OpenSerp.node.ts +++ b/nodes/OpenSerp/OpenSerp.node.ts @@ -12,7 +12,6 @@ import type { SearchParams, } from '@openserp/sdk'; import { - NodeConnectionTypes, NodeOperationError, type ICredentialDataDecryptedObject, type IExecuteFunctions, @@ -102,7 +101,8 @@ const commonQueryProperties: INodeProperties[] = [ default: '', required: true, placeholder: 'openserp', - description: 'Search query text. When used as an AI Agent tool, this is the main parameter to let the model fill', + description: + 'Search query text. When used as an AI Agent tool, this is the main parameter to let the model fill.', }, { displayName: 'Limit', @@ -111,7 +111,6 @@ const commonQueryProperties: INodeProperties[] = [ default: 50, typeOptions: { minValue: 1, - maxValue: 100, }, description: 'Max number of results to return', }, @@ -204,8 +203,8 @@ export class OpenSerp implements INodeType { name: "OpenSERP", }, usableAsTool: true, - inputs: [NodeConnectionTypes.Main], - outputs: [NodeConnectionTypes.Main], + inputs: ["main"], + outputs: ["main"], credentials: [ { name: "openSerpApi",