用途:指导在 n8n 的 Custom Code Tool(节点类型 @n8n/n8n-nodes-langchain.toolCode)中编写 JavaScript 或 Python 代码。该节点由 AI Agent(LangChain)调用,不是工作流里的普通 Code 节点,两者包、调用方与运行时契约都不同。
主要能力与契约:输入变量固定为 query(JS)或 _query(Python),不可改名;返回值必须是字符串,数字会自动转换,返回对象或数组会报错,结构化结果建议用 JSON.stringify()。工具名需为字母、数字、下划线(v1.1+),描述要写明何时调用。
两种输入模式:默认非结构化(specifyInputSchema: false),AI 传入单个字符串,可让其传 JSON 字符串再解析;结构化模式(specifyInputSchema: true)下工具变为 LangChain DynamicStructuredTool,可用 schemaType: "fromJson" + jsonSchemaExample 或 "manual" + inputSchema 定义模式,字段直接通过 query 访问。
限制:沙箱中不可用 $fromAI()、$input、$json、$node、this.helpers.httpRequest()、$jmespath()、getContext、$getWorkflowStaticData 等;需要 HTTP 调用、跨调用状态或多参数类型化输入时,应改用 HTTP Request Tool 或 toolWorkflow。错误信息会返回给 LLM,建议写出可指导重试的报错内容。
适用场景:纯确定性计算、解析、格式化、校验等轻量转换,且希望代码内联在工作流中。
使用方式:将节点通过 ai_tool 连接接入 AI Agent,并用 LLM 实际会发送的输入类型进行测试。更多细节见资料提到的 INPUT_SCHEMA.md 与 ERROR_PATTERNS.md。