腾讯云智能体开发平台工具节点

节点功能
工具节点属于信息处理类节点，支持在节点内设置自定义 API。工作流运行至该节点时，系统将自动调用 API 并输出返回结果。
﻿
﻿
﻿
操作说明
在工作节点中，您需要完成以下配置：基础信息、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秒
异常处理方式
支持“输出特定内容”、“执行异常流程”和“中断流程”三种
异常情况的输出变量
选择异常处理方式为“输出特定内容”时，超过最大重试次数后节点返回的输出变量
﻿
﻿
﻿
选择异常处理方式为“输出特定内容”时，发生异常后工作流不会中断，节点异常重试后直接返回用户在输出内容设置的输出变量及变量值；
选择异常处理方式为“执行异常流程”时，发生异常后工作流不会中断，节点异常重试后执行用户自定义的异常处理流程；
﻿
﻿
﻿
选择异常处理方式为“中断流程”时，没有更多设置项，发生异常后工作流执行中断。
轮询调用
可手动开启轮询调用（默认为关闭），满足异步任务运行等场景需求。用户可手动配置轮询条件。
配置
说明
轮询时间间隔
节点进行两次查询之间相隔的时间。默认值 1s，最大值 10s。
最长轮询时间
节点进行轮询的总时长，默认值为 10s，最大值 600s。节点运行时间超过最长轮询时间后，认为该节点执行失败。
轮询结束条件
停止轮询的规则或条件，不满足条件时，接着进行轮询。当条件被满足时，结束轮询，执行下一节点。
﻿
﻿
﻿
说明：
轮询的优先级低于异常处理的优先级，若用户同时开启了异常处理与轮询调用，当出现异常情况时，根据异常处理中的“异常处理方式”执行，可跳过未进行完的轮询。
应用示例
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。如需了解更多智能体应用接口请求字段说明，请参见接口文档。
1. 基础配置
在工具节点中配置 POST 请求方式与流式调用方式。
注意：工具节点内部不会实时渲染流式内容，而是后台自动拼接完整结果。如需查看流式输出效果，请在节点后追加「回复节点」，详情见后文。
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":""
}'
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
根据请求示例，在工具节点 Body 中填写例如以下参数：
session_id: a29bae68
bot_app_key: your-key
visitor_biz_id: random-id
content: 用户问题
﻿
﻿
﻿
3. 输出变量配置
当 SSE 返回类似以下结构时：
{
  "Body": "event:reply
  data:{\\"type\\":\\"reply\\",\\"payload\\":{\\"content\\":\\"fdsaijofjioasdgj\\", ... }}"
}
分析输出的内容格式，在输出变量里按照对应的格式解析对应的字段。参考以下格式填写：
﻿
﻿
﻿
根据接口实际的返回情况选择对应的解析方式：
增量解析：每次接收的内容为独立完整片段，例如「今天」→「天气」→「很好」。
覆盖解析：每次接收的内容基于上一次结果叠加更新，例如「今」→「今天」→「今天天气很好」。
工具节点最终输出为平台自动拼接后的整段文本。
4. 如何在平台内查看真正的流式效果
在工具节点后添加一个“回复节点”，并在回复内容中插入工具节点的输出变量，例如 {{result}}。
﻿
﻿
﻿
单击工作流右上角的调试，运行后即可看到 SSE 拼接后的最终回复内容。
﻿
﻿
﻿
常见问题
如何配置 Bearer 鉴权？
工具节点支持 Bearer 鉴权。请选择 “API Key” 授权方式，在密钥值处填写 “Bearer [您的 API 密钥值]”。

配置	说明
密钥位置	支持选择 “header” 和 “query”，用于配置填写 APIKey 的位置
密钥参数名	APIKey 的名称
密钥值	APIKey 的具体值

配置	说明
SecretId	用于标识 API 调用者身份，可以类比为用户名
SecretKey	用于验证 API 调用者的身份，可以类比为密码

配置	说明
GET	用于从服务器获取（请求）数据，通常用于查询操作。适用场景： ● 获取网页、图片、API 数据等静态资源 ● 搜索引擎查询 ● 无敏感信息的简单数据传递
POST	用于向服务器提交（发送）数据，通常用于创建或更新资源。适用场景： ● 提交表单数据，如用户注册、登录 ● 上传文件或大型数据 ● 执行非查询类操作
PUT	用于向服务器提交数据以创建或替换资源。通常用于更新现有资源或者创建新资源（如果资源不存在）。如果资源已经存在，PUT 会覆盖现有资源；如果资源不存在，则会创建新资源。适用场景： ● 更新用户信息，如修改用户的个人资料 ● 替换资源的内容，如上传新的文件内容
DELETE	用于从服务器删除指定的资源，通常用于移除数据或取消操作。适用场景： ● 删除用户账号、文章、评论等动态资源 ● 取消已提交的订单或预约 ● 清理临时文件或缓存数据
PATCH	用于向服务器提交部分数据以更新现有资源，而不是替换整个资源。与 PUT 不同，PATCH 仅修改部分数据，而不是完整资源。适用场景： ● 更新用户的部分信息，如仅修改用户名或电子邮件地址 ● 对资源进行增量更新，例如调整某个配置项的数值
HEAD	用于请求服务器返回响应头部信息，但不返回响应体。常用于获取资源的元数据（如文件大小、类型等），用于检查资源是否存在或获取资源的基本信息。适用场景： ● 检查文件是否存在而不下载文件内容 ● 获取资源的修改时间、大小、类型等信息
OPTIONS	用于询问服务器支持哪些 HTTP 方法或者查询服务器的通信选项。常用于在跨域请求中发送预检请求，以确定服务器是否允许某种类型的请求。适用场景： ● 跨域请求时，浏览器会自动发送 OPTIONS 请求，以确认是否允许特定的请求方法 ● 确认服务器支持哪些 HTTP 方法，例如 GET、POST、PUT 等

配置	说明
变量名称	该变量的名称，只能包含字母、数字或下划线，并且以字母或下划线开头，必填
变量描述	该变量的说明信息，非必填
数据来源	该变量的数据来源，支持“引用”“输入”两种选项。“引用”可选择前序所有节点的输出变量，“输入”可手动填入固定值，必填
变量类型	该变量的数据类型，不可选择，默认为引用的变量类型或输入的 string 类型

配置	说明
JSON	结构化数据格式，使用键值对表示对象，支持嵌套和数组结构，适合传输结构化数据。
form-data	将数据分割为多个部分，每个部分包含独立的内容类型和编码，支持混合文本和二进制数据，适合文件上传、表单提交和混合类型数据传输。
x-www-form-urlencoded	将数据编码为键值对（ key = value ），多个值用 & 连接，特殊字符进行 URL 编码，适合无文件的简单表单提交、传统Web 表单和兼容旧系统接口。
raw text	纯文本数据，无任何格式处理，按原始字节流传输，适合发送自定义文本消息、传输代码片段或非结构化数据。
binary	原始二进制数据流，无元数据描述，按字节传输，适合上传未知类型文件。

配置	说明
最大重试次数	节点运行异常时重新运行的最大次数。重试超过设定次数，认为该节点调用失败，执行下方的异常处理方式，默认为3次
重试时间间隔	每次重新运行的时间间隔，默认为1秒
异常处理方式	支持“输出特定内容”、“执行异常流程”和“中断流程”三种
异常情况的输出变量	选择异常处理方式为“输出特定内容”时，超过最大重试次数后节点返回的输出变量

配置	说明
轮询时间间隔	节点进行两次查询之间相隔的时间。默认值 1s，最大值 10s。
最长轮询时间	节点进行轮询的总时长，默认值为 10s，最大值 600s。节点运行时间超过最长轮询时间后，认为该节点执行失败。
轮询结束条件	停止轮询的规则或条件，不满足条件时，接着进行轮询。当条件被满足时，结束轮询，执行下一节点。

工具节点

本页目录：

节点功能

操作说明

基础信息

接口链接

授权方式

APIKey 授权：

腾讯云授权

请求方式

调用方式

基础信息添加

通过 YAML 添加

API 参数

请求体格式

输出变量

异常处理

轮询调用

应用示例

GET 请求的示例：实时天气

POST 请求示例 1：查询客户订单

POST 请求示例 2：在工作流内使用流式方式调用 ADP 应用

1. 基础配置

2. Body 示例填写

Running Environment

3. 输出变量配置

4. 如何在平台内查看真正的流式效果

常见问题