23. 外部智能体、技能、插件与外部注册中心

完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向租户管理员、工作空间管理员和普通成员，说明如何把企业内外的智能体、技能与工具组合纳入 Zenova 统一治理：接入遵循 A2A 协议的外部智能体并由网关代为鉴权和记录，将其发布为 MCP 工具；把 Zenova 内的智能体对外发布为 A2A 服务；导入经过安全检查的技能，分发给成员并安装到智能体；把技能与远程 MCP 打包为插件包迁移；从 Nacos 批量同步智能体与 MCP 服务；把本地智能体工具的接入配置交给成员。

相关入口：

除「分享」由智能体所在工作空间的管理者操作外，以上管理功能需要租户管理员权限。

23.1 接入外部智能体

适用场景：某套系统已提供遵循 A2A 协议的智能体，希望由网关统一对外提供入口，并与 Zenova 的智能体一起治理。

前提：外部智能体提供 A2A 名片（Agent Card），其服务地址可从网关所在网络访问。

操作步骤

1. 进入「管理后台 › 能力 › A2A」，在「智能体目录」页签选择右上角「接入 A2A 智能体」。
2. 第 1 步「来源」二选一：「名片 URL 拉取」填写名片地址（如 https://agent.example.com/.well-known/agent-card.json），或「粘贴智能体名片 JSON」粘贴名片内容。
3. 第 2 步「凭据绑定」选已有凭据或「暂不绑定」，上游凭据可在详情页配置（见第 23.3 节）；第 3 步「连通测试」选「开始测试」，确认显示「连通正常，延迟 N 毫秒」。
4. 第 4 步「完成」核对名片名称、协议版本与签名校验，页面提示「已提交注册，当前为待审批状态」。
5. 回列表把状态筛选切到「待审批」并选择「批准」。只有已批准的智能体才能发布、签发令牌与分发。

你会看到

• 列表显示名称、来源、状态、协议版本、健康、调用方与接入时间；「协议版本」取名片声明的 protocolVersion，标题旁的版本号是智能体自身的版本。
• 待审批状态下「发布」开关置灰不可点，批准后可打开。重复接入同一名片地址会被拒绝，提示「该名片地址已接入为智能体「…」，无需重复接入。」

注意

• 名片未声明鉴权时，凭据来源只提供「无需鉴权」与「平台统一配置」。连通测试失败时先确认网关网络能访问名片声明的服务地址。
• 接入后上游地址与鉴权方式都不对调用方暴露（见第 23.2 节）。

23.2 核对网关改写后的名片

适用场景：确认网关对外暴露了哪些信息，以及调用方拿到的名片地址。

打开智能体详情的「详情」页签，可并排查看「原始名片」与「改写后名片（网关入口）」：

调用方读取改写后名片的地址为 https://<网关地址>/api/v1/agent-gateway/a2a/<智能体 ID>/.well-known/agent-card.json，无需鉴权即可读取。名片里的 protocolVersion 是网关对外的协议代际，与原始名片声明的版本是两件事。

23.3 配置上游凭据与调用方令牌

适用场景：上游需要凭据才能调用；外部系统需要长期令牌调用网关入口。

配置上游凭据

1. 在智能体详情「详情」页签的「上游凭据」区域查看「鉴权方式」，它由名片声明决定，支持「Bearer 令牌」「API 密钥」「Basic Auth」「Cookie」「自定义请求头」。
2. 「凭据来源」选「平台统一配置」，填写凭据值并选择「保存凭据」，页面提示「凭据已保存」；「绑定端点」显示上游地址，凭据显示「已配置」且不回显明文。

签发调用方令牌

1. 在「调用方令牌」区域选择「签发」，填写「标签」（如外部系统名称）与有效期，选择「签发」。
2. 在「令牌已签发」中复制明文。明文只显示一次，关闭后无法找回。
3. 需要回收时选择「吊销」。

你会看到

• 令牌列表逐条显示标签、令牌指纹、过期时间、最近使用与状态，签发后「最近使用」为「从未使用」。
• 吊销确认框提示吊销后最多 15 秒内全站生效、不可恢复；确认后状态变为「已吊销」，约 15 秒起该令牌调用返回 401 a2a_token_invalid。

注意

• 调用方只携带 zg_a2a_ 令牌即可调用，上游凭据由网关注入。
• 令牌指纹与明文开头不一定一致；核对是哪一张令牌时按标签与签发时间判断。
• 名片声明 OAuth2 / OIDC 鉴权时需要单独配置；mTLS 与查询参数中的 API 密钥不受支持。

23.4 通过网关调用外部智能体

适用场景：业务系统作为调用方，按 A2A 协议向网关入口提交任务并取回结果。

• 调用入口：https://<网关地址>/api/v1/agent-gateway/a2a/<智能体 ID>
• 改写后名片：https://<网关地址>/api/v1/agent-gateway/a2a/<智能体 ID>/.well-known/agent-card.json

curl -X POST "https://<网关地址>/api/v1/agent-gateway/a2a/<智能体 ID>" \
  -H "Authorization: Bearer <A2A_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "msg-001",
        "role": "ROLE_USER",
        "parts": [{ "text": "请汇总本周工单" }]
      }
    }
  }'

返回结果的 result.task 含任务标识与状态（如 TASK_STATE_COMPLETED）；用 GetTask 加任务标识可查询完整历史。

你会看到

• 不带令牌调用返回 401，error_description: authorization required。
• 调用记录出现在智能体详情的「调用情况」页签与「任务中心」（见第 23.6 节），逐条列出方法、调用者、状态与耗时。

注意：网关入口按 A2A 1.0 语义工作：方法名用 SendMessage、GetTask、CancelTask，角色用 ROLE_USER。旧版写法（如 message/send 配 role: "user"）会收到 JSON-RPC 错误 Invalid enum value，只支持旧写法的客户端需升级。上游智能体可以是 A2A 0.x（如 0.3）或 1.0：网关按其名片声明的协议版本转发，向 0.x 智能体发送 message/send，调用方始终按 1.0 写法调用。入口不含上游地址与凭证。

23.5 分发外部智能体并发布为 MCP 工具

适用场景：把智能体上架到成员侧 A2A 目录，决定哪些成员可以使用；需要时同时发布为 MCP 工具，供 MCP 客户端调用。

前提：智能体已批准。

操作步骤（管理员）

1. 在智能体详情「详情」页签打开「发布」，把智能体上架到工作台顶部「A2A」目录。
2. 打开「可用范围」页签，选择「编辑可用范围」，勾选成员后下一步选择有效期并「保存」；需要供 MCP 客户端调用时，在同一页签打开「发布为 MCP 工具」。

你会看到

• 可用范围保存后提示「分发已保存」，页签显示已分发的成员；打开「发布」后标题旁出现「已发布」徽标，打开「发布为 MCP 工具」后状态显示「已发布」。
• 成员侧拿到的 A2A 配置可直接调用 SendMessage；范围外成员看到卡片但标注「需要管理员分发」，获取配置时提示「请求的资源不存在，或当前无法访问」。

操作步骤（成员）

1. 在工作台顶部「A2A」中打开智能体，页面显示技能与改写后名片，可「复制名片地址」「复制名片」。
2. 在「原生协议接入」中选择令牌有效期并「获取 A2A 配置」，得到名片地址、调用地址与一次性显示的 Bearer 令牌。
3. 已发布为 MCP 工具时，页面的「WorkBuddy / MCP 接入」区块可「获取 MCP 配置」，把 mcpServers 条目合并到客户端配置。

注意

• 「发布为 MCP 工具」通过固定的 A2A MCP 桥接服务提供，含 4 个工具：列出可用智能体、发送消息、查询任务、取消任务；成员获取一次配置即可覆盖所有已发布且分发给本人的智能体。
• 关闭「发布为 MCP 工具」后，已有的 MCP 配置立即不能再调用；租户关闭令牌接入时，成员不能生成 A2A 或 MCP 配置。
• 用 MCP 配置连接桥接入口若返回 401，先由管理员确认发布状态，再让成员重新获取配置，不要复用较早签发的令牌。
• 范围外成员的提示与网络失败不同：先确认其是否在可用范围内，再排查网络。

23.6 查看调用情况与任务中心

适用场景：核对一次外部智能体调用是否成功、结果是什么，以及历史上都有哪些任务。

调用情况：页签逐条列出时间、来源、用户、方法（如 SendMessage、GetTask）、状态、耗时与结果；被拦截的调用同样记录，状态显示「已拦截」。限流与熔断在流量规则中按调用类型「A2A」配置（需要「动态路由」模块），见第 26 章。

任务中心

1. 进入「A2A › 任务中心」，在「按任务 ID 搜索」中输入任务标识，或通过「筛选」添加「目标智能体」「状态」条件；列表显示任务标识、目标智能体、调用方、状态、开始时间、耗时与最近更新。
2. 展开任务查看状态节点。

你会看到

• 调用方列显示「外部 Agent」，目标智能体显示名称；按目标智能体筛选需填写智能体标识，不能按名称选择。
• 展开后显示「状态节点」。上游同步返回完成时只有一个节点（如「已完成」及其时间），说明上游没有给出中间阶段。

注意

• 任务中心记录经网关发起的调用。任务查不到时先用任务标识检索，仍无结果就到智能体详情的「调用情况」核对这次调用是否到达网关。
• 「操作审计」页签记录该智能体的注册、审批、凭据、令牌与分发变更。

23.7 把 Zenova 智能体对外发布为 A2A 服务

适用场景：工作空间里已有一个调好的智能体（例如合同审查助手），希望让平台之外的系统或其他厂商的智能体按 A2A 协议调用它。

前提：你能管理该智能体所在的工作空间；智能体使用婉儿运行时。

操作步骤

1. 打开智能体详情，选择右上角的「分享」，打开「分享智能体」对话框。
2. 在「对外发布（A2A）」区域打开「发布为 A2A 服务」。
3. 页面给出「AgentCard 地址」与「调用端点」，选择「复制」交给调用方。
4. 在「调用令牌」中填写「标签」（如调用方系统名称），选择「生成令牌」，立即复制明文。

你会看到

• 打开开关后提示「已发布为 A2A 服务」；关闭时提示「已取消发布」。
• 令牌以 zg_a2a_ 开头，页面提示「明文仅此一次展示，关闭后无法找回，请立即复制。」；不再需要的令牌选择「撤销」。
• 调用方按第 23.4 节的格式向「调用端点」发送 SendMessage，智能体以自身的模型、技能与应用完成任务。

注意

• 不支持对外发布的智能体会提示「仅 waner 运行时的智能体可对外发布。」
• 「分享智能体」对话框中的「可见范围」「用户授权」管理的是工作空间内成员的访问；对外调用方以调用令牌访问，令牌撤销后即不能再调用，关闭「发布为 A2A 服务」则所有对外调用停止。
• 智能体对外提供服务时，它能访问的知识库、应用与凭据都会被调用方间接使用。发布前确认智能体只连接了该场景需要的能力，并为调用方单独签发、按需撤销令牌。

23.8 导入与分发技能

适用场景：把一份行为指南与附属文件作为技能纳入平台，安装前看清风险，再决定分发给谁。

操作步骤

1. 解析完成后，左栏上方显示来源摘要，例如「GitHub · vercel-labs/agent-skills · 提交 3f2a1c9」，下方的候选表列出该来源中的全部技能，每页 20 个，可按名称搜索。每行依次显示技能名称、说明与目录路径；尚未分析的技能在「结论」列显示文件数。此时只读取了技能清单，尚未分析任何技能。
2. 勾选要导入的技能，选择「分析所选（未分析 n 个）」。只有勾选且尚未分析的技能会被分析，已分析过的不会重复分析；单次最多分析 20 个技能，超过时按钮不可用，请分批分析。
3. 选中候选表中的某一行，右栏显示该技能的分析结果：风险等级、准入结论、15 项检查清单、风险标尺上的企业准入线，以及技能包内的全部文件。尚未分析的技能提示「该技能尚未分析，勾选后点击『分析所选』」。
4. 选择「导入（n）」，n 为勾选且可安装的技能数；页面提示「技能已安装」。新技能状态「未发布」、可见范围「未开放」，此时「编辑可用范围」按钮不可点。
5. 在「信息」页签打开「发布」，回到「可用范围」页签勾选成员并选择有效期，保存。

以下情况会预先勾选一个技能，并在解析的同时自动完成分析，可直接核对结果后导入；如需同一来源中的其他技能，再勾选后选择「分析所选」：

• 从「搜索技能源」的结果进入；
• 来源地址指向具体技能，如 owner/repo@技能名、技能目录地址或 skills.sh 技能页；
• 上传的 .zip 中只有一个技能。

你会看到：风险分析结果标注等级、准入结论与「15 项检查全部通过，没有发现需要你关注的内容。」这类结论，并标出「你所在企业的准入线」；发布后头部出现「已发布」徽标、生效范围显示「未分发」，配置可用范围后提示「分发已保存」。

支持的来源写法

• 只写技能名称（如 react-best-practices）不算来源：同名技能可能分属多个仓库，无法确定要取哪一个。页面提示「无法识别该来源。请输入仓库地址或 owner/repo；按名称查找请使用『搜索技能源』」。
• 地址中不能包含账号口令，归档、清单与其他 git 仓库地址不能带查询参数（如带签名的临时下载链接）。
• 指定的技能在仓库中不存在时，候选表照常列出全部技能，并在来源摘要下方提示「仓库中没有名为『x』的技能，请从下方列表选择」，直到更换来源为止。
• 一个来源最多包含 1000 个技能；超过时提示「该来源包含的技能过多（超过 1000 个），请输入具体技能目录地址」。

勾选与导入规则

• 底部栏左侧显示「已选 n 个」。勾选状态在翻页和搜索后保留。
• 勾选但尚未分析的技能不会导入，导入按钮旁提示「另有 k 个未分析的技能不会安装」。
• 分析后不可安装的技能（如被企业策略拒绝、被安全规则阻断、格式错误或超出大小限制）自动取消勾选且不可再勾选，原因显示在「结论」列。
• 导入的是分析时取得的内容：确认导入时不再重新访问来源，来源在分析之后发生的变化不会进入本次导入。
• 需要换一个来源时选择「更换来源」，页面回到输入区并保留原来的输入内容。

风险等级与准入结论

风险等级由低到高：纯指南、知识资产、受管集成、本地执行、外部 / 高敏、禁止级。准入结论如下：

从来源重新导入（更新技能）

技能来源有新版本时，在技能详情中逐个更新：

1. 打开技能详情，选择「从来源重新导入」。页面打开添加技能页，自动解析该技能来源的最新提交，并预先勾选原技能。
2. 候选表中只有原技能那一行可以勾选，其他技能显示「重新导入只能更新原技能」。
3. 内容与已安装版本相同时，该行显示「与已安装版本相同」，底部提示「与已安装版本相同，无需更新」，只能选择「取消」。
4. 内容有变化时自动分析；核对结果后确认，原技能替换为新版本。

• 只有记录了来源的技能显示「从来源重新导入」。来源地址无法识别的早期技能不显示该按钮，来源一栏显示「来源地址无法识别，需删除后重新添加」。
• 上传 .zip 导入的技能没有可重新访问的来源，更新时请上传新的技能包。

常见问题与处理

注意

• 风险分析基于规则匹配，不执行技能内容；租户准入线默认为「外部 / 高敏」，不能设为「禁止级」。
• 编辑技能后直接生效，没有「比对差异后重启」这一步；回到来源版本时选「从来源重新导入」，同样经过风险分析。成员可在技能详情下载技能包，管理员在「下载记录」查看下载记录；单包上限 20 MiB。
• 平台只访问无需登录即可读取的公开来源，不保存托管平台的账号或令牌。

23.9 在智能体中安装与使用技能

适用场景：成员把管理员上架的技能装进自己工作空间的智能体，让智能体按固定流程完成任务；或向管理员提交自己整理的技能。

前提：技能已发布并分发给本人；你能管理目标智能体。

操作步骤

1. 在工作台顶部选择「智能体」，左侧进入「技能广场」，页面标题为「<工作空间名> · 技能广场」。未选择工作空间时，先在左上角切换到目标工作空间。
2. 打开技能，选择「安装到智能体」，在「选择智能体」中勾选一个或多个智能体，选择「安装到 N 个智能体」。
3. 技能需要授权凭据时，页面提示「此技能需要授权凭据配置，安装后请前往各智能体的技能设置中完成配置。」，按提示到智能体详情完成配置。
4. 在对话中选择该智能体，输入 / 可从「技能」分组中指定技能，也可直接描述任务，由智能体按需选用。

你会看到

• 安装成功提示「已成功安装到 N 个智能体」；部分失败时提示「已安装到 X/Y 个智能体（部分失败）」，并给出原因。卡片显示「已安装 N 次」。
• 被企业策略或工作空间策略禁用的技能标「已禁用」。

提交技能（成员）：在「技能广场」选择「上传技能」，上传 .zip 技能包或填写来源地址，选择「解析来源」。之后的勾选与「分析所选」与第 23.8 节相同，所有技能先经过相同的安全扫描；选择「提交审批（n）」后进入待审批，页面提示「已提交，审批通过后由管理员上架」。该技能已在审批中，或待审批的技能已达上限时，提交被拒绝并写明原因。管理员关闭上传时按钮提示「管理员已关闭技能上传」。

注意

• 当前空间关闭自助安装时提示「当前空间已关闭自助安装，如需启用请联系管理员开启。」
• 智能体自己的自定义技能、技能自进化与版本回滚在智能体详情中维护，见第 13、14 章。

23.10 导入与导出智能体插件包

适用场景：把技能和远程 MCP 服务打包成一个标准 zip，便于在平台之间迁移，或交给支持插件的智能体工具整体安装。

导出为插件

1. 进入「管理后台 › 能力 › 插件」，选择「导出为插件」，填写「插件名」（只允许小写字母、数字和连字符）、「版本」「描述」「许可证」。
2. 在「技能」与「MCP 服务」中勾选组件（只有远程 MCP 服务可导出）。
3. 选择「预览」，核对组件与技能标识，页面提示「产物不含任何凭据，目标端需自行配置。」；选择「导出」下载 zip 或「保存到平台」。

导出的包含 plugin.json、.claude-plugin/plugin.json、MCP 配置（只含服务类型与地址）与 skills/<技能标识>/SKILL.md，不含凭据、可用范围与固定值。

导入插件包：在「插件」页选择「导入」，上传 .zip 插件包，在预览中勾选要导入的组件后选择「导入」。

你会看到

• 导入成功后插件立即出现在「插件」列表并显示组件计数，例如「技能 1/1」或「技能 1/1 · MCP 1/1」；包内技能以「未发布 / 未开放」进入「技能」列表，包内 MCP 服务以「未发布」进入「MCP 服务」列表。

注意

• 包内技能与直接导入技能用同一套安装前检查，超出准入线或命中禁止项会使导入被拒绝。
• 包的清单必须带 $schema，缺少时提示 manifest_invalid (required field $schema is missing)；mcp.json 缺 $schema 报 mcp_config_invalid；$schema 版本不受支持时预览显示 0 个可用组件且不落库。
• 导入的组件需分别配置凭据、发布并分发后才能使用；插件概览的「可见范围」为「本租户」。插件名重复时导入被拒绝，改名后重试或先删除旧插件。
• 这里的插件是技能与 MCP 的组合包。在请求链路上执行的网关扩展插件在「管理后台 › 流量 › 网关扩展」中管理，见第 27 章。

23.11 同步外部注册中心

适用场景：企业已用 Nacos 管理 A2A 智能体与 MCP 服务，希望批量纳入平台治理而不是逐个接入。

前提：Nacos 提供 AI 注册管理接口（/nacos/v3/admin/ai/a2a、/nacos/v3/admin/ai/mcp），平台能访问其地址；开启鉴权时需提供能读取目标命名空间的账号。

操作步骤

1. 进入「管理后台 › 能力 › 外部注册中心」，选择「新建源」，填写下表字段后选择「保存」。

1. 保存后在行尾「更多操作 › 编辑」中选择「测试连接」，核对可同步的 A2A 智能体数、MCP 数与跳过的模板数，再选「立即同步」或等待按轮询间隔自动同步。

你会看到

• 列表显示健康状态、最近同步时间与创建时间，新建后健康为「未知」。「测试连接」返回可同步数量，失败时给出原因与建议；「立即同步」失败时健康列变为「降级」。

同步规则

• 同步进来的智能体与 MCP 服务仍需在各自的「可用范围」中显式分发，成员才能看到；关闭「自动批准」时智能体以「待审批」进入目录。
• 同一条目重复同步时更新原记录，上游连续两次轮询都不存在才视为删除；单次同步为空或删除过半条目时暂停删除并标记「降级」。
• 同步来的智能体不能单独删除，需通过注册源统一管理。

23.12 把本地智能体工具接入平台观测

适用场景：成员在本机使用 Claude Code、Codex、Trae 等智能体工具，希望这些工具的会话也进入 Zenova 的观测与诊断。

操作步骤

成员在工作台顶部「洞察」中进入「我的客户端」，选择「新建客户端」，分两步填写「基本信息」与「密钥与配置」。客户端类型按分组选择：

打开已有客户端详情的「配置」页签，复制接入片段。

你会看到

• 「配置」页签给出可直接粘贴的配置：以 Claude Code 为例是一组 export 环境变量，含遥测开关、导出协议、平台采集地址与带工作区标识、密钥占位的请求头，旁边有「复制」按钮。
• 「经 ZenSwitch」分组的说明为「由 ZenSwitch 自动接入」，需在 ZenSwitch 中打开对应客户端的会话观测；片段中的密钥是占位符，需另行生成后手工替换。

注意

• 网页端只提供「复制片段 → 粘贴到客户端」，不改写本地文件，也没有回滚按钮，修改前先备份原配置。
• 「经 ZenSwitch」分组的客户端需在 ZenSwitch 内打开会话观测开关才能上报；安装包从下载站获取，列表为空时联系管理员。观测数据的查看与权限边界见第 29 章。

能力说明

---

上一章：22. 配置并分发 MCP 服务与 API 服务 · 下一章：24. 配置敏感数据（PII）检测