# 基于JSON文件导入API插件
AgentArts支持通过JSON文件形式导入API插件，可以直接将API插件中定义的接口、入参、出参、鉴权等信息编辑为一份JSON文件，再导入平台创建API形态插件。
该文件定义了插件的基础属性、后端服务连接地址、输入输出参数结构以及鉴权方式。开发者可通过修改此文件，快速将现有的RESTful API接入到平台中创建成插件。推荐结合[示例：创建联网搜索插件](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0124.html)、[基于API创建插件](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0126.html)进行查看，便于理解JSON文件中的各参数。
#### 前提条件
- 已[开通AgentArts服务](https://support.huaweicloud.com/qs-agentarts0/agentarts_04_0000.html)。
- 登录用户为空间所有者、空间管理员、开发工程师，详细信息请参考[管理团队空间成员](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0216.html)。
- 已经完成插件、工具的创建操作，操作指导请参考[基于API创建插件](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0126.html)、[基于函数创建插件](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0127.html)。
 
#### 约束与限制
- 当前仅支持导入通过"API类型"创建的插件。
- 仅支持上传.jsonl格式文件。
- 最大支持128MB。
 
**获取JSON示例文件：**
当前平台需要事先创建、发布一个API插件，再导出该插件的JSON配置文件。您可以参考[示例：创建联网搜索插件](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0124.html)创建插件并导出插件的JSON文件。
图1导出插件   
![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424073.png)
配置文件由顶层的metadata和import_type组成。所有的业务逻辑配置均位于metadata对象中。
```
{
    "metadata": { ... },     // 核心配置区域
    "import_type": "Plugin"  // 标识文件类型，固定为 "Plugin"
}
```
**插件基础信息：**
定义插件在平台页面上的展示信息及唯一标识。
表1插件基础信息参数 
| 参数                  | 名称      | 示例                              |
|:---|:---|:---|
| plugin_display_name | 插件英文标识名 | "web_search"                    |
| plugin_chinese_name | 插件中文名称  | "联网搜索插件"（在市场或编排页展示的名字）          |
| plugin_desc         | 插件描述    | "联网搜索插件"（用于模型理解插件用途）            |
| icon                | 插件图标    | Base64编码的图标                     |
| type                | 插件类型    | "custom"（表示用户自定义插件）             |
| call_mode           | 调用模式    | "api"（核心字段，标识此为HTTP接口调用，而非代码函数） |
   
**服务连接配置：**
字段：request_info。注意，此字段的值是一个经过转义的JSON字符串。它定义了API的物理地址和工具列表。
```
{
    "basic_info": {
        "host": "qianfan.baidubce.com",  // API 域名
        "protocol": "https",             // 协议
        "path": "/v2/ai_search"          // 基础路径前缀
    },
    "tool_info": [
        {
            "tool_id": "7381...",        // 工具唯一ID
            "tool_display_name": "web_search", // 工具名
            "method": "POST",            // HTTP方法
            "path": "/web_search",       // 具体接口路径（完整路径为basic path + tool path）
            "tool_desc": "网络搜索工具"    // LLM决策时参考的工具描述
        }
    ]
}
```
**接口契约定义：**
这是配置文件中最复杂的部分，定义了插件如何组装参数以及如何处理返回值。
- 输入参数定义 (input_schema) 格式：JSON字符串数组。
  该字段定义了API请求所需的Header、Body、Query参数。
  在编辑此字段时，必须严格遵守JSON转义规则（例如 " 必须写成 \\"），否则会导致导入失败。
  
- 输出参数定义 (output_schema) 格式：JSON字符串数组。
  定义了API响应的结构，帮助Agent提取关键信息。
  
**鉴权配置：**
字段：auth_info
定义了Agent调用外部API时的认证方式。
```
示例
"auth_info": {
    "scope": "SERVICE",      // 鉴权范围
    "domain": "HEADERS",     // 鉴权参数位置：HEADERS, QUERY, BODY
    "auth_keys": [
        {
            "target_name": "Authorization", // HTTP Header的Key
            "auth_key": "B****3"            // 实际的API Key值（通常导入后需重新配置以保密）
        }
    ]
}
```
**生命周期与状态控制**：
表2参数说明 
| 参数            | 说明                                        |
|:---|:---|
| visibility    | 可见性，如 "project"（项目内可见）。                   |
| auth_required | 用户是否需要自行授权。false表示使用平台预置的统一鉴权。            |
| intf_type     | 接口类型。包含JSON字符串，blocking代表同步阻塞调用（等待API返回）。 |
   
如果您需要基于此模板创建一个新的API插件（例如接入天气查询API），请遵循以下步骤修改JSON：
- 修改基础信息：更新plugin_chinese_name和plugin_desc。
- 更新请求地址： 将request_info中的host修改为您的API域名（如api.weather.com）。
  更新tool_info中的path和method。
  
- 重写Schema： 这是最容易出错的步骤。建议先编写标准的JSON Schema对象，然后使用工具将其转换为转义后的字符串，填入input_schema和output_schema。
  
- 配置鉴权： 如果API需要Key，在auth_info中填入对应的Header Key名称和Value。