# 插件 插件节点是工作流中实现第三方能力调用的核心组件之一，允许工作流通过调用插件来执行特定功能任务。 尽管大语言模型（LLM）具备强大的自然语言处理与推理能力，但存在两大局限：信息滞后（无法获取训练截止日期之后的实时信息）和行动力缺失（无法直接与外部系统交互）。插件节点正是突破这些局限的关键桥梁，每个插件本质上是经过标准化封装的API或者函数功能的工具集合，提供即插即用的模块化服务，让工作流具备连接外部世界的能力。 插件与工具的关系：插件是集成了一个或多个工具的功能集合，定义了这些工具共用的基础属性（如服务域名、鉴权方式）；工具是插件内具体的执行单元，每个工具对应一个独立的功能。工作流中添加插件节点时，实际调用的是插件中某一个特定工具。 插件与工具层级关系：插件 → \[工具1, 工具2, ...\]（每个工具对应一个独立功能） 插件节点的执行原理：插件节点执行时，平台服务器根据插件定义中的API地址和请求方式，将输入参数组装为HTTP请求发送给目标服务，等待响应后将返回数据映射为输出参数传递给下游节点。 数据流转过程：上游节点输出 → 输入参数映射 → 平台发起API请求 → 接收响应 → 输出参数映射 → 下游节点获取 相关文档： [示例：创建联网搜索插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0124.html) [基于API创建插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0126.html) #### 添加节点 工作流中支持添加两种类型的插件。 表1插件类型 | 插件分类 | 说明 | 获取方式 | |:---|:---|:---| | 插件广场 | 由AgentArts平台预置至"资产广场"的官方插件，由平台提供技术支持和维护。 | 来自"资产广场 \> 插件广场"的插件，注意部分插件需要配置鉴权或收费。 | | 组件库插件 | 开发者自行创建的插件，支持API类型（封装外部RESTful API）和函数类型（在平台沙箱中运行代码脚本）。 | 通过"组件库 \> 插件"入口自行配置创建。 | 如果是需要调用通用的第三方成熟公共服务（如地图查询、天气预报、通用翻译等），推荐优先选择"插件广场"中的官方预置插件，即插即用。 如果是需要对接企业内部专有的业务系统、未公开的微服务或执行自研的代码脚本，推荐前往"组件库 \> 插件"页面自行配置创建"组件库插件"。 在工作流编辑页面，单击下方"添加节点"，选择"插件"节点，可按类型筛选，添加所需的插件。 图1添加插件节点 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717549715.png "点击放大") 图2插件鉴权 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717389829.png "点击放大") ![](https://support.huaweicloud.com/lowcode-agentarts/public_sys-resources/note_3.0-zh-cn.png) - 使用官方插件时，系统会提示需要鉴权的插件，请根据页面指引完成相应配置鉴权操作后方可使用。 - 使用插件调用外部服务时，可能产生第三方服务的调用费用，该费用由第三方服务方收取。 #### 配置插件节点 参数只读限制：插件节点的输入、输出参数结构均由插件创建时的定义（元信息）决定，在工作流节点内为只读状态，无法直接修改、添加或删除。若需要调整参数结构，必须回到"组件库 \> 插件"页面修改插件定义。 也就是说，您在创建插件时（或插件开发者在定义API接口时）配置的请求参数会自动映射为插件节点的输入参数，API返回的响应字段会自动映射为插件节点的输出参数。 如果需要调整插件节点的参数结构（如新增、删除或修改某个字段），需要回到"组件库 \> 插件"页面中修改插件本身的定义，而非在工作流节点中直接修改。配置插件节点的详细参数说明如下： #### 请求头 平台向插件发起请求时会自动附加自定义的HTTP头部信息，配置的请求参数会自动映射为插件节点的请求头。详细配置请参见[基于API创建插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0126.html)。 请求头的值支持手动输入固定值，或引用上游节点输出及全局配置的记忆变量。 #### 输入参数 需要为插件节点的每个输入参数指定数据来源，支持以下两种取值方式： - 引用：支持用户选择工作流中已包含的前置节点的输出变量值和全局配置中的记忆变量。前置节点为开始节点时，可以引用其输入参数。 - 输入：支持用户输入固定值。 无论是引用还是输入，均需要保证参数类型正确。 同时支持用户自定义输入参数的具体含义。 ![](https://support.huaweicloud.com/lowcode-agentarts/public_sys-resources/note_3.0-zh-cn.png) 注意：手动输入Array（数组）或Object（对象）类型时，必须使用标准的JSON格式，否则节点运行时会报格式错误。详细格式要求请参考[常见问题]。 #### 输出参数 输出参数的所有信息从插件元信息中自动导入，无需手动修改。插件节点运行时会调用工具处理输入参数，并返回处理后的数据供下游节点使用。 #### 异常处理 支持对节点的异常（如超时、调用失败等情况）进行处理，包括超时时间、重试次数、异常处理方式。 - "超时时间"：支持用户配置超时时间，取值范围0.1\~900，默认900s。 - "重试次数"：支持配置重试次数（不重试、重试1次、重试2次、重试3次），系统默认不重试。 - "异常处理方式"：配置异常处理方式。 - 中断流程：节点发生异常后，直接中断流程，不再运行后续节点。 - 返回设定内容：节点发生异常后，工作流不会中断，用户可自定义设置需要返回的输出字段内容，必须是输出参数中已定义的字段，且格式为合法的JSON格式。 - 执行异常流程：节点发生异常后，工作流不会中断，而是会执行异常处理流程。用户可以在该运行异常的节点后新增节点，并为新增的异常分支配置相应的处理流程。 #### 配置示例 本示例使用预置的"文档生成"插件并结合大模型生成文档内容。用户输入待生成的内容后，大模型会自动给出文档标题、文档内容，并由后续的插件节点将内容合并，生成一个可供下载的文档链接。 运行成功后，结束节点将返回包含文档下载链接的输出，用户可通过该链接下载生成的文档。 图3示例效果 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687950070.png "点击放大") - **添加插件** 新建一个工作流，添加插件节点，选择来自插件广场的"文档生成"插件，该插件会将用户输入的标题、内容合并生成一份文档。 图4添加插件 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717389833.png "点击放大") 依次连接开始节点、大模型节点、插件节点、结束节点。 图5连接各节点 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687790226.png "点击放大") - **变量引用** - 所有节点的输入参数均使用"引用"关系，引用前置节点的内容作为本节点的输入。 - 由于示例使用的"文档生成"插件需要输入文档标题、文档内容，该内容可以由前面的大模型节点生成。配置大模型节点"用户提示词"如下。配置提示词时需要考虑后续插件节点的参数输入形式，生成与插件节点参数相同的内容。 ``` 你是一个文档生成助手。根据用户输入的{{query}}生成对应的文档标题document_name和文档内容input。 ``` - 大模型节点除了通过提示词的方式将输出格式与插件节点对齐外，还需要将输出参数改为一致。关闭输出参数的流式输出模式，改为JSON输出。添加document_name、input参数，分别表示文档标题、文档正文内容。 ![](https://support.huaweicloud.com/lowcode-agentarts/public_sys-resources/note_3.0-zh-cn.png) 本示例中大模型节点的输出参数名称和类型必须与插件节点的输入参数完全对齐，否则变量引用时将无法匹配，导致插件调用失败。 图6配置大模型节点 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717549713.png "点击放大") - 文档生成插件节点的输入参数引用大模型节点的输出参数。 图7配置插件节点 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687790222.png "点击放大") - 结束节点引用插件节点的输出参数。 图8配置结束节点 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687950074.png "点击放大") #### 相关操作 - 单击节点名称，可修改节点名称。 - 单击![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717549909.png)图标，可对节点进行重命名、复制、删除或更换节点；也可以将节点连接到结束节点。 - 单击![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687790412.png)图标，可对节点进行测试。 - 单击名称下面的节点说明，可修改节点的描述信息。 - 单击![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717549911.png)图标，可查看文档信息。 #### 常见问题 - **引用上游节点变量后，节点运行提示"参数类型不匹配"** 检查上游输出类型与插件要求类型是否一致，例如插件要求Array，但上游输出的是一个String类型的参数。 - **必填参数已配置，但仍提示"缺少必填参数"** 引用的上游变量在运行时为空值（null或空字符串），虽然配置了引用，但上游节点在某些分支下未产出该变量。请检查上游节点的输出是否正常。 引用了错误的变量，变量名看起来相似但实际指向了另一个字段，请仔细核对引用路径。 - **手动输入固定值时，Array或者Object类型报错格式错误** Array和Object类型的固定值必须使用合法的JSON格式。 表2JSON格式示例 | 参数类型 | 正确写法 | 常见错误写法 | |:---|:---|:---| | Array | \["地点1", "地点2"\] | 地点1, 地点2 | | Array（数字） | \[1, 2, 3\] | 1, 2, 3 | | Object | {"city": "地点1", "count": 5} | city: 地点1, count: 5 | | 嵌套结构 | {"list": \[1, 2\], "info": {"key": "val"}} | 缺少引号或括号不配对 | - **插件调用超时如何处理** 检查网络连通性和目标服务的响应速度。如果目标服务确实需要较长响应时间，可在异常处理中将超时时间调大（最大900秒）。如果超时频繁发生，建议检查目标API是否存在性能问题。 - **插件鉴权配置失败如何排查** 1. 确认鉴权信息（如API Key、Token）是否正确且未过期； 2. 确认鉴权信息的格式是否符合插件要求（如是否需要加Bearer前缀）。 - **插件返回数据结构与输出参数定义不符怎么办** 输出参数从插件元信息自动导入，如果API实际返回的字段与定义不一致，需要回到"组件库 \> 插件"修改插件的响应参数定义，使其与API实际返回结构对齐。 - 插件节点是否收费 执行插件节点执行本身不额外收费，但以下情况可能产生费用： 1. 部分插件广场插件由提供方收费； 2. API类型插件调用外部服务产生第三方费用； 3. 循环或重试场景下费用将按次数累加。