# 基于JSON文件导入API插件 AgentArts支持通过JSON文件形式导入API插件，可以直接将API插件中定义的接口、入参、出参、鉴权等信息编辑为一份JSON文件，再导入平台创建API形态的插件。 JSON导入功能允许您通过配置文件而非手动单击界面来创建插件，平台解析该文件后，会自动完成插件注册、工具定义及鉴权配置，实现插件的即插即用。该功能特别适用于批量迁移（如将开发环境的大量插件快速迁移到生产环境）和版本管理（如将插件配置存储在代码仓库中，实现变更追踪和回滚）等场景。 该JSON文件定义了插件的基础属性、后端服务连接地址、输入输出参数结构以及鉴权方式。开发者可通过修改此文件，快速将现有的RESTful API接入到平台中创建成插件。推荐结合[示例：创建联网搜索插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0124.html)、[基于API创建插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0126.html)进行查看，便于理解JSON文件中的各参数。 #### 前提条件 - 已[开通AgentArts服务](https://support.huaweicloud.com/qs-agentarts/agentarts_04_0000.html)。 - 建议先阅读[基于API创建插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0126.html)了解插件的基本概念和创建流程，或直接参考[示例：创建联网搜索插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0124.html)导出现有插件作为模板。 #### 约束与限制 - 当前仅支持导入通过"API类型"创建的插件。 - 仅支持上传.jsonl格式文件。 - 最大支持128MB。 **获取JSON示例文件：** 当前平台需要事先创建、发布一个API插件，再导出该插件的JSON配置文件。您可以参考[示例：创建联网搜索插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0124.html)创建插件并导出插件的JSON文件。 图1导出插件 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687949820.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字符串（例如，原始 JSON 为 {"a":1}，在文件中应填写为 "{\\"a\\":1}"）。它定义了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决策时参考的工具描述 } ] } ``` tool_info中的tool_id是唯一标识。如果您修改了tool_id，请务必同步更新input_schema、output_schema、intf_type等数组中对应的tool_id，否则会导致参数配置无法匹配。 **接口契约定义：** 这是配置文件中最复杂的部分，定义了插件如何组装参数以及如何处理返回值。 - 输入参数定义 (input_schema) 结构说明：该数组中的每个对象对应一个工具，必须包含tool_id以匹配tool_info中的工具，以及具体的input_schema（参数定义）内容。 作用：定义API请求所需的Header、Body、Query参数。 注意：在编辑此字段时，必须严格遵守JSON转义规则（例如 " 必须写成 \\"），否则会导致导入失败。如果您修改了tool_info中的tool_id，请务必同步更新此处的tool_id。 - 输出参数定义 (output_schema) 格式：JSON字符串数组。 结构说明：该数组中的每个对象对应一个工具，必须包含tool_id以匹配tool_info中的工具，以及具体的output_schema（返回结构）内容。 作用：定义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"为项目内可见。"domain"为域（租户）内可见。 | | 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。 **完整JSON示例** 使用[示例：创建联网搜索插件](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0124.html)导出的完整JSON示例文件如下： ``` { "metadata": { "plugin_id": "6282baa8-abe7-47bc-a9e7-77f537843580", "project_id": "832bce5c182f4c528188e4a9c120ea10", "plugin_display_name": "lianwangsousuo", "plugin_chinese_name": "联网搜索", "plugin_desc": "通过搜索引擎获取互联网实时信息，包括新闻、百科、网页内容等", "icon": "data:image/svg+xml;base64,PHN2ZyB3a...", "request_info": "{\"basic_info\":{\"host\":\"qianfan.baidubce.com\",\"path\":\"/v2/ai_search\",\"protocol\":\"https\",\"input_schema\":\"{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{},\\\"required\\\":[]}\"},\"tool_info\":[{\"tool_id\":\"3a9de9fc917a40be\",\"tool_display_name\":\"web_search\",\"tool_chinese_name\":\"网络搜索\",\"tool_desc\":\"通过搜索引擎获取互联网实时信息，包括新闻、百科、网页内容等\",\"method\":\"POST\",\"path\":\"/web_search\"}]}", "auth_info": { "scope": "SERVICE", "domain": "HEADERS", "auth_keys": [ { "target_name": "Authorization", "auth_key": "B****f" } ] }, "visibility": "domain", "input_schema": "[{\"tool_id\":\"3a9de9fc917a40be\",\"input_schema\":\"{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"Authorization\\\":{\\\"default\\\":\\\"Bearer bce-v3/ALTAK...\\\",\\\"location\\\":\\\"Headers\\\",\\\"validate_rule\\\":\\\"\\\",\\\"validate_type\\\":\\\"CHAR\\\",\\\"validated\\\":false,\\\"name_cn\\\":\\\"Authorization\\\",\\\"type\\\":\\\"string\\\",\\\"description\\\":\\\"Authorization\\\"},\\\"Content-Type\\\":{\\\"default\\\":\\\"application/json\\\",\\\"location\\\":\\\"Headers\\\",\\\"validate_rule\\\":\\\"\\\",\\\"validate_type\\\":\\\"CHAR\\\",\\\"validated\\\":false,\\\"name_cn\\\":\\\"Content-Type\\\",\\\"type\\\":\\\"string\\\",\\\"description\\\":\\\"Content-Type\\\"},\\\"messages\\\":{\\\"location\\\":\\\"Body\\\",\\\"validate_rule\\\":\\\"\\\",\\\"validate_type\\\":\\\"CHAR\\\",\\\"validated\\\":false,\\\"name_cn\\\":\\\"\\\",\\\"type\\\":\\\"array\\\",\\\"description\\\":\\\"messages\\\",\\\"items\\\":{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"role\\\":{\\\"default\\\":\\\"user\\\",\\\"location\\\":\\\"Body\\\",\\\"validate_rule\\\":\\\"\\\",\\\"validate_type\\\":\\\"CHAR\\\",\\\"validated\\\":false,\\\"name_cn\\\":\\\"\\\",\\\"type\\\":\\\"string\\\",\\\"description\\\":\\\"角色\\\"},\\\"content\\\":{\\\"location\\\":\\\"Body\\\",\\\"validate_rule\\\":\\\"\\\",\\\"validate_type\\\":\\\"CHAR\\\",\\\"validated\\\":false,\\\"name_cn\\\":\\\"\\\",\\\"type\\\":\\\"string\\\",\\\"description\\\":\\\"用户问题\\\"}},\\\"required\\\":[\\\"role\\\",\\\"content\\\"]}}},\\\"required\\\":[\\\"Authorization\\\",\\\"Content-Type\\\",\\\"messages\\\"]}\"}]", "output_schema": "[{\"tool_id\":\"3a9de9fc917a40be\",\"output_schema\":\"{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"references\\\":{\\\"type\\\":\\\"array\\\",\\\"description\\\":\\\"输出信息\\\",\\\"items\\\":{\\\"type\\\":\\\"string\\\"}}},\\\"required\\\":[\\\"references\\\"]}\"}]", "is_input_list": "[{\"tool_id\":\"3a9de9fc917a40be\",\"is_input_list\":false}]", "is_output_list": "[{\"tool_id\":\"3a9de9fc917a40be\",\"is_output_list\":false}]", "type": "custom", "call_mode": "api", "intf_type": "[{\"tool_id\":\"3a9de9fc917a40be\",\"intf_type\":\"blocking\"}]", "metadata": "", "creator": "hwPersonalaccount", "creator_id": "082c85020600265e1f34c008f1aaacfb", "created_on": 1780135248000, "updated_on": 1783579119000, "test_status": "[{\"tool_id\":\"3a9de9fc917a40be\",\"test_status\":1}]", "last_version_id": "1780138253433", "auth_required": false, "trace_id": "6282baa8-abe7-47bc-a9e7-77f537843580", "published": 1, "is_free": 0, "domain_id": "082c85016600258f0fe3c0080c949e20", "is_share": 0, "view_times": 3 }, "import_type": "Plugin" } ``` **导入JSON示例文件：** JSON文件准备完成后，在平台插件页面执行导入操作。 导入后重新对插件进行调试，如果出现401 Invalid token报错，请尝试重新配置插件的鉴权信息。 图2导入JSON文件 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687789970.png "点击放大")