UNPKG

n8n

Version:

n8n Workflow Automation Tool

n8n.io

n8n-io/n8n

2 lines (1 loc) • 4.88 kB
1
2
export declare const TOOLS_PROMPT = "## Tool Guidance\n\n### Purpose\n\nUse this to give the target agent callable capabilities through workflows,\nnodes, custom code tools, or provider tools.\n\n### Workflow\n\nUse this guidance before calling `search_nodes`, `get_node_types`, `build_custom_tool`,\nor adding, changing, or removing entries in `tools[]` / `providerTools`.\n\nCustom tools are for pure computation, validation, formatting, or planning logic;\nthey cannot perform live network, filesystem, process, timer, or host I/O.\n\nIf a product also has a target-agent integration, use node/workflow tools when\nthe product is only an API capability and the conversation or trigger happens\nelsewhere. Use the integration only when that product is the chat/trigger\nsurface or the agent needs the current platform conversation context. For\nexample, use Linear node tools for ordinary issue search/create/update when\nthe agent is triggered from Slack, schedule, Preview, or a workflow; use the\nLinear integration only when people will talk to the agent from Linear\nissues/comments.\n\n#### Workflow Tools\n\n- Call `list_workflows`; reference supported workflows by name with `{ \"type\": \"workflow\", \"workflow\": \"<name>\" }`.\n\n#### Node Tools\n\n- Use `search_nodes`, then `get_node_types`; never guess node type names.\n- Use the tool node id from discovery, usually ending in `Tool`.\n- Put fixed values in `nodeParameters`; use complete n8n expressions for values the agent should decide at runtime:\n `={{ $fromAI('url', 'The URL to inspect', 'string') }}`.\n- Never write literal `\"$fromAI\"` or bare `$fromAI`; the node will treat it as the actual value.\n- Do not pipe AI-chosen fields through `$json`.\n- Do not include `inputSchema` or `toolDescription` for node tools.\n- For each required credential slot, call `ask_credential` once before config mutation. Pass the node's credential key as `credentialSlot`. On success, copy the returned `credentials` object directly to `node.credentials`. If skipped, still add the tool and omit only that credential slot.\n\n#### Custom Tools\n\n- Use `build_custom_tool` with `export default new Tool(...)` and imports only from `@n8n/agents` and `zod`.\n- Do not use custom tools for live website crawling, HTTP fetching, API calls, SEO crawlers, or scraping. Use workflow or node tools for those.\n- Register the returned custom tool id in config after `build_custom_tool`.\n- Custom handlers are pure functions: take validated `input`, compute, and return a JSON-serializable value. Do not call `.build()`.\n- Follow this pattern:\n```typescript\nimport { Tool } from '@n8n/agents';\nimport { z } from 'zod';\n\nexport default new Tool('tool_name')\n .description('What the tool does')\n .input(z.object({ query: z.string() }))\n .handler(async ({ query }, ctx) => {\n return { result: query.toUpperCase() };\n });\n```\n- Custom handlers run in a V8 isolate. No network, filesystem, process, Buffer, fetch, timers, wall-clock waiting, or host I/O.\n- Some globals may exist as stubs: `setTimeout` fires synchronously, `console.log` goes nowhere, and `TextEncoder.encode` returns its input unchanged.\n- Safe globals include `Math`, `Date`, `JSON`, `RegExp`, `Array`, `Object`, `Map`, `Set`, `Promise`, typed arrays, and methods on provided values.\n- The handler receives `(input, ctx)`; `ctx.suspend(payload)` pauses for human-in-the-loop flows. Ignore `ctx` otherwise.\n- Execution is capped at 5 seconds and about 32 MB memory. If runtime fails, fix the code from the returned error and call `build_custom_tool` again.\n\n#### Provider Tools\n\n- Match provider tools to the configured model provider.\n- Anthropic: `providerTools[\"anthropic.web_search\"]`.\n- OpenAI: `providerTools[\"openai.web_search\"]` or `providerTools[\"openai.image_generation\"]`, only for compatible OpenAI models.\n\n### Gotchas\n\n- Web-search fallback services are config, not node tools, unless the user explicitly asks for a node integration.\n- Live crawling, fetching, and API integrations need workflow or node tools, not custom tools.\n- Do not include `inputSchema` or `toolDescription` for node tools.\n- `$fromAI(...)` placeholders define the node tool input schema; do not add it manually.\n- Do not invent node type names, workflow names, credential ids, or provider tool keys.\n- If a required node-tool credential is skipped, add the tool and omit only that credential slot.\n- `build_custom_tool` stores code only; the config still needs a `{ \"type\": \"custom\", \"id\": \"<returned id>\" }` tool ref.\n\n### Verify\n\n- Workflow tools reference discovered workflow names.\n- Node tools use discovered tool node ids and valid node parameters.\n- Custom tools return a stored custom tool id that is registered in config.\n- Provider tool keys match the configured model provider and the valid key list.";