` 参数注入与提示词级工具描述)
AI 技能AI 插件工作流自动化流程编排【免费下载链接】n8n-skillsn8n skillset for Claude Code to build flawless n8n workflows项目地址https://gitcode.com/gh_mirrors/n8/n8n-skills点击查看免费下载在 n8n 中构建 AI Agent 时工具Tool是模型与外部能力之间的唯一桥梁。本指南基于 n8n-skills 仓库的 n8n-agents 技能包TOOLS.md 及其配套参考文档系统讲解四大工具类型的选型、$fromAI()参数注入机制、plumbed 参数隐藏技巧以及如何把工具名称与描述当作提示词工程来设计。读完你将掌握一套可复用的决策框架与书写规范能够显著减少Agent 不调用我的工具、参数传错等常见故障。核心原则工具的名称与描述就是提示词Agent 选择工具的方式只有一条读取工具的 name 和 description仅此而已。这两个字段都是 prompt 的一部分与参数 schema含$fromAI描述一起进入模型的上下文。正如 TOOLS.md 开篇所强调的要把工具设计当作 API 设计来对待——它做什么、何时使用、每个参数的含义、以及它会如何失败。SKILL.md 将这一条列为两个不可妥协原则之首工具名称和描述就是提示词的一部分。一个名为tool1、描述为空的工具对模型而言是不可见的——模型会跳过它、误选它或者臆造参数。而且这通常没有报错只是表现为Agent 就是不用我的工具。因此工具暴露给模型的一切文本都必须像写 API 文档一样精确。四大工具类型与 Custom Code Tooln8n 的 LangChain 节点族n8n/n8n-nodes-langchain.*为 Agent 提供了四种正规军工具形态外加一个特例Custom Code Tool。选型原则是优先选择能覆盖任务的最轻方案。1. 原生工具节点Native Tool Node预置的工具版常规节点slackTool、gmailTool、googleSheetsTool、toolCalculator、notionTool、httpRequestTool等。它与普通节点行为一致唯一区别是参数可以由 Agent 通过$fromAI()填充。维度说明优点配置最少、经过充分测试、原生体验缺点一个节点只能做一个操作多步逻辑放不进来适用场景能力恰好映射到一个节点 一个操作当原生节点缺少某个操作、或需要非标准的参数形态时可以用 HTTP Request Tool 指向该服务的 API并复用该服务的预定义凭证类型——这样既复用了已有的 OAuth / API-key 凭证又能拿到完整的 API 能力。2. 子工作流作为工具n8n/n8n-nodes-langchain.toolWorkflow任何工作流都可以变成一个带类型化$fromAI()输入的工具这是不止一个节点场景的默认选择也是 n8n 构建 Agent 能力的正统方式详见 SUBWORKFLOW_AS_TOOL.md。维度说明优点工具内拥有 n8n 全部能力——分支、错误处理、子-子工作流、原生节点、自定义逻辑可跨 Agent 复用可独立测试缺点多一层工作流边界略有延迟适用场景超过一个节点逻辑可能被复用或希望独立可测试原生 LangChain 中工具是一个函数而在 n8n 中工具可以是一整个工作流它可以按输入分支IF/Switch、调用多个 API 并聚合、自带重试与回退、调用其他子工作流、读写 Data Tables、用n8n_test_workflow与固定数据独立测试、同时被 Agent 和非 Agent 工作流复用。接线形态两半结构子工作流一侧以Execute Workflow Trigger的Define Below类型化字段模式声明输入工具侧用 Tool Workflow 节点指向子工作流并绑定参数。SUBWORKFLOW_AS_TOOL.md给出了完整 JSON 示例其中关键映射是逐输入进行的workflowInputs: { mappingMode: defineBelow, value: { imagePrompt: {{ $fromAI(imagePrompt, Detailed prompt describing the desired image, string) }}, imageName: {{ $fromAI(imageName, Storage key of an existing image to edit, or empty for new generation, string) }}, sessionId: {{ $(Chat Trigger).first().json.sessionId }} } }Agent 填充{{ $fromAI(paramName, description, string) }}——由 Agent 决定取值。Plumbed注入{{ $(SourceNode).first().json.field }}——由工作流确定值。触发器的输入模式至关重要必须是 Define Below类型化字段而非 passthrough——passthrough 没有 schemaAgent 便没有东西可供$fromAI()填充。类型强制发生在Agent 侧通过$fromAI的type参数而非触发器处允许类型为string/number/boolean/json。此外sessionId这条映射是硬性约束绝不能让sessionId进入$fromAI否则模型会编造一个 UUID必须从触发器 plumb 进来保证记忆与按会话键控的工作保持一致。Agent 能看到的只有Tool Workflow 节点的名称和 description。它看不到子工作流内部结构、子工作流自己的名字也看不到sessionId这类 plumbed 值——只有$fromAI参数会出现在工具 schema 里。这意味着你可以大改子工作流内部而不影响 Agent 所见。工具子工作流的输出契约调用方收到的是最后一个节点输出的内容必须固定一种返回形状并跨模式保持一致例如始终{ imageUrl, imageKey }输出形状是每个调用方依赖的契约。对预期内的失败如搜索无结果返回可分支的形状{ ok: false, error: no_results, message: ... }对非预期但可处理的错误认证失败、上游宕机、不可恢复输入则用Stop and Error节点抛出让 Agent 看到工具错误并自行重试/换工具/上报。子工作流内可失败节点HTTP、S3、DB应设置onError: continueErrorOutput并路由到干净的错误响应。独立测试先n8n_test_workflow({workflowId, method: prepare})确认哪些节点需要固定数据再按节点 name 构造样本项{json: {...}}然后n8n_test_workflow({workflowId, method: pinned, pinData})运行并等待最后核对输出形状。注意 routed 方法需要N8N_MCP_ACCESS_TOKEN及工作流开启 Available in MCP默认method: auto无法运行无 HTTP 触发器的子工作流。3. HTTP Request Tooln8n/n8n-nodes-langchain.toolHttpRequestHTTP Request 节点的包装器把其参数暴露给 Agent。维度说明优点任意 HTTP API 用一个节点就能变成工具缺点仅限 HTTP认证 / 重试 / 错误处理都需要自己接线适用场景调用单个外部 API且希望 Agent 直接编排一个必须知道的细节HTTP Request 自带 HTTP 层超时默认 5 分钟对慢端点需要调大options.timeout。而 Agent 工具本身没有超时——Agent 会一直等到工具返回。指向例如 Notion API复用 Notion 预定义凭证时Agent 可以自行组合 path、method、body覆盖原生节点不暴露的操作。代价是 Agent 现在在手写 API 请求更容易出错需要足够强的模型 描述里清晰的端点指引——这扩大了爆炸半径务必让用户理解这一点。4. MCP Client Tooln8n/n8n-nodes-langchain.mcpClientTool把 Agent 连接到任意 MCP 服务器两种形态外部 MCP 服务器——任意第三方或自托管 MCPGitHub、Linear、Notion、自定义内部服务。一个节点即可暴露该服务器提供的所有工具。n8n 托管的 MCP——同一实例上的某个工作流以 MCP 访问发布后用同一个 client 节点指向 n8n 的 MCP trigger URL。让一个工作流服务多个 Agent。维度说明缺点工具描述与形态来自服务器质量参差且难以调优认证与可达性自备适用场景现成维护良好的 MCP 服务器已覆盖该能力或希望一个已发布的工作流服务多个 AgentPlusCustom Code Tooln8n/n8n-nodes-langchain.toolCode纯内联计算数学、解析、格式化。其运行时契约是string in / string out、没有$fromAI、没有$helpers由 n8n-code-tool 技能管辖——写之前必须先读 n8n-code-tool/SKILL.md。经验法则只要你在代码里想要$fromAI()就应该用.toolWorkflow而不是.toolCode。典型错误包括$fromAI在 Code Tool 沙箱内不可用报No execution data available、返回对象而非字符串报The response property should be a string, but it is an object、返回工作流式数组报Wrong output type returned。决策树到底该用哪种工具TOOLS.md 给出了完整的决策树原文照录如下Capability the agent needs? ├── One native node one operation does it │ → native tool node ├── Native node missing an op / needs custom params for ONE API │ → HTTP Request Tool (with the services predefined credential) ├── More than one node, or logic that might be reused │ → Sub-workflow as tool (.toolWorkflow) ← default when in doubt ├── Pure deterministic computation, one-off, inline │ → Custom Code Tool (.toolCode) ← see n8n-code-tool └── A maintained MCP server covers it / publish n8n logic to many agents → MCP Client Tool补充两个反向判断来自 SUBWORKFLOW_AS_TOOL.md 的 When NOT to use简单单节点包装——调这个端点并返回用 HTTP Request Tool 更短。一次性、仅本 Agent 使用的纯代码逻辑——几行只存在于别处的 JS/Python 用 Custom Code Tool 即可。决策规则可复用的业务逻辑 → 子工作流一次性的 Agent 专用转换 → Code Tool。已有原生工具节点覆盖的能力——不要用子工作流去包slackTool。$fromAI()Agent 如何填充工具参数$fromAI()是 n8n真实存在的表达式辅助函数写在工具节点的参数表达式里。Agent 应该决定的参数就用它包起来sendTo: {{ $fromAI(recipient, Email address of the recipient, string) }} subject: {{ $fromAI(subject, Email subject line, concise and informative, string) }} body: {{ $fromAI(body, Email body in plain text, professional tone, string) }}形态$fromAI(paramName, description, type?, defaultValue?)参数含义要点paramName模型内部使用的参数名snake_case 或 camelCase保持一致description告诉模型要产出什么值属于 prompt 的一部分要具体格式、范围、示例typestring默认、number、boolean、json强制类型校验——类型错误会导致调用失败defaultValue模型省略该参数时使用的值可选它只携带 JSON——不能携带二进制不能有 base64、不能有文件字节即使通过非 AI 绑定也不行。对于二进制应该传一个存储键字符串让工具自行重新获取详见 AGENT_TOOL_BINARY.md。这条二进制边界是双向的硬墙模型可以通过视觉看到上传的图片passthroughBinaryImages: true但工具调用传不了文件字节工具产出的文件也不能以字节形式回给 Agent。统一的解法都是先落存储、跨 JSON 边界传键、另一侧再取。好描述与无用描述的对比原文示例✅ {{ $fromAI(imageName, Storage key for an existing image to edit, or empty for a new generation. Use the exact key shown in the system prompt; do not reconstruct or guess., string) }} ❌ {{ $fromAI(imageName, image name, string) }} // useless to the model把$fromAI的描述当作JSDoc来写——模型就是靠读它来判断该传什么值的。反过来AGENT_TOOL_BINARY.md也强调描述是模型判断取值形状的唯一指引要与你工作流实际使用的存储后端匹配只说明那一种形状不要给一长串可能方案。Plumbed 参数隐藏不该由 Agent 决定的东西并非每个参数都必须走$fromAI。任何参数都可以从工作流上下文确定性地填充而且plumbed 值对 Agent 完全不可见——不出现在工具 schema 里模型产生的任何内容都无法影响它reason: {{ $fromAI(reason, Why the user is requesting a refund, string) }} // agent-filled customerId: {{ $(Chat Trigger).first().json.user.id }} // hidden maxRefund: {{ $(Get user tier).first().json.refundLimit }} // hidden idempotencyKey:{{ $(Chat Trigger).first().json.sessionId }} // hidden应该 plumb注入三类东西身份Identity——userId、customerId、已认证操作者、租户范围。权限边界Authority limits——退款上限、层级标记、允许的区域。关联 IDCorrelation IDs——sessionId、幂等键、trace ID。给 Agent 一个按钮而不是一个方向盘是这一原则的最强形态一个敏感工具可以拥有零个$fromAI参数——Refund order 工具的orderId来自触发器、amount来自取回的订单记录、actor来自会话全部 plumbed。Agent 物理上不可能退错订单它只能决定是否扣动扳机。对于既需要确定性参数、又需要人工签批的动作配合 HUMAN_REVIEW.md 使用——审阅节点插在工具与 Agent 之间的ai_tool链路上审批消息必须用字面量{{ $tool.parameters.name }}展示真实参数绝不能用$fromAI()让模型复述否则人类审批的是模型编造的转述而非即将发出的调用。工具名称与描述即提示词模型每一轮都会执行这样的选择过程拿到系统提示词、对话历史、以及工具列表。对每个工具读取name description 参数 schema含$fromAI描述。挑选描述与当前任务最匹配的工具。坏的名称和描述会造成坏的选型——通常是静默的模型就是不调用你的工具或者用垃圾参数去调另一个工具。没有任何报错。命名动词开头、具体明确好坏为什么Search customer databasequery/tool1通用名称什么也说明不了Generate image with VeoimageGen哪个生成器Edit existing imageedit编辑什么Send Slack message to channelslack说出动作而不是表面的对象名Lookup user by emailgetUser怎么查描述三部分构成它做什么一句话。何时使用它一到两句话包含边界 / 示例。参数说明仅当$fromAI描述里没有覆盖时才写。TOOLS.md 给出的完整范例Edit existing image: Modifies an image the user already uploaded, based on a prompt. Use when the user uploaded an image and asks for changes (color, style, composition, content). Do NOT use for generating new images from scratch — use Generate Image for that. The imageName parameter must be the storage key of the existing image as listed in your available files; do not pass the original filename or a URL.注意这段描述包含了正面用法、负面边界Do NOT use…和参数形态约束——它做的是原本会撑爆系统提示词的工作这正是它的价值所在。接线与验证侧的证据EXAMPLES.md 的无状态 Agent 核心片段中web 搜索工具这样定义{ descriptionType: manual, toolDescription: Search the web fast to fact-check a claim or find a source. Use for verifying anything from training data., query: {{ $fromAI(query, The search query, phrased to match relevant sources, string) }}, type: tavily/n8n-nodes-tavily.tavilyTool }而子 Agent 工具Idea database manager则把关键上下文写进描述甚至重复 This tool is stateless——因为路由器无法依赖共享上下文。所有工具都通过ai_tool连接Search the web: { ai_tool: [[{ node: AI Agent, type: ai_tool, index: 0 }]] }接入 Agent多个工具共享同一个ai_toolindex 0是堆叠而非分叉。工具描述作为模块化提示词任何与如何调用这个工具相关的具体说明都应该放进工具描述而不是系统提示词放在系统提示词里应移出更好的位置工具描述生成图片时优先写实摄影而非8k cinematicGenerate Image Default to realistic photography aesthetics…如果搜索工具没有结果要礼貌地总结Search Returns up to 10 results; if empty, report no matches rather than retrying broader视频工具用 9:16Generate Video Defaults to 9:16; passaspectRatio: 16:9for landscape三个理由TOOLS.md 与 SYSTEM_PROMPT.md 共同支撑可复用性Reusability——一个描述良好的工具教会每一个新 Agent 如何使用它。Token 效率Token efficiency——按工具分片的指引只在模型考虑该工具时才加载而不是每轮都烧掉 token。可维护性Maintainability——只改一处工具描述而不是改埋在 5000-token 提示词里的段落。对应的模块化分工是系统提示词负责人格、全局行为、格式规则、文件处理工具描述负责如何调用这个工具、参数含义、何时选它而非其他$fromAI描述负责该参数具体填什么值。SYSTEM_PROMPT.md还提醒当前日期永远用{{ $now }}在运行时注入硬编码的日期立刻过期。粒度一个带分支的工具而不是两个近似的工具模型在近似的工具之间选择时会困惑。如果两个工具内部有约 80% 相同用一个带分支参数的工具。Generate Image与Edit Image共享大部分逻辑 → 合并为一个用imageName参数区分空 生成非空 编辑。只有在确实不同、且描述能清晰区分时才拆两个。Send DM与Send Channel Message是明显不同的。SUBWORKFLOW_AS_TOOL.md 的一个工具、两种模式完整示例正是这个思想的实践子工作流内部用IF: imageName empty?分支空走 Gemini 生成、非空先 S3 按 key 下载再编辑最终统一输出{ imageUrl, imageKey }。Agent 通过往imageName里放什么来决定模式。如果模型在这个判别器上反复出错替代方案是两个 Tool Workflow 节点指向同一个子工作流用不同的参数接线一个硬编码空 key、一个让模型填——一个子工作流、两个描述截然不同的前门。运维要点maxIterations默认值太低必须调高Agent 有可配置的工具调用上限options.maxIterations默认值很低。多工具 Agent 连续调用很容易触顶表现为 max iterations reached 或空输出。务必调高并准备回退方案不要指望优雅恢复。SKILL.md 给出的参考专注的子 Agent 用 15宽泛的编排者用 50–200。EXAMPLES.md 中核心 Agent 设maxIterations: 50因为每轮要链式调用多个工具子 Agent 只设 15。工具调用成本每次调用至少多一次模型往返。高频调用的工具应返回精简结果——臃肿的返回会快速烧掉输入 token。工具失败处理在希望 Agent 收到错误字符串而非整体中止的场景下给工具子工作流设置onError: continueErrorOutput——Agent 收到错误后可以重试、换工具或直接上报详见 n8n-error-handling/SKILL.md。注意continueErrorOutput是两步设置既要设onError创建第二输出也要把main[1]错误输出接向真正的处理节点只做一半会在运行时静默吞掉错误。关联与延伸阅读子工作流工具的完整细节两半结构、输入契约、独立测试→ SUBWORKFLOW_AS_TOOL.md系统提示词与工具描述的分工 → SYSTEM_PROMPT.md二进制如何跨工具边界预存储 传键模式→ AGENT_TOOL_BINARY.mdCustom Code Tool 的 string-in/string-out 契约与常见错误 → n8n-code-tool/SKILL.md敏感工具的人工审阅包装与$tool.parameters字面量 → HUMAN_REVIEW.md完整可参考的节点 JSON 片段无状态核心、Slack 壳、领域子 Agent→ EXAMPLES.md最后回到那条贯穿始终的准则模型看不到你的接线——它看到的只是一个系统提示词和一堆有名有姓、有描述的工具。像设计 API 一样设计它们Agent 不听话的问题就会消失大半。赞分享AI 技能AI 插件工作流自动化流程编排【免费下载链接】n8n-skillsn8n skillset for Claude Code to build flawless n8n workflows项目地址https://gitcode.com/gh_mirrors/n8/n8n-skills点击查看免费下载相关推荐快速上手Ryujinx如何在PC上免费畅玩Switch游戏的3个技巧终极指南快速上手Ryujinx如何在PC上免费畅玩Switch游戏的3个技巧终极指南 想要在PC上体验Switch游戏的魅力吗Ryujinx Switch模拟器为你硬件仿真图形学使用 GEPA LangChainAdapter 优化 LangChain 提示词与工具 Agent 实战指南使用 GEPA LangChainAdapter 优化 LangChain 提示词与工具 Agent 实战指南 GEPA 的 LangChainAdapterAI Agent提示工程模型优化Docker 部署魔兽世界私服AzerothCore WotLK 3.3.5 容器化实战Docker 部署魔兽世界私服AzerothCore WotLK 3.3.5 容器化实战 AzerothCore 是开源 MMO 服务器框架跑魔兽世界 3.游戏开发后端上一篇Express框架终极指南从零构建高性能Node.js Web应用的7个核心技巧下一篇PhpRedis版本升级终极指南从5.x到6.x迁移的10个关键注意事项创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 n8n Agent 工具设计实战指南：四大工具类型、`$fromAI()` 参数注入与提示词级工具描述
AI 技能AI 插件工作流自动化流程编排【免费下载链接】n8n-skillsn8n skillset for Claude Code to build flawless n8n workflows项目地址https://gitcode.com/gh_mirrors/n8/n8n-skills点击查看免费下载在 n8n 中构建 AI Agent 时工具Tool是模型与外部能力之间的唯一桥梁。本指南基于 n8n-skills 仓库的 n8n-agents 技能包TOOLS.md 及其配套参考文档系统讲解四大工具类型的选型、$fromAI()参数注入机制、plumbed 参数隐藏技巧以及如何把工具名称与描述当作提示词工程来设计。读完你将掌握一套可复用的决策框架与书写规范能够显著减少Agent 不调用我的工具、参数传错等常见故障。核心原则工具的名称与描述就是提示词Agent 选择工具的方式只有一条读取工具的 name 和 description仅此而已。这两个字段都是 prompt 的一部分与参数 schema含$fromAI描述一起进入模型的上下文。正如 TOOLS.md 开篇所强调的要把工具设计当作 API 设计来对待——它做什么、何时使用、每个参数的含义、以及它会如何失败。SKILL.md 将这一条列为两个不可妥协原则之首工具名称和描述就是提示词的一部分。一个名为tool1、描述为空的工具对模型而言是不可见的——模型会跳过它、误选它或者臆造参数。而且这通常没有报错只是表现为Agent 就是不用我的工具。因此工具暴露给模型的一切文本都必须像写 API 文档一样精确。四大工具类型与 Custom Code Tooln8n 的 LangChain 节点族n8n/n8n-nodes-langchain.*为 Agent 提供了四种正规军工具形态外加一个特例Custom Code Tool。选型原则是优先选择能覆盖任务的最轻方案。1. 原生工具节点Native Tool Node预置的工具版常规节点slackTool、gmailTool、googleSheetsTool、toolCalculator、notionTool、httpRequestTool等。它与普通节点行为一致唯一区别是参数可以由 Agent 通过$fromAI()填充。维度说明优点配置最少、经过充分测试、原生体验缺点一个节点只能做一个操作多步逻辑放不进来适用场景能力恰好映射到一个节点 一个操作当原生节点缺少某个操作、或需要非标准的参数形态时可以用 HTTP Request Tool 指向该服务的 API并复用该服务的预定义凭证类型——这样既复用了已有的 OAuth / API-key 凭证又能拿到完整的 API 能力。2. 子工作流作为工具n8n/n8n-nodes-langchain.toolWorkflow任何工作流都可以变成一个带类型化$fromAI()输入的工具这是不止一个节点场景的默认选择也是 n8n 构建 Agent 能力的正统方式详见 SUBWORKFLOW_AS_TOOL.md。维度说明优点工具内拥有 n8n 全部能力——分支、错误处理、子-子工作流、原生节点、自定义逻辑可跨 Agent 复用可独立测试缺点多一层工作流边界略有延迟适用场景超过一个节点逻辑可能被复用或希望独立可测试原生 LangChain 中工具是一个函数而在 n8n 中工具可以是一整个工作流它可以按输入分支IF/Switch、调用多个 API 并聚合、自带重试与回退、调用其他子工作流、读写 Data Tables、用n8n_test_workflow与固定数据独立测试、同时被 Agent 和非 Agent 工作流复用。接线形态两半结构子工作流一侧以Execute Workflow Trigger的Define Below类型化字段模式声明输入工具侧用 Tool Workflow 节点指向子工作流并绑定参数。SUBWORKFLOW_AS_TOOL.md给出了完整 JSON 示例其中关键映射是逐输入进行的workflowInputs: { mappingMode: defineBelow, value: { imagePrompt: {{ $fromAI(imagePrompt, Detailed prompt describing the desired image, string) }}, imageName: {{ $fromAI(imageName, Storage key of an existing image to edit, or empty for new generation, string) }}, sessionId: {{ $(Chat Trigger).first().json.sessionId }} } }Agent 填充{{ $fromAI(paramName, description, string) }}——由 Agent 决定取值。Plumbed注入{{ $(SourceNode).first().json.field }}——由工作流确定值。触发器的输入模式至关重要必须是 Define Below类型化字段而非 passthrough——passthrough 没有 schemaAgent 便没有东西可供$fromAI()填充。类型强制发生在Agent 侧通过$fromAI的type参数而非触发器处允许类型为string/number/boolean/json。此外sessionId这条映射是硬性约束绝不能让sessionId进入$fromAI否则模型会编造一个 UUID必须从触发器 plumb 进来保证记忆与按会话键控的工作保持一致。Agent 能看到的只有Tool Workflow 节点的名称和 description。它看不到子工作流内部结构、子工作流自己的名字也看不到sessionId这类 plumbed 值——只有$fromAI参数会出现在工具 schema 里。这意味着你可以大改子工作流内部而不影响 Agent 所见。工具子工作流的输出契约调用方收到的是最后一个节点输出的内容必须固定一种返回形状并跨模式保持一致例如始终{ imageUrl, imageKey }输出形状是每个调用方依赖的契约。对预期内的失败如搜索无结果返回可分支的形状{ ok: false, error: no_results, message: ... }对非预期但可处理的错误认证失败、上游宕机、不可恢复输入则用Stop and Error节点抛出让 Agent 看到工具错误并自行重试/换工具/上报。子工作流内可失败节点HTTP、S3、DB应设置onError: continueErrorOutput并路由到干净的错误响应。独立测试先n8n_test_workflow({workflowId, method: prepare})确认哪些节点需要固定数据再按节点 name 构造样本项{json: {...}}然后n8n_test_workflow({workflowId, method: pinned, pinData})运行并等待最后核对输出形状。注意 routed 方法需要N8N_MCP_ACCESS_TOKEN及工作流开启 Available in MCP默认method: auto无法运行无 HTTP 触发器的子工作流。3. HTTP Request Tooln8n/n8n-nodes-langchain.toolHttpRequestHTTP Request 节点的包装器把其参数暴露给 Agent。维度说明优点任意 HTTP API 用一个节点就能变成工具缺点仅限 HTTP认证 / 重试 / 错误处理都需要自己接线适用场景调用单个外部 API且希望 Agent 直接编排一个必须知道的细节HTTP Request 自带 HTTP 层超时默认 5 分钟对慢端点需要调大options.timeout。而 Agent 工具本身没有超时——Agent 会一直等到工具返回。指向例如 Notion API复用 Notion 预定义凭证时Agent 可以自行组合 path、method、body覆盖原生节点不暴露的操作。代价是 Agent 现在在手写 API 请求更容易出错需要足够强的模型 描述里清晰的端点指引——这扩大了爆炸半径务必让用户理解这一点。4. MCP Client Tooln8n/n8n-nodes-langchain.mcpClientTool把 Agent 连接到任意 MCP 服务器两种形态外部 MCP 服务器——任意第三方或自托管 MCPGitHub、Linear、Notion、自定义内部服务。一个节点即可暴露该服务器提供的所有工具。n8n 托管的 MCP——同一实例上的某个工作流以 MCP 访问发布后用同一个 client 节点指向 n8n 的 MCP trigger URL。让一个工作流服务多个 Agent。维度说明缺点工具描述与形态来自服务器质量参差且难以调优认证与可达性自备适用场景现成维护良好的 MCP 服务器已覆盖该能力或希望一个已发布的工作流服务多个 AgentPlusCustom Code Tooln8n/n8n-nodes-langchain.toolCode纯内联计算数学、解析、格式化。其运行时契约是string in / string out、没有$fromAI、没有$helpers由 n8n-code-tool 技能管辖——写之前必须先读 n8n-code-tool/SKILL.md。经验法则只要你在代码里想要$fromAI()就应该用.toolWorkflow而不是.toolCode。典型错误包括$fromAI在 Code Tool 沙箱内不可用报No execution data available、返回对象而非字符串报The response property should be a string, but it is an object、返回工作流式数组报Wrong output type returned。决策树到底该用哪种工具TOOLS.md 给出了完整的决策树原文照录如下Capability the agent needs? ├── One native node one operation does it │ → native tool node ├── Native node missing an op / needs custom params for ONE API │ → HTTP Request Tool (with the services predefined credential) ├── More than one node, or logic that might be reused │ → Sub-workflow as tool (.toolWorkflow) ← default when in doubt ├── Pure deterministic computation, one-off, inline │ → Custom Code Tool (.toolCode) ← see n8n-code-tool └── A maintained MCP server covers it / publish n8n logic to many agents → MCP Client Tool补充两个反向判断来自 SUBWORKFLOW_AS_TOOL.md 的 When NOT to use简单单节点包装——调这个端点并返回用 HTTP Request Tool 更短。一次性、仅本 Agent 使用的纯代码逻辑——几行只存在于别处的 JS/Python 用 Custom Code Tool 即可。决策规则可复用的业务逻辑 → 子工作流一次性的 Agent 专用转换 → Code Tool。已有原生工具节点覆盖的能力——不要用子工作流去包slackTool。$fromAI()Agent 如何填充工具参数$fromAI()是 n8n真实存在的表达式辅助函数写在工具节点的参数表达式里。Agent 应该决定的参数就用它包起来sendTo: {{ $fromAI(recipient, Email address of the recipient, string) }} subject: {{ $fromAI(subject, Email subject line, concise and informative, string) }} body: {{ $fromAI(body, Email body in plain text, professional tone, string) }}形态$fromAI(paramName, description, type?, defaultValue?)参数含义要点paramName模型内部使用的参数名snake_case 或 camelCase保持一致description告诉模型要产出什么值属于 prompt 的一部分要具体格式、范围、示例typestring默认、number、boolean、json强制类型校验——类型错误会导致调用失败defaultValue模型省略该参数时使用的值可选它只携带 JSON——不能携带二进制不能有 base64、不能有文件字节即使通过非 AI 绑定也不行。对于二进制应该传一个存储键字符串让工具自行重新获取详见 AGENT_TOOL_BINARY.md。这条二进制边界是双向的硬墙模型可以通过视觉看到上传的图片passthroughBinaryImages: true但工具调用传不了文件字节工具产出的文件也不能以字节形式回给 Agent。统一的解法都是先落存储、跨 JSON 边界传键、另一侧再取。好描述与无用描述的对比原文示例✅ {{ $fromAI(imageName, Storage key for an existing image to edit, or empty for a new generation. Use the exact key shown in the system prompt; do not reconstruct or guess., string) }} ❌ {{ $fromAI(imageName, image name, string) }} // useless to the model把$fromAI的描述当作JSDoc来写——模型就是靠读它来判断该传什么值的。反过来AGENT_TOOL_BINARY.md也强调描述是模型判断取值形状的唯一指引要与你工作流实际使用的存储后端匹配只说明那一种形状不要给一长串可能方案。Plumbed 参数隐藏不该由 Agent 决定的东西并非每个参数都必须走$fromAI。任何参数都可以从工作流上下文确定性地填充而且plumbed 值对 Agent 完全不可见——不出现在工具 schema 里模型产生的任何内容都无法影响它reason: {{ $fromAI(reason, Why the user is requesting a refund, string) }} // agent-filled customerId: {{ $(Chat Trigger).first().json.user.id }} // hidden maxRefund: {{ $(Get user tier).first().json.refundLimit }} // hidden idempotencyKey:{{ $(Chat Trigger).first().json.sessionId }} // hidden应该 plumb注入三类东西身份Identity——userId、customerId、已认证操作者、租户范围。权限边界Authority limits——退款上限、层级标记、允许的区域。关联 IDCorrelation IDs——sessionId、幂等键、trace ID。给 Agent 一个按钮而不是一个方向盘是这一原则的最强形态一个敏感工具可以拥有零个$fromAI参数——Refund order 工具的orderId来自触发器、amount来自取回的订单记录、actor来自会话全部 plumbed。Agent 物理上不可能退错订单它只能决定是否扣动扳机。对于既需要确定性参数、又需要人工签批的动作配合 HUMAN_REVIEW.md 使用——审阅节点插在工具与 Agent 之间的ai_tool链路上审批消息必须用字面量{{ $tool.parameters.name }}展示真实参数绝不能用$fromAI()让模型复述否则人类审批的是模型编造的转述而非即将发出的调用。工具名称与描述即提示词模型每一轮都会执行这样的选择过程拿到系统提示词、对话历史、以及工具列表。对每个工具读取name description 参数 schema含$fromAI描述。挑选描述与当前任务最匹配的工具。坏的名称和描述会造成坏的选型——通常是静默的模型就是不调用你的工具或者用垃圾参数去调另一个工具。没有任何报错。命名动词开头、具体明确好坏为什么Search customer databasequery/tool1通用名称什么也说明不了Generate image with VeoimageGen哪个生成器Edit existing imageedit编辑什么Send Slack message to channelslack说出动作而不是表面的对象名Lookup user by emailgetUser怎么查描述三部分构成它做什么一句话。何时使用它一到两句话包含边界 / 示例。参数说明仅当$fromAI描述里没有覆盖时才写。TOOLS.md 给出的完整范例Edit existing image: Modifies an image the user already uploaded, based on a prompt. Use when the user uploaded an image and asks for changes (color, style, composition, content). Do NOT use for generating new images from scratch — use Generate Image for that. The imageName parameter must be the storage key of the existing image as listed in your available files; do not pass the original filename or a URL.注意这段描述包含了正面用法、负面边界Do NOT use…和参数形态约束——它做的是原本会撑爆系统提示词的工作这正是它的价值所在。接线与验证侧的证据EXAMPLES.md 的无状态 Agent 核心片段中web 搜索工具这样定义{ descriptionType: manual, toolDescription: Search the web fast to fact-check a claim or find a source. Use for verifying anything from training data., query: {{ $fromAI(query, The search query, phrased to match relevant sources, string) }}, type: tavily/n8n-nodes-tavily.tavilyTool }而子 Agent 工具Idea database manager则把关键上下文写进描述甚至重复 This tool is stateless——因为路由器无法依赖共享上下文。所有工具都通过ai_tool连接Search the web: { ai_tool: [[{ node: AI Agent, type: ai_tool, index: 0 }]] }接入 Agent多个工具共享同一个ai_toolindex 0是堆叠而非分叉。工具描述作为模块化提示词任何与如何调用这个工具相关的具体说明都应该放进工具描述而不是系统提示词放在系统提示词里应移出更好的位置工具描述生成图片时优先写实摄影而非8k cinematicGenerate Image Default to realistic photography aesthetics…如果搜索工具没有结果要礼貌地总结Search Returns up to 10 results; if empty, report no matches rather than retrying broader视频工具用 9:16Generate Video Defaults to 9:16; passaspectRatio: 16:9for landscape三个理由TOOLS.md 与 SYSTEM_PROMPT.md 共同支撑可复用性Reusability——一个描述良好的工具教会每一个新 Agent 如何使用它。Token 效率Token efficiency——按工具分片的指引只在模型考虑该工具时才加载而不是每轮都烧掉 token。可维护性Maintainability——只改一处工具描述而不是改埋在 5000-token 提示词里的段落。对应的模块化分工是系统提示词负责人格、全局行为、格式规则、文件处理工具描述负责如何调用这个工具、参数含义、何时选它而非其他$fromAI描述负责该参数具体填什么值。SYSTEM_PROMPT.md还提醒当前日期永远用{{ $now }}在运行时注入硬编码的日期立刻过期。粒度一个带分支的工具而不是两个近似的工具模型在近似的工具之间选择时会困惑。如果两个工具内部有约 80% 相同用一个带分支参数的工具。Generate Image与Edit Image共享大部分逻辑 → 合并为一个用imageName参数区分空 生成非空 编辑。只有在确实不同、且描述能清晰区分时才拆两个。Send DM与Send Channel Message是明显不同的。SUBWORKFLOW_AS_TOOL.md 的一个工具、两种模式完整示例正是这个思想的实践子工作流内部用IF: imageName empty?分支空走 Gemini 生成、非空先 S3 按 key 下载再编辑最终统一输出{ imageUrl, imageKey }。Agent 通过往imageName里放什么来决定模式。如果模型在这个判别器上反复出错替代方案是两个 Tool Workflow 节点指向同一个子工作流用不同的参数接线一个硬编码空 key、一个让模型填——一个子工作流、两个描述截然不同的前门。运维要点maxIterations默认值太低必须调高Agent 有可配置的工具调用上限options.maxIterations默认值很低。多工具 Agent 连续调用很容易触顶表现为 max iterations reached 或空输出。务必调高并准备回退方案不要指望优雅恢复。SKILL.md 给出的参考专注的子 Agent 用 15宽泛的编排者用 50–200。EXAMPLES.md 中核心 Agent 设maxIterations: 50因为每轮要链式调用多个工具子 Agent 只设 15。工具调用成本每次调用至少多一次模型往返。高频调用的工具应返回精简结果——臃肿的返回会快速烧掉输入 token。工具失败处理在希望 Agent 收到错误字符串而非整体中止的场景下给工具子工作流设置onError: continueErrorOutput——Agent 收到错误后可以重试、换工具或直接上报详见 n8n-error-handling/SKILL.md。注意continueErrorOutput是两步设置既要设onError创建第二输出也要把main[1]错误输出接向真正的处理节点只做一半会在运行时静默吞掉错误。关联与延伸阅读子工作流工具的完整细节两半结构、输入契约、独立测试→ SUBWORKFLOW_AS_TOOL.md系统提示词与工具描述的分工 → SYSTEM_PROMPT.md二进制如何跨工具边界预存储 传键模式→ AGENT_TOOL_BINARY.mdCustom Code Tool 的 string-in/string-out 契约与常见错误 → n8n-code-tool/SKILL.md敏感工具的人工审阅包装与$tool.parameters字面量 → HUMAN_REVIEW.md完整可参考的节点 JSON 片段无状态核心、Slack 壳、领域子 Agent→ EXAMPLES.md最后回到那条贯穿始终的准则模型看不到你的接线——它看到的只是一个系统提示词和一堆有名有姓、有描述的工具。像设计 API 一样设计它们Agent 不听话的问题就会消失大半。赞分享AI 技能AI 插件工作流自动化流程编排【免费下载链接】n8n-skillsn8n skillset for Claude Code to build flawless n8n workflows项目地址https://gitcode.com/gh_mirrors/n8/n8n-skills点击查看免费下载相关推荐快速上手Ryujinx如何在PC上免费畅玩Switch游戏的3个技巧终极指南快速上手Ryujinx如何在PC上免费畅玩Switch游戏的3个技巧终极指南 想要在PC上体验Switch游戏的魅力吗Ryujinx Switch模拟器为你硬件仿真图形学使用 GEPA LangChainAdapter 优化 LangChain 提示词与工具 Agent 实战指南使用 GEPA LangChainAdapter 优化 LangChain 提示词与工具 Agent 实战指南 GEPA 的 LangChainAdapterAI Agent提示工程模型优化Docker 部署魔兽世界私服AzerothCore WotLK 3.3.5 容器化实战Docker 部署魔兽世界私服AzerothCore WotLK 3.3.5 容器化实战 AzerothCore 是开源 MMO 服务器框架跑魔兽世界 3.游戏开发后端上一篇Express框架终极指南从零构建高性能Node.js Web应用的7个核心技巧下一篇PhpRedis版本升级终极指南从5.x到6.x迁移的10个关键注意事项创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考