二、操作说明
在工具节点中，你需要完成以下配置：基础信息、API 参数、输出变量，以及异常处理（可选）。这些配置共同决定了节点在运行时如何调用外部服务、处理响应数据，并与其他节点交互。
四、接口链接
传入 API 接口的 URL。你也可以通过输入"/"符号引用前序节点内变量中的链接信息。
五、授权方式
API 使用权限，支持“无需授权”、 “APIKey” 和“腾讯云”三种。
APIKey 授权：
APIKey 授权是一种基于唯一标识符（API Key）的轻量级身份验证机制，用于验证客户端（例如：应用程序、用户或服务）对 API 的访问权限。API Key 通常是一串随机生成的字符，由 API 提供商分配，客户端在调用 API 时需将其包含在请求头或请求参数中，以证明其合法性。配置如下：
| 配置 | 说明 |
| 密钥位置 | 支持选择 “header” 和 “query”，用于配置填写 APIKey 的位置 |
| 密钥参数名 | APIKey 的名称 |
| 密钥值 | APIKey 的具体值 |
腾讯云授权
适用于调用腾讯云产品 API 的场景，腾讯云 API 会对每一个请求进行身份验证，用户需要使用安全凭证发起请求，以确保请求由持有合法访问密钥的主体发起。详细的密钥获取信息请参阅控制台 公共参数 页面。可通过 云 API 密钥 进行密钥获取。具体配置如下：
| 配置 | 说明 |
| SecretId | 用于标识 API 调用者身份，可以类比为用户名 |
| SecretKey | 用于验证 API 调用者的身份，可以类比为密码 |
六、请求方式
配置该 API 工具的请求方式，支持 GET、POST 以及 PUT、DELETE、PATCH、HEAD、OPTIONS 共七种。
| 配置 | 说明 |
| GET | 用于从服务器获取（请求）数据，通常用于查询操作。适用场景：● 获取网页、图片、API 数据等静态资源● 搜索引擎查询● 无敏感信息的简单数据传递 |
| POST | 用于向服务器提交（发送）数据，通常用于创建或更新资源。适用场景：● 提交表单数据，如用户注册、登录● 上传文件或大型数据● 执行非查询类操作 |
| PUT | 用于向服务器提交数据以创建或替换资源。通常用于更新现有资源或者创建新资源（如果资源不存在）。如果资源已经存在，PUT 会覆盖现有资源；如果资源不存在，则会创建新资源。适用场景：● 更新用户信息，如修改用户的个人资料● 替换资源的内容，如上传新的文件内容 |
| DELETE | 用于从服务器删除指定的资源，通常用于移除数据或取消操作。适用场景：● 删除用户账号、文章、评论等动态资源● 取消已提交的订单或预约● 清理临时文件或缓存数据 |
| PATCH | 用于向服务器提交部分数据以更新现有资源，而不是替换整个资源。与 PUT 不同，PATCH 仅修改部分数据，而不是完整资源。适用场景：● 更新用户的部分信息，如仅修改用户名或电子邮件地址● 对资源进行增量更新，例如调整某个配置项的数值 |
| HEAD | 用于请求服务器返回响应头部信息，但不返回响应体。常用于获取资源的元数据（如文件大小、类型等），用于检查资源是否存在或获取资源的基本信息。适用场景：● 检查文件是否存在而不下载文件内容● 获取资源的修改时间、大小、类型等信息 |
| OPTIONS | 用于询问服务器支持哪些 HTTP 方法或者查询服务器的通信选项。常用于在跨域请求中发送预检请求，以确定服务器是否允许某种类型的请求。适用场景：● 跨域请求时，浏览器会自动发送 OPTIONS 请求，以确认是否允许特定的请求方法● 确认服务器支持哪些 HTTP 方法，例如 GET、POST、PUT 等 |
七、调用方式
支持流式与非流式两种调用方式。
·非流式调用：请求接口后一次性返回完整结果，适用于普通接口调用或任务执行场景。
·流式调用：支持调用 SSE（Server-Sent Events） 格式的接口。请求接口后，后台完成数据拼接后统一输出。
·增量解析：每次接收的内容为独立完整片段，例如「今天」「天气」「很好」；
·覆盖解析：每次接收的内容基于上一次结果叠加更新，例如「今」「今天」「今天天气很好」。
流式调用适用于处理持续输出类接口（如聊天或生成类 API），但最终展示结果为整合后的完整文本。
如需查看示例，请参考文末的 POST 请求示例 2：在工作流内使用流式方式调用 ADP 应用。
八、基础信息添加
除了手动填写工具节点的基础信息，支持通过 JSON、cURL 和 YAML 代码自动添加基础信息。
通过 YAML 添加
OpenAPI 是一种用于描述 RESTful API 的标准化规范，可用于定义接口的结构、请求与响应格式以及认证方式等内容。YAML 是 OpenAPI 中常用的描述格式，语法简洁、可读性高，便于快速配置和维护接口。YAML 格式填写示例如下：
openapi: "3.0.0"info: title: "测试API" version: "1.0.0" description: "请在此填入插件描述"servers: – url: "https://example.com/api" description: "请在此填入插件描述"paths: "/weatherInfo": get: summary: "API名称" description: "请在此填入插件下面的API描述" operationId: "getWeatherInfo" parameters: – name: "city" in: "query" description: "参数说明" required: true schema: type: "string" responses: "200": description: "成功的响应" content: application/json: schema: type: "object" properties: status: type: "integer" description: "返回状态" enum: [0, 1] "400": description: "错误的请求" "401": description: "未授权" "500": description: "服务器内部错误"
填写完成后，单击解析，即可自动填写对应的参数。
通过 cURL 添加
支持通过 cURL 命令添加基础信息。OpenAPIcURL 是一个命令行工具，用于向服务器发送请求。它支持多种协议（如 HTTP、HTTPS、FTP 等），并且可以通过命令行发送 HTTP 请求，用于测试和调试 API。
cURL 的 API 示例如下：
curl -X POST https://api.example.com/users -H "Content-Type: application/json" -d '{"name": "John", "email": "john@example.com"}'
通过 JSON 添加
支持通过 JSON 添加基础信息。JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，通常用于 API 的请求和响应体。JSON 格式的数据具有键值对结构，适用于表示结构化的数据。
JSON 的 API 示例如下：
{ "openapi": "3.0.0", "info": { "title": "示例API", "description": "演示OpenAPI规范的完整结构", "version": "1.0.0", "contact": { "name": "API支持", "email": "support@example.com" } }, "servers": [ { "url": "https://api.example.com/v1", "description": "生产环境" } ], "paths": { "/users": { "get": { "summary": "获取用户列表", "responses": { "200": { "description": "用户数组", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } } }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "responses": { "201": { "description": "创建成功" } } } } }}
九、API 参数
填写该 API 调用所需的 Header、Query 和 Body 参数。请根据接口文档或实际业务需求，配置相应的参数名称与取值来源，以确保请求能够正确执行。
| 配置 | 说明 |
| 变量名称 | 该变量的名称，只能包含字母、数字或下划线，并且以字母或下划线开头，必填 |
| 变量描述 | 该变量的说明信息，非必填 |
| 数据来源 | 该变量的数据来源，支持“引用”“输入”两种选项。“引用”可选择前序所有节点的输出变量，“输入”可手动填入固定值，必填 |
| 变量类型 | 该变量的数据类型，不可选择，默认为引用的变量类型或输入的 string 类型 |
十、请求体格式
对 body 请求体，支持 JSON、form-data、x-www-form-urlencoded、raw text 和 binary 五种格式输入。
注意：说明：
注意：仅当请求方式为 POST、PUT 和 PATCH 时，才有 body 请求体。
| 配置 | 说明 |
| JSON | 结构化数据格式，使用键值对表示对象，支持嵌套和数组结构，适合传输结构化数据 |
| form-data | 将数据分割为多个部分，每个部分包含独立的内容类型和编码，支持混合文本和二进制数据，适合文件上传、表单提交和混合类型数据传输 |
| x-www-form-urlencoded | 将数据编码为键值对（ key = value ），多个值用 & 连接，特殊字符进行 URL 编码，适合无文件的简单表单提交、传统Web 表单和兼容旧系统接口 |
| raw text | 纯文本数据，无任何格式处理，按原始字节流传输，适合发送自定义文本消息、传输代码片段或非结构化数据 |
| binary | 原始二进制数据流，无元数据描述，按字节传输，适合上传未知类型文件 |
十一、输出变量
经过该节点处理后的输出变量默认为空，用户可根据需要手动添加。手动添加时，变量名称应与该 API 的返回参数名称保持一致，以便正确映射响应数据。系统同时会生成一个运行状态字段：
·Error（类型：object）——用于记录运行过程中的异常信息；当节点正常执行时，该字段为空。
在完成基础信息与 API 参数配置后，系统还支持自动解析接口返回结构，并生成对应的输出变量，方便后续节点直接引用。
十二、异常处理
当接口调用失败或返回异常时，可手动开启异常处理功能（异常处理默认关闭）。通过配置异常重试策略与异常处理方式，你可以控制流程在出现错误时的行为，例如自动重试或输出指定的错误信息，确保节点执行的稳定性与可追溯性。详细配置如下：
| 配置 | 说明 |
| 最大重试次数 | 节点运行异常时重新运行的最大次数。重试超过设定次数，认为该节点调用失败，执行下方的异常处理方式，默认为3次 |
| 重试时间间隔 | 每次重新运行的时间间隔，默认为1秒 |
| 异常处理方式 | 支持“输出特定内容”、“执行异常流程”和“中断流程”三种 |
| 异常情况的输出变量 | 选择异常处理方式为“输出特定内容”时，超过最大重试次数后节点返回的输出变量 |
选择异常处理方式为“输出特定内容”时，发生异常后工作流不会中断，节点异常重试后直接返回用户在输出内容设置的输出变量及变量值；
选择异常处理方式为“执行异常流程”时，发生异常后工作流不会中断，节点异常重试后执行用户自定义的异常处理流程；
选择异常处理方式为“中断流程”时，没有更多设置项，发生异常后工作流执行中断。
十三、异步调用
工具节点的异步调用指在执行任务时，用户无需等待工具节点调用结束即可继续执行后续流程的调用方式。能够有效提升系统的吞吐量和响应速度，同时降低资源阻塞风险。目前工具节点支持两种调用模式：轮询调用与回调调用。
轮询调用与回调调用的区别如下：
·轮询调用：ADP 主动定期查询外部系统执行结果。
·回调调用：外部系统执行完成后，通过 ADP 提供的地址主动返回结果。
十四、轮询调用
选择“调用类型”为“轮询”，即可开启轮询调用，满足异步任务运行等场景需求。用户可手动配置轮询条件。
| 配置 | 说明 |
| 轮询时间间隔 | 节点进行两次查询之间相隔的时间。默认值 1s，最大值 10s |
| 最长轮询时间 | 节点进行轮询的总时长，默认值为 10s，最大值 600s。节点运行时间超过最长轮询时间后，认为该节点执行失败 |
| 轮询结束条件 | 停止轮询的规则或条件，不满足条件时，接着进行轮询。当条件被满足时，结束轮询，执行下一节点 |
用户可手动设置轮询结束的条件，支持选择两种条件判断模式：
1. 选择 “大模型语义判断” 时，由模型智能解析当前场景是否满足预设条件，进而自动决策轮询是否继续。
2. 选择 “严格精准判断” 时，需完全匹配退出轮询的预设条件，系统才会终止轮询流程，确保判断逻辑的一致性与准确性。
用户可手动配置轮询调用时使用的模型，仅支持选择该账号具有权限的大模型。
十五、回调调用
选择“调用类型”为“回调”，即可开启回调调用，满足异步任务运行等场景需求。用户可手动配置回调时间。
| 配置 | 说明 |
| 最长等待时间 | 节点进行回调的等待时长，时间单位支持秒/分，默认选中秒；在选中秒为时间单位时，默认值为 10s，最大值 600s。选中分为时间单位时，默认值1min，最大值10min |
注意：说明：
注意：异步调用的优先级低于异常处理的优先级，若用户同时开启了异常处理与异步调用，当出现异常情况时，根据异常处理中的“异常处理方式”执行，可跳过未运行结束的异步调用。
十七、GET 请求的示例：实时天气
查询特定城市的实时天气，city 为必填项，且放置在请求的 query 中。示例配置如下：
YAML 导入的示例如下：
openapi: "3.0.0"info: title: "天气查询" version: "1.0.0" description: "用于天气查询的插件"servers: – url: "https://example.example/api" description: "查询特定城市的实时天气情况"paths: "/weatherInfo": get: summary: "查询特定城市实时天气的插件" operationId: "getWeatherInfoId" description: "查询特定城市的实时天气情况" parameters: – name: "city" in: "query" description: "待查询天气的城市" required: true schema: type: "string" responses: "200": description: "成功的响应" content: application/json: schema: type: "object" properties: weather: type: "string" description: "天气描述" status: type: "integer" description: "接口调用状态" "400": description: "错误的请求" "401": description: "未授权" "500": description: "服务器内部错误"
注意：示例仅用作展示 API 的配置过程，无法直接调用，请根据示例替换成你自己的 API 。
十八、POST 请求示例 1：查询客户订单
查询特定客户 ID 的订单列表， customerId 为必填项， customerName 和 customerEmail 为非必填项，放置在请求的 body 中。示例配置如下：
YAML 导入的示例如下：
openapi: "3.0.0"info: title: "客户订单查询" version: "1.0.0" description: "通过客户ID查询客户的所有订单"servers: – url: "https://example.example/api" description: "查询特定客户的订单信息"paths: /orderList: post: summary: "查询特定客户的订单列表" operationId: "getOrderList" description: "通过客户ID查询客户的所有订单" requestBody: required: true description: "请求体中包含客户ID" content: application/json: schema: type: object properties: customerId: type: integer description: "客户ID，必填项" customerName: type: string description: "客户姓名（可选）" customerEmail: type: string description: "客户邮箱（可选）" required: – customerId responses: "200": description: "查询成功" content: application/json: schema: type: object properties: orderList: type: array description: "订单列表" items: type: object properties: orderId: type: integer description: "订单ID" status: type: string description: "订单状态" amount: type: number description: "订单金额" status: type: integer description: "接口调用状态" enum: [0, 1] "400": description: "错误的请求" "401": description: "未授权" "500": description: "服务器内部错误"
注意：示例仅用作展示 API 的配置过程，无法直接调用，请根据示例替换成你自己的 API 。
十九、POST 请求示例 2：在工作流内使用流式方式调用 ADP 应用
以下示例演示如何在工具节点中以 流式（SSE） 方式调用某个智能体应用接口。
示例接口：https://wss.lke.cloud.tencent.com/v1/qbot/chat/sse。如需了解更多智能体应用接口请求字段说明，请参见接口文档。
20、1. 基础配置
在工具节点中配置 POST 请求方式与流式调用方式。
注意：工具节点内部不会实时渲染流式内容，而是后台自动拼接完整结果。如需查看流式输出效果，请在节点后追加「回复节点」，详情见后文。
21、2. Body 示例填写
参考接口文档或 cURL 示例，按需在 Body 中填写对应字段。
示例 cURL:
curl –location 'https://wss.lke.cloud.tencent.com/v1/qbot/chat/sse' \\–header 'Content-Type: application/json' \\–data '{ "session_id":"a29bae68-cb1c-489d-8097-6be78f136acf", "bot_app_key":"请自行获取应用对应的key", "visitor_biz_id":"a29bae68-cb1c-489d-8097-6be78f136acf", "content":"哪吒2票房", "incremental": true, "streaming_throttle": 10, "visitor_labels": [], "custom_variables":{}, "search_network":"disable", "stream":"enable", "workflow_status":"disable", "tcadp_user_id":""}'
22、Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64Runtime Version: GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
根据请求示例，在工具节点 Body 中填写例如以下参数：
session_id: a29bae68bot_app_key: your-keyvisitor_biz_id: random-idcontent: 用户问题
23、3. 输出变量配置
当 SSE 返回类似以下结构时：
{ "Body": "event:reply data:{\\"type\\":\\"reply\\",\\"payload\\":{\\"content\\":\\"fdsaijofjioasdgj\\", … }}"}
分析输出的内容格式，在输出变量里按照对应的格式解析对应的字段。参考以下格式填写：
根据接口实际的返回情况选择对应的解析方式：
·增量解析：每次接收的内容为独立完整片段，例如「今天」→「天气」→「很好」。
·覆盖解析：每次接收的内容基于上一次结果叠加更新，例如「今」→「今天」→「今天天气很好」。
工具节点最终输出为平台自动拼接后的整段文本。
24、4. 如何在平台内查看真正的流式效果
在工具节点后添加一个“回复节点”，并在回复内容中插入工具节点的输出变量，例如 {{result}}。
单击工作流右上角的调试，运行后即可看到 SSE 拼接后的最终回复内容。
25、常见问题
如何配置 Bearer 鉴权？
工具节点支持 Bearer 鉴权。请选择 “API Key” 授权方式，在密钥值处填写 “Bearer [你的 API 密钥值]”。