基于json文件导入api插件-j9九游会登录

agentarts支持通过json文件形式导入api插件，可以直接将api插件中定义的接口、入参、出参、鉴权等信息编辑为一份json文件，再导入平台创建api形态的插件。

json导入功能允许您通过配置文件而非手动单击界面来创建插件，平台解析该文件后，会自动完成插件注册、工具定义及鉴权配置，实现插件的即插即用。该功能特别适用于批量迁移（如将开发环境的大量插件快速迁移到生产环境）和版本管理（如将插件配置存储在代码仓库中，实现变更追踪和回滚）等场景。

该json文件定义了插件的基础属性、后端服务连接地址、输入输出参数结构以及鉴权方式。开发者可通过修改此文件，快速将现有的restful api接入到平台中创建成插件。推荐结合示例：创建联网搜索插件、基于api创建插件进行查看，便于理解json文件中的各参数。

获取json示例文件：

当前平台需要事先创建、发布一个api插件，再导出该插件的json配置文件。您可以参考示例：创建联网搜索插件创建插件并导出插件的json文件。

配置文件由顶层的metadata和import_type组成。所有的业务逻辑配置均位于metadata对象中。

{
    "metadata": { ... },     // 核心配置区域
    "import_type": "plugin"  // 标识文件类型，固定为 "plugin"
}

插件基础信息：

定义插件在平台页面上的展示信息及唯一标识。

服务连接配置：

字段：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值（通常导入后需重新配置以保密）
        }
    ]
}

生命周期与状态控制：

如果您需要基于此模板创建一个新的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示例

使用示例：创建联网搜索插件导出的完整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报错，请尝试重新配置插件的鉴权信息。