插件管理

插件用于把已有的 HTTP API 接入平台，使 Agent 或 AgentLite 能够查询业务系统、调用第三方服务或执行确定的外部操作。

一个插件统一保存一组接口共用的 插件 URL 和 鉴权方式；插件中的每个 工具 对应一个具体接口，分别定义请求路径、请求方法和输入输出参数。应用最终使用的是插件中的工具，而不是只创建一个插件就能直接调用外部服务。

一、开始前准备什么

创建插件前，应从接口提供方取得以下信息：

必要信息	用途
服务基础地址	作为插件 URL，例如院内服务的统一访问前缀
鉴权要求	是否需要 API Key，以及请求头名称、前缀和密钥内容
接口契约	每个接口的路径、请求方法、输入参数和返回结构
测试环境与测试数据	用于调试真实请求，避免影响生产业务或真实患者数据
OpenAPI 文件或地址（可选）	已有规范时可批量导入工具，减少手工录入

插件适合接入已有 HTTP API。对方提供的是 MCP Server 时，应使用 MCP 管理；需要把平台节点组成固定处理流程时，应使用工作流管理。

调试会发起真实请求。POST、PUT、PATCH、DELETE 等可能改变外部数据的接口，必须使用测试环境和测试数据。

二、先理解插件与工具

假设一个服务统一提供医生信息查询能力：

插件名称：医生信息服务
插件 URL：<服务基础地址>/medical
工具名称：查询医生信息
工具路径：/doctors/query
请求方法：GET
最终请求地址：<服务基础地址>/medical/doctors/query

在这组配置中：

• 插件负责公共地址与鉴权；
• 工具负责具体接口和参数；
• 同一插件还可以继续添加“查询科室”“查询排班”等共用地址与鉴权的工具；
• 应用引用具体工具，并由模型根据工具说明决定何时调用。

新建插件时需要选择 业务插件 或 通用插件。插件类型用于分类，不影响插件的可见范围、使用对象、权限或应用引用范围；创建后仍可在插件设置中修改。

三、进入插件管理

进入 基础服务 › 组件中心 › 插件管理。

左侧分组用于定位插件，右侧可按类型筛选或按插件名称搜索。插件卡片上的信息主要用于判断当前状态：

信息	重点用途
组件 ID	插件的唯一标识，可复制用于核对和定位
引用次数	插件被使用的累计次数，仅供参考，不代表当前实时使用情况
包含工具	确认插件内已经登记的工具数量
插件详情	只读查看插件属性和工具
管理插件	添加、导入、编辑和调试工具

插件分组支持层级组织。点击左侧 插件分组 旁的 ＋ 可创建分组；没有明确归属的插件可放入默认分组。分组只用于管理和筛选，不代替插件类型或访问权限。

四、创建插件

点击右上角 添加插件。

4.1 填写基础信息

字段	配置要点
插件图标	可选；建议 240px × 240px，不超过 2 MB，支持 JPG、PNG
插件名称	使用业务能力名称，如“医生信息服务”，不要使用“测试插件”等无法识别用途的名称
插件类型	选择业务插件或通用插件，仅用于分类，创建后可以修改
插件描述	写清服务范围、适用场景和主要限制，不要只复述插件名称
插件分组	选择便于团队维护的归属分组
插件 URL	填写该插件下所有工具共用的服务基础地址
鉴权类型	根据接口实际要求选择“不需要鉴权”或“API Key”

插件描述可以按下面的结构编写：

提供医生、科室与排班信息查询，供院内服务类应用调用。
仅用于查询，不执行挂号、排班修改或其他写入操作。

4.2 配置 API Key

接口要求在请求头中携带密钥时，选择 API Key。

字段	配置要点
鉴权头部前缀	页面提供 Basic、Bearer、Custom 三个选项，按接口提供方给出的鉴权要求选择；切换选项不会增加其他配置字段
API KEY 名称	请求头字段名，常见为 Authorization，也可能是接口约定的自定义名称
API KEY 内容	接口提供方分配的密钥内容

Basic、Bearer、Custom 位于添加插件弹窗下半部分的 鉴权头部前缀。选择鉴权头部前缀后，按照接口提供方的鉴权要求填写 API KEY 名称 和 API KEY 内容。配置完成后，可通过工具调试验证鉴权信息是否正确。

不要把生产密钥写进插件名称、描述、工具参数、截图或测试输出。测试与生产环境应使用不同凭证，密钥轮换后需要重新调试受影响的工具。

填写完成后点击 确定。此时只完成了插件容器的创建，还需要继续配置工具。

五、配置工具

在插件卡片上点击 管理插件。工具可以手动添加，也可以通过 OpenAPI 导入。

5.1 手动添加工具

点击 添加工具。

基本信息

字段	配置要点
工具名称	使用明确动作，如“查询医生信息”
工具描述	写清何时调用、需要什么、返回什么以及限制条件
工具路径	只填写插件 URL 后面的接口路径，不要重复填写完整 URL
请求方法	必须与接口契约一致

工具描述会影响模型是否选对工具，建议采用下面的结构：

根据医生姓名或科室编号查询医生基本信息。
当用户询问医生所在科室、职称或医生编号时使用。
doctor_name 与 department_id 至少提供一个。
返回医生编号、姓名、科室和职称；不提供排班修改能力。

确认请求地址

工具路径会接在插件 URL 后面。保存前必须核对最终地址，避免重复路径或遗漏 /。

插件 URL：<服务基础地址>/medical
工具路径：/doctors/query
最终地址：<服务基础地址>/medical/doctors/query

若接口文档给出的是完整 URL，应先拆出共用的基础地址，再把接口独有部分填入工具路径。

输入参数

输入参数决定平台怎样组织真实请求：

配置	判断标准
参数名称	必须与接口契约中的字段名一致，包括大小写和下划线
参数描述	说明业务含义、允许值、格式及与其他参数的约束
参数类型	必须与接口接收的类型一致
传入方法	根据接口约定选择 Path、Query、Header 或 Body 等位置
是否必填	接口缺少该参数就不能运行时设为必填
默认值	只有业务上存在稳定默认值时才配置，避免默认值掩盖用户真实意图
开启状态	关闭后该参数不参与工具定义和调用

不同传入位置的含义：

• Path：参数是 URL 路径的一部分，例如 /doctors/{doctor_id}；
• Query：参数拼在 URL 查询字符串中，例如 ?department_id=1001；
• Header：参数放入请求头，适用于接口约定的非公共头部；
• Body：参数进入请求体，常用于 POST、PUT、PATCH 请求。

跨字段条件必须写进参数描述。例如“医生姓名与科室编号至少填写一个”不能仅靠两个“非必填”开关表达，应在工具描述和相关参数描述中同时写清。

输出参数

输出参数用于说明接口返回内容，使模型知道哪些字段可以用于回答。参数名称和类型应与真实返回结构一致，描述应写业务含义而不是重复字段名。

例如：

参数名称	类型	描述
doctor_id	String	医生在业务系统中的唯一编号
doctor_name	String	医生姓名
department_name	String	医生当前所属科室名称

保存后不要立即交给应用使用，先完成调试。

5.2 通过 OpenAPI 导入

已有 OpenAPI（Swagger）规范时，点击 导入工具，可选择：

• 手动粘贴 Schema；
• 从在线 Schema URL 导入；
• 上传本地 Schema 文件。

导入只能减少录入工作，不能代替校验。导入后逐个检查：

1. 工具名称和描述是否能让模型准确选择；
2. 插件 URL 与工具路径是否正确拼接；
3. 请求方法和参数位置是否与接口一致；
4. 必填项、默认值和数据类型是否准确；
5. 输出字段是否与真实返回一致；
6. 每个准备开放给应用的工具是否调试成功。

OpenAPI 支持版本、文件格式、重复导入和覆盖规则以平台实际实现为准。

六、调试并判断是否可用

在工具列表或插件详情中点击 调试。

输入测试参数并点击 运行 后，平台会向外部接口发起一次真实请求。一次“有返回”的调试不等于工具已经可用，至少核对：

• 请求地址、请求方法和参数位置正确；
• 鉴权成功，返回的不是登录页或权限错误；
• 返回结构稳定，配置的输出字段真实存在且类型一致；
• 正常、缺失、越界和异常输入均得到合理结果；
• 输出不包含不应暴露给模型或最终用户的密钥、患者敏感信息和内部调试信息；
• 写入类操作只影响测试数据，并且结果可核验。

常见错误可按下面的顺序定位：

现象	优先检查
401 / 403	API Key 内容、请求头名称和鉴权前缀
404	插件 URL、工具路径及二者拼接结果
405	请求方法是否与接口一致
400 / 422	参数名称、类型、必填项、传入位置和 Body 结构
请求超时或无响应	网络连通性、服务状态和接口耗时
请求成功但结果不可用	输出字段、返回层级、空值及工具描述

每次修改 URL、鉴权、路径、参数或输出结构后，都应重新执行调试。

七、在智能应用中使用插件工具

工具调试成功后，进入目标 Agent 或 AgentLite 的 编排 页面，在工具区域选择插件中的具体工具并开启。详细入口见应用编排中的工具配置。

应用侧至少完成两类测试：

1. 提出一个必须调用该工具才能回答的问题，确认工具能够被选择并返回正确结果；
2. 模拟接口失败或无数据，确认应用不会编造结果，并能给出符合业务要求的提示。

“工具已添加”不等于“模型实际调用”。需要结合日志与分析或链路追踪，确认本次运行使用了正确工具、输入参数和返回结果。

八、查看、修改与维护

8.1 插件详情与管理页

点击卡片上的 插件详情，可在只读抽屉中查看插件 URL、鉴权类型、引用次数和工具概览。

需要新增、编辑或调试工具时，使用 管理插件，不要把只读详情抽屉与管理页面混淆。

8.2 卡片菜单

点击插件卡片右上角 …，可进入设置、复制和删除操作。

• 设置插件：修改页面允许编辑的插件基础信息；
• 复制插件：复制插件及其所有配置，包括鉴权密钥和工具配置。复制后会生成名称带“的副本”的独立插件，拥有新的组件 ID，引用次数从 0 开始；
• 删除插件：平台不会校验插件是否被引用，确认后直接删除，且删除操作不可恢复。

8.3 变更前检查

修改已被应用引用的插件时，按下面的顺序处理：

1. 根据实际使用情况确认可能受影响的应用；引用次数仅表示累计使用次数，不能用于确认当前使用情况；
2. 记录本次变更涉及的 URL、鉴权、工具和参数；
3. 需要大幅调整时先复制插件进行验证；
4. 重新调试所有受影响工具；
5. 在应用预览中验证工具选择、参数和异常处理；
6. 发布后观察日志，确认错误量与响应时间没有异常变化。

九、交付前检查表

• 插件 URL 与每个工具路径能拼出正确地址；
• 鉴权请求头与接口契约一致，文档和截图中没有泄露密钥；
• 工具描述写明调用条件、输入、输出和限制；
• 参数名称、类型、位置、必填项和默认值均与接口一致；
• 输出参数能覆盖应用实际需要的结果；
• 正常、无数据、错误鉴权和异常输入均已调试；
• Agent 能够在需要时调用正确工具，失败时不会编造结果；
• 写入类工具已经过业务、安全与数据责任人确认；
• 已评估变更对现有引用应用的影响。