# 插件
插件节点是工作流中实现第三方能力调用的核心组件之一，允许工作流通过调用插件来执行特定功能任务。
尽管大语言模型（LLM）具备强大的自然语言处理与推理能力，但存在两大局限：信息滞后（无法获取训练截止日期之后的实时信息）和行动力缺失（无法直接与外部系统交互）。插件节点正是突破这些局限的关键桥梁，每个插件本质上是经过标准化封装的API或者函数功能的工具集合，提供即插即用的模块化服务，让工作流具备连接外部世界的能力。
插件与工具的关系：插件是集成了一个或多个工具的功能集合，定义了这些工具共用的基础属性（如服务域名、鉴权方式）；工具是插件内具体的执行单元，每个工具对应一个独立的功能。工作流中添加插件节点时，实际调用的是插件中某一个特定工具。
#### 添加节点
工作流中支持添加三种类型的插件。
表1插件类型 
| 插件分类 | 说明                                                       | 获取方式                          |
|:---|:---|:---|
| 插件广场 | 由AgentArts平台上架至"资产广场"的官方插件，由平台提供技术支持和维护。                 | 来自"资产广场"的插件，注意部分插件需要配置鉴权或收费。  |
| 我的插件 | 开发者自行创建的插件，支持API类型（封装外部 RESTful API）和函数类型（在平台沙箱中运行代码脚本）。 | 通过"组件库 \> 插件"入口自行配置创建。        |
| 团队共享 | 其他空间共享给本空间的插件资源。                                         | 在资产广场中查看并添加（仅AgentArts企业版支持）。 |
   
在工作流编辑页面，单击下方"添加节点"，选择"插件"节点，可按类型筛选，添加所需的插件。
图1添加插件节点   
![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569344155.png)
注使用官方插件时，系统会提示需要鉴权的插件，请根据页面指引完成相应操作。
图2插件鉴权   
![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569344161.png)
#### 配置插件节点
**参数来源：**
插件节点的输入参数和输出参数均从插件元信息中自动导入，包括参数名称、参数类型、是否必填以及默认值等信息，用户无需手动添加或修改参数结构。
也就是说，您在创建插件时（或插件开发者在定义API接口时）配置的请求参数会自动映射为插件节点的输入参数，API返回的响应字段会自动映射为插件节点的输出参数。
如果需要调整插件节点的参数结构（如新增、删除或修改某个字段），需要回到"组件库 \> 插件"页面中修改插件本身的定义，而非在工作流节点中直接修改。
**输入参数：**
需要为插件节点的每个输入参数指定数据来源，支持以下两种取值方式：
- 引用：支持用户选择工作流中已包含的前置节点的输出变量值和全局配置中的记忆变量。前置节点为开始节点时，可以引用其输入参数。
- 输入：支持用户输入固定值。
无论是引用还是输入，均需要保证参数类型
**输出参数：**
输出参数的所有信息从插件元信息中自动导入，无需手动修改。插件节点运行时会调用工具处理输入参数，并返回处理后的数据供下游节点使用。
**异常处理：**
支持对节点的异常（如超时、调用失败等情况）进行处理，包括超时时间、重试次数、异常处理方式。
- 超时时间""：支持用户配置超时时间，取值范围0.1\~900，默认900s。
- 重试次数""：支持配置重试次数（不重试、重试1次、重试2次、重试3次），系统默认不重试。
- 异常处理方式""：配置异常处理方式。
  - 中断流程：节点发生异常后，直接中断流程，不再运行后续节点。
  
  - 返回设定内容：节点发生异常后，工作运行不会中断，用户可自定义设置需要返回的输出字段内容，必须是输出参数中已定义的字段，且格式为合法的JSON格式。
  
  - 执行异常流程：节点发生异常后，工作流不会中断，而是会执行异常处理流程。用户可以在该运行异常的节点前新增节点，并为新增的异常分支配置相应的处理流程。
   
 
#### 配置示例
本示例使用预置的"文档生成"插件并结合大模型生成文档内容。用户输入待生成的内容后，大模型会自动给出文档标题、文档内容，并由后续的插件节点将内容合并，生成一个可供下载的文档链接。
图3示例效果   
![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384446.png)
- **添加插件**
  新建一工作流，添加插件节点，选择来自插件广场的"文档生成"插件，该插件会将用户输入的标题、内容合并生成一份文档。
  图4添加插件   
  ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569344149.png)
  依次连接开始节点、大模型节点、插件节点、结束节点。
  图5连接个节点   
  ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544398.png) 
- **变量引用**
  - 所有节点的输入参数均使用"引用"关系，引用前置节点的内容作为本节点的输入。
  
  - 由于示例使用的"文档生成"插件需要输入文档标题、文档内容，该内容可以由前面的大模型节点生成。配置大模型节点"用户提示词"如下。配置提示词时需要考虑后续插件节点的参数输入形式，生成与插件节点参数相同的内容。
    ```
    你是一个文档生成助手。根据用户输入的{{query}}生成对应的文档标题document_name和文档内容input。
    ```
    
  
  - 大模型节点除了通过提示词的方式将输出格式与插件节点对齐外，还需要将输出参数改为一致。关闭输出参数的流式输出模式，改为JSON输出。添加document_name、input参数，分别表示文档标题、文档正文内容。
    图6配置大模型节点   
    ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424131.png) 
  
  - 文档生成插件节点的输入参数引用大模型节点的输出参数。
    图7配置插件节点   
    ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424139.png) 
  
  - 结束节点引用插件节点的输出参数。
    图8配置结束节点   
    ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544382.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"}} | 缺少引号或括号不配对          |