A2A接入指南
A2A 用于连接不同平台的 Agent。你可以让外部平台调用 AE Agent,也可以在 AE 中接入远程 Agent,由当前 Agent 将任务交给它执行并整理结果。
以下远程 Agent 配置与会话选择步骤适用于已提供独立远程 Agent 入口的环境。若你的环境仍通过 MCP 管理 A2A 连接,请联系管理员核对产品与配套沙箱版本。
功能概述与准备
| 接入方向 | 适用场景 | 配置入口 |
|---|---|---|
| 外部平台调用 AE Agent | 在其他支持 A2A 的平台中使用 AE Agent 的能力。 | 在 Agent 库 → Agent 中获取 Agent Card 地址,再通过具备调用能力的外部 Agent 会话或 A2A 配置页接入。 |
| AE 调用远程 Agent | 让当前 Agent 将专项任务交给远程 Agent 处理。 | 在 Agent 库 → 远程 Agent 中创建连接,再在会话输入框中选择。 |
Agent Card 是描述 Agent 名称、能力、协议和调用地址的信息文件。接入时应填写完整的 Agent Card URL,并确认调用方能够访问该地址及 Card 声明的服务地址。
当前接入要求使用兼容 A2A 1.0 JSON-RPC 的客户端或远程服务。调用 AE Agent 时,需准备有权访问该 Agent 的有效访问令牌,并启用目标 Agent;接入远程 Agent 时,按远程服务的要求选择认证方式。
将 AE Agent 接入外部平台
- 进入 Agent 库 的 Agent 页签。若要调用默认 Agent,点击页面顶部的 支持 A2A 1.0 · 查看接入方式;若要调用指定 Agent,打开该 Agent 详情,找到 外部调用(A2A)。
- 点击 复制地址,获取对应 Agent 的 Card 地址。默认 Agent 与指定 Agent 的地址不同,应复制实际需要调用的 Agent 所显示的地址。
- 在能够执行 HTTP 请求并按 A2A 1.0 协议调用的外部 Agent 会话中,发送 Card 地址和任务;也可使用平台提供的 A2A 接入配置页。Card 读取和后续任务请求均需携带以下请求头。
Authorization: Bearer <ACCESS_TOKEN>
A2A-Version: 1.0
将 <ACCESS_TOKEN> 替换为通过既有授权方式获取的有效 CLI token,或已有的 TE access token。A2A 接入窗口不生成令牌。仅复制 Card 地址不能完成鉴权,也不能用浏览器 Cookie 代替上述请求头。
通过会话发起时,可以发送以下指令,并附上刚复制的完整 Card 地址:
请读取这个 Agent Card,使用已配置的 TE 访问凭证,按 A2A 1.0 协议调用该 Agent,完成任务:将“活动将于本周五开使,欢迎参与”改为没有错别字的文案。
外部 Agent 需要实际读取 Card 并发送协议请求。普通聊天窗口仅接收到链接和文字,并不表示已经建立 A2A 连接;若平台不具备执行请求的工具,则需使用其支持的 A2A 接入方式。
首次使用先验证一个简单文本任务。若返回正在执行的任务,继续查询任务状态;若任务要求补充输入,在原任务中继续回复。
在 AE 的接入窗口中,可点击 查看 Card 内容,查看协议、输入输出类型及完整 JSON,并复制 JSON。这里的预览使用当前登录身份;外部平台使用其他凭证时,应以该凭证实际读取到的 Card 为准。
外部调用沿用令牌所属用户的权限,只能访问该用户可见且已启用的 Agent。接入地址还需能被外部平台所在网络访问。
公开过程与最终回答
外部平台调用 AE Agent 时,公开过程与最终回答分别作为独立的文本 Artifact 返回。公开过程是用户可见的执行过程,不包含模型的私有推理。
| 内容 | metadata.aeOutputKind | 调用方处理方式 |
|---|---|---|
| 公开过程 | thinking | 按需展示任务进展,与最终回答分开保存和呈现。 |
| 最终回答 | result | 作为任务的回答内容;只有过程、尚无回答时,不会生成结果 Artifact。 |
流式调用时,两类内容都可能更新。客户端应按 artifactId 区分产物,并按 append 追加或替换内容,不能将全部文本分片直接拼成最终回答。运行中的回答可能尚未定稿,任务是否完成仍以任务状态为准。
接入 A2A 远程 Agent
远程 Agent 在独立页面中管理,不再作为 MCP 连接创建,也不需要在 Agent 创建或编辑页的 MCP 配置中绑定。
- 进入 Agent 库 → 远程 Agent,点击 创建远程 Agent。
- 填写基本信息、连接与认证信息,并按需设置执行选项。
- 点击 保存。平台会读取 Agent Card,检查其是否提供兼容的 A2A 1.0 JSON-RPC 接口。保存成功后,确认该连接处于启用状态。
| 配置项 | 填写说明 |
|---|---|
| 标识名称(必填) | 如 copy_editor。以英文字母开头,仅支持英文字母、数字、下划线和短横线,最长 64 个字符。创建后不能在编辑页修改。 |
| 显示名称、描述(可选) | 填写便于辨认的名称和用途说明。 |
| Agent Card URL(必填) | 填写远程 Agent 的完整 A2A 1.0 Card 地址。接入另一个 AE Agent 时,使用其接入窗口中复制的地址。 |
| 认证方式 | 按远程服务要求选择 无认证、独立 Bearer Token 或 当前用户 CLI 授权,具体见下表。 |
| 允许作为独立外部服务委派 | 接入第三方 Agent 时开启。无认证连接也需开启;AE 内部目标不能使用此授权。 |
| 远端执行模型(可选) | 填写连接与认证信息后,点击 读取模型列表,选择远端允许使用的模型。未选择时 保持远端默认行为。 |
| 高级设置 → 允许访问此地址的内网或 HTTP 服务(可选) | 默认关闭。仅在确需访问内网或 HTTP 地址时开启,只放行当前地址的主机和端口。HTTP 会以明文传输凭证和数据,建议优先使用 HTTPS。 |
| 认证方式 | 使用说明 |
|---|---|
| 无认证 | 仅用于远程服务明确允许无需凭证访问的情况,同时开启 允许作为独立外部服务委派。 |
| 独立 Bearer Token | 在 第三方 Bearer Token 中填写远程服务提供的有效令牌,只填令牌本身,无需添加 Bearer 前缀。凭证加密保存,详情中不展示凭证值。 |
| 当前用户 CLI 授权 | 调用支持该认证方式的 AE 服务时,使用当前执行用户的 CLI 授权身份,无需手动填写独立 Token。 |
远端模型列表取决于当前认证身份的访问权限。若远程 Agent 不支持模型选择,保持默认行为即可;若已选模型失效,需重新读取列表并选择可用模型,或改回默认行为后保存。
如果目标是 AE 服务,也可以直接在会话中让 Agent 通过 AE CLI 调用,无需创建远程 Agent 连接。
选择远程 Agent 并验证调用
在会话中选择
- 打开会话,点击输入框的 加号 → 远程 Agent。
- 选择一个或多个已启用、可用的远程 Agent。已选项显示在输入框的引用区,可逐项移除。
- 输入任务目标、必要资料和期望结果,然后发送。
- 查看执行过程,确认是否发起远程委派并取得返回结果。远端需要补充信息时,按提示继续回复。
选择远程 Agent 表示让它成为当前任务的可用能力,模型会根据任务和远端 Agent Card 的能力说明判断是否委派,并不保证每次发送都会调用远端。若希望使用某个远程 Agent,可在任务中明确说明期望的分工。
例如,接入的远程 Agent 用于文案校对时,可输入:
请调用文案校对 Agent,检查下面这段文字的错别字,并说明修改原因:活动将于本周五开使,欢迎参与。
保存连接或读取到模型列表,只表示相应配置或发现步骤成功。首次使用仍应通过一次实际委派验证权限、网络与返回结果。
常见问题与限制
| 现象 | 检查与处理 |
|---|---|
| 无法读取 Agent Card,或保存连接失败 | 检查是否填写完整的 Card 地址、认证方式是否匹配,以及服务是否提供 A2A 1.0 JSON-RPC 接口。第三方服务需开启 允许作为独立外部服务委派;使用内网或 HTTP 地址时,检查对应高级设置。 |
| 外部平台读取 AE Card 或调用任务时鉴权失败 | 确认 Card 读取和任务请求都带有 Authorization 与 A2A-Version: 1.0 请求头;检查令牌所属用户是否有权访问该 Agent,以及该 Agent 是否已启用。 |
| 无法读取模型列表,或所选模型不可用 | 检查地址、认证信息和远端模型选择能力。重新读取列表,选择当前身份可用的模型;不指定模型时选择 保持远端默认行为。 |
| 提示不能保存 A2A Bearer Token | 若提示服务未配置凭证加密,请联系管理员完成服务配置后重试。 |
| 已选择远程 Agent,但没有发生委派 | 选择仅提供可用能力,模型仍会判断是否需要调用。确认连接已启用,并检查远端 Agent Card 的能力说明是否准确,在任务中明确需要远端完成的工作。 |
| 配置页能读取模型列表,实际委派却连接失败 | 配置页与任务执行环境的网络可达性可能不同。请管理员确认执行任务的沙箱能够直接访问远端 Card 及其声明的调用地址,并检查内网或 HTTP 访问设置。 |
| 提示沙箱尚不支持远程 Agent 按需委派 | 请管理员先升级配套沙箱,再部署与之匹配的应用版本,然后重新验证。 |
| 在 MCP 页面找不到原来的 A2A 连接 | 升级迁移会保留旧连接标识、凭证与绑定,迁移后在 Agent 库 → 远程 Agent 中管理。若升级后仍找不到,联系管理员核对迁移结果。 |
当前接入支持 A2A 1.0 JSON-RPC,不兼容 A2A 0.3,不能直接套用普通 MCP、REST 或 gRPC 的连接配置。外部平台调用 AE Agent 时仍必须提供有效的 Bearer 凭证;远程 Agent 配置中的 无认证 只适用于相应远程服务。附件传输、流式返回等能力取决于双方实际支持并声明的能力;建议先以文本任务完成接入验证。

