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

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

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

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

相关入口都在「管理后台 › 能力」下：

以上功能需要租户管理员权限。

12.1 接入外部智能体

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

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

操作步骤

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

你会看到

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

注意

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

12.2 核对网关改写后的名片

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

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

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

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

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

配置上游凭据

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

签发调用方令牌

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

你会看到

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

注意

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

12.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。
• 调用记录出现在智能体详情的「调用情况」页签与「任务中心」（见第 12.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 写法调用。入口不含上游地址与凭证。

12.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，先由管理员确认发布状态，再让成员重新获取配置，不要复用较早签发的令牌。
• 范围外成员的提示与网络失败不同：先确认其是否在可用范围内，再排查网络。

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

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

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

任务中心

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

你会看到

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

注意

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

12.7 导入与分发技能

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

操作步骤

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。
• 平台只访问无需登录即可读取的公开来源，不保存托管平台的账号或令牌。

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

适用场景：把技能和远程 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 个可用组件且不落库。
• 导入的组件需分别配置凭据、发布并分发后才能使用；插件概览的「可见范围」为「本租户」。插件名重复时导入被拒绝，改名后重试或先删除旧插件。

12.9 同步外部注册中心

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

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

操作步骤

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

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

你会看到

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

同步规则

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

12.10 插件目录、版本绑定与执行统计

适用场景：管理网关侧扩展插件：浏览目录、下载开发包、查看版本与执行情况。

操作步骤

1. 进入「管理后台 › 流量 › 网关扩展」，插件列表显示类型与能力、当前版本、状态、绑定数、凭据绑定数与最近更新。
2. 选择「下载 SDK」，挑选开发语言（Lua 或 Rust）并填写插件标识后下载。
3. 打开插件的「管理」，依次查看「概览」「版本」「执行统计」「绑定」。

你会看到

• 概览显示运行时、声明钩子、失败策略、可见范围与安装状态；内置与自建插件同列。
• SDK 含 manifest.json（声明 schemaVersion、hostApiVersion、运行时、钩子、支持的服务类型与失败策略）、示例代码与 SDK 运行时。
• 版本页显示当前版本、源版本、渠道、产物标识与摘要，并提供「上传新版本」入口；版本历史保留产物以便回切。
• 执行统计按钩子给出执行次数与结论分布，逐条列出时间、钩子、结论（如「改写 · 强制」）、原因、耗时与绑定，可点进请求详情。
• 「绑定」页签的「创建绑定」可设置服务类型（模型分组 / MCP / API / A2A）、作用范围、调用方与配置覆盖。

注意

• 失败策略由插件清单声明（失败放行 / 失败关闭），安全关键插件应声明失败关闭；安装后在概览中核对。绑定范围选「全部服务」时，之后新增的服务同样被覆盖。
• 上传的插件包在入口处校验包格式、清单版本、宿主接口版本与 $schema，不合法即拒收。

12.11 内置策略插件与处置动作

适用场景：不写代码，用流量规则的内置动作完成请求拦截等策略。

操作步骤

1. 进入「管理后台 › 流量 › 流量规则」，选择「新建规则」。
2. 「添加条件」收窄规则，例如「模型」等于某个模型并叠加「请求头」条件。
3. 「添加处置动作」选择「拒绝本次调用」并填写原因代码，选择「保存规则」，在确认对话框中核对字段差异与命中顺序后「确认并应用」。

你会看到

• 命中规则的调用返回 HTTP 403，正文含 code: permission_denied、deniedBy: routePolicy 与自定义原因代码；未命中的调用照常返回结果。

处置动作清单

注意

• 被拒绝的调用不出现在「运行总览 › 请求」中，该列表只显示已完成的调用；核对拦截效果请查看规则的命中记录。
• 需要防重放时，用「挂载插件」挂自建插件实现，或在上游侧校验请求唯一性。用「调用方」条件时，必须同时把「调用类型」收窄为一种。

12.12 管理客户端的接入配置

适用场景：把观测与接入配置交给成员，让其在本地客户端里接入平台。

操作步骤

成员打开工作台 ›「我的客户端」，选择「新建客户端」，分两步填写「基本信息」与「密钥与配置」。客户端类型按分组选择：

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

你会看到

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

注意

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

12.13 查看智能体运行状态与调试提示词

适用场景：确认运行中的智能体状态，或在不影响线上智能体的前提下调试提示词。

操作步骤

1. 进入「管理后台 › 智能体运营」，列表显示智能体、状态、服务状态、工作区、运行时版本、升级状态、节点与创建时间。
2. 打开智能体详情，「概览」与「事件」两个页签给出运维信息，可启动、停止、重启、重新下发配置。
3. 调试提示词时进入「提示词库 › 试验台」，选模型与最大输出长度，构造多轮消息后「运行」。

你会看到：智能体运营只提供运维视角的信息；试验台可完整跑多轮对话，结果给出耗时与 Token 数并保留上下文，支持「新窗口」「运行全部」「存为新提示词」。

注意

• 试验台直接调用模型，不经过智能体，因此没有工具调用轨迹，也不能单步执行智能体流程；真实对话轨迹在工作台对话与观测中心查看。
• 停止、重启会影响线上正在使用的智能体，操作前确认影响范围。

能力说明

---

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