出站（UiPath 到外部）

在 Agent Gateway 中注册 UiPath 外部托管的 A2A 智能体，并为其调用配置身份验证。

备注：

此功能处于预览阶段。

出站 A2A 是指直接调用 UiPath 外部托管的智能体或作为 UiPath 智能体中的工具调用的平台。您可以在Agent Gateway > “A2A 智能体”中注册一次智能体，UiPath 会在其前面充当监管网关。

由于有两个跃点，因此存在两次独立的身份验证：调用者向 UiPath 进行身份验证，而 UiPath 单独向远程智能体进行身份验证。双方都无法看到另一方的凭据。

与第二个跃点特定的所有内容仅适用于此方向：Integration Service 连接、配置的标头、Orchestrator 资产引用和基于用户的连接。

注册远程 A2A 智能体

注册智能体后，便可从平台调用 UiPath 外部托管的 A2A 智能体。Agent Gateway 存储智能体的卡和凭据，并为其提供稳定的 UiPath URL，从此平台上任何具有 A2A 功能的使用者都将通过该 URL 访问智能体。

注册后，智能体的行为与 UiPath 中任何其他已部署的工件相同：位于文件夹中，文件夹权限控制谁可以调用它，护栏可以筛选其消息，调用将显示在追踪记录中，并且对其所做的更改都会经过审核。

外部客户端也可以使用已注册的 A2A 智能体。它们使用 UiPath 令牌调用 UiPath 公开的 A2A URL，与调用 UiPath 托管的智能体完全相同。有关接受的令牌和所需的权限，请查看身份验证。

先决条件

• 智能体的卡：或者是其 URL（通常以 /.well-known/agent-card.json 结尾），或者是原始卡 JSON（对于无法直接获取卡的智能体）。
• 无论智能体希望进行身份验证如何：静态标头值，例如 API 密钥或固定令牌，或已在 Orchestrator 中创建的连接。
• 目标文件夹中MCP 服务器的文件夹级“创建”权限。远程 A2A 智能体共享“MCP 服务器”权限集，并且Automation Developer 、 Folder Administrator和个人工作区管理员角色包括“创建”权限。Automation User只有“查看”权限，这足以调用智能体，但无法注册智能体。

注册代理

1. 在Agent Gateway > A2A 智能体中，选择添加外部智能体。

2. 输入“名称” 、 “缩略名”和“说明” 。

   备注：

   缩略名将成为智能体 UiPath URL 的一部分，并且在创建后无法更改。请仅使用小写字母、数字和连字符。

3. 通过 URL 或粘贴的 JSON 文件提供“智能体卡” 。

   备注：

   粘贴的 JSON 会自动填充“名称”和“说明”字段（如果有）。

4. 选择连接类型：对于通过公共互联网连接的智能体，选择标准；对于私有网络上的智能体，选择私有(中继) 。有关详细信息，请查看访问私有网络内的智能体。

5. 使用以下任一或同时配置智能体的身份验证：

   • 连接: 为智能体到智能体连接器创建一个连接，然后在此处选择该连接。选择后，Agent Gateway 每次调用时都会从连接中检索新的持有者令牌，因此无需手动轮换过期的凭据。
   • 标头: 添加到每个请求的名称-值对，以<key>:<value>形式添加，例如Authorization:Bearer <your-api-key> 。标头会加密存储，并在回读时进行掩码处理。标头值可以以 Authorization:%ASSETS/AssetName% 形式引用 Orchestrator 资产，而不是粘贴密码。

   如果两者都已设置，则连接将提供 Authorization 标头，其他标头仍适用。

6. （可选）展开“护栏”并进行配置。有关详细信息，请查看护栏。

7. 选择“保存”。

结果：Agent Gateway能够获取智能体的卡并进行缓存。智能体将显示在“A2A 智能体”列表中。如果提取失败，则保存将失败并显示提取错误，并且在卡可读之前不会存储任何内容。

外部客户看到的内容

注册智能体的住所：

https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}

您可以从A2A 智能体列表中复制此 URL。外部客户端完全可以像使用任何 A2A 智能体一样使用它：Agent Gateway 在 <that URL>/.well-known/agent-card.json 上提供智能体卡，并进行了重写，以便每个通告的端点都指向网关而不是上游主机，并且客户端向 UiPath 进行身份验证，而不是向 Automation Suite 进行身份验证。上游智能体。上游自己的身份验证方案永远不会泄漏。

每次调用时，**Agent Gateway** 都会验证调用者的 **UiPath** 令牌和文件夹访问权限，这需要对MCP 服务器的“查看”权限，因为 A2A 共享 MCP 服务器权限集。然后，它会根据智能体的防护机制筛选请求，去除调用者的 Authorization 标头，注入配置的凭据，然后按原样流式传输回响应，包括 SSE（服务器发送事件）。不会解析或重写消息，因此 A2A 0.3 和 1.0 客户端均可工作，并且客户端会选择具有 A2A-Version 标头的版本。调用将显示在“追踪”中。

注册后

• 当远程代理发生变更（例如，新端点、新技能或更新描述）时， “刷新卡”会重新获取卡。
• 用户配置允许个人用户附加自己的连接。对于智能体的调用，该连接优先于智能体的默认连接。

身份验证

通过 UiPath 调用 A2A 智能体涉及两个单独的身份验证，并且它们彼此独立。UiPath 使用注册智能体时配置的凭据，对其将请求转发给的智能体进行身份验证。调用者使用普通平台令牌单独向 UiPath 进行身份验证。双方都无法看到另一方的凭据。

注册智能体需要配置两部分。智能体卡片告知 UiPath 将消息发送至何处。凭据让 UiPath 在每次调用时向智能体进行身份验证，因为调用者的令牌永远不会被转发。凭据可以作为 Integration Service 连接和/或标头提供，也可以同时以两者形式提供。

智能体卡片

智能体卡片是 A2A 智能体发布用于描述自身的 JSON 文档：其名称、技能以及接受 JSON-RPC（JSON 远程过程调用）消息的端点。如果没有智能体卡，UiPath 无法路由调用，因此每次注册都会将智能体的卡作为路由和身份验证记录保留。

注册智能体需要拥有对目标文件夹中MCP 服务器的“创建”权限。远程 A2A 智能体共享 MCP 服务器权限集，因此 MCP 服务器权限也管理 A2A。

选项 1：提供智能体卡片的 URL

输入智能体卡片的 URL，通常是智能体的基本 URL，后跟 /.well-known/agent-card.json。此时，UiPath 使用在同一屏幕上配置的凭据获取它：附加的连接（如果有），或者配置的标头。此请求也将解析这些标头中的资产引用，因此无需粘贴密钥即可读取 Orchestrator 中存储的 API 密钥后面的卡。

在发出请求之前，系统会检查 URL 是否符合 SSRF（服务器端请求假冒请求）保护措施，除非可通过中继访问智能体。如果 UiPath 无法访问该地址，或者响应失败，则不会创建智能体。这是支持“稍后刷新卡”的唯一选项。

选项 2：粘贴卡 JSON

直接粘贴卡片文档。UiPath 不会发出任何出站请求，因此注册时不需要任何凭据，且 SSRF 检查不适用。对于在注册时无法从 UiPath 访问的智能体，或其卡无法通过公共地址发布的智能体，请使用此选项。如果同时提供了 URL 和粘贴的 JSON，则使用粘贴的 JSON，并且不进行提取。

无论卡如何到达，仅当它是通过 v0.3 url字段或 v1.0 supportedInterfaces列表公告可用 HTTP 或 HTTPS JSON-RPC 端点的 JSON 对象时，UiPath 才会接受。没有关联的卡将在注册时拒绝，而不是在调用时拒绝。

存储的卡不会在每次调用时重新提取，因此上游更改的卡不会自行更新。刷新卡需要再次获取，需要MCP 服务器的“编辑”权限，并且需要卡 URL：通过粘贴 JSON 注册的智能体没有任何权限，并且刷新将被拒绝。

备注：

刷新的身份验证方式与调用方式不同，而非注册方式：刷新使用为触发刷新的用户配置的连接，然后使用智能体的默认连接。因此，刷新可能对一个用户成功，而对另一个用户失败。

Integration Service 连接

附加与智能体的连接意味着 UiPath 会在每次调用时从中检索新的持有者令牌。对于凭据过期的智能体，这是更好的选项，因为无需手动轮换任何内容。连接与其所属的文件夹一起使用；如果缺少该文件夹，调用将失败，不会回退到另一个文件夹或已配置的标头。

标头

或者，将智能体需要的标头配置为名称值对。常见情况是 Authorization: Bearer <your-api-key>。标头会加密存储，并在回读时进行掩码处理，因此粘贴一次密码之后将不可见。

连接和标头优先级

如果已附加连接，则该连接将提供 Authorization 标头，并且同时配置的任何 Authorization 标头都将被忽略，而不是被覆盖：在解析资产引用之前，已配置的行将被删除，因此指向资产的标头不是我什至没有向上看。仍会发送所有其他配置的标头。相同的优先级适用于注册时的卡提取。

基于用户的连接数

个人用户可以通过智能体行上的“用户配置”附加自己的连接，这需要具有“连接”的“编辑”权限。调用智能体时，系统将按此顺序选择连接：

1. 为调用用户配置的连接。
2. 智能体的默认连接。
3. “无连接”，在这种情况下，使用配置的标头。如果未配置标头，则不发送任何身份验证。

系统会针对令牌所代表的任何身份选择连接。在计划运行或 Unattended 运行中，该身份不是智能体的构建或计划者，因此不会使用附加到自己用户名下的连接。如果必须通过 Unattended 运行访问智能体，请为其提供默认连接，而不是按用户连接。

用户配置还会显示每个连接的状态：

状态	意义
活动	连接已获得授权并已就绪。
需要身份验证	该用户没有可用的工作连接，可能是因为未配置任何连接，或者需要再次授权。
不可用	共享默认连接缺失、已禁用、已过期或无法访问。
不活动	智能体未处于活动状态，或连接已禁用。

引用 Orchestrator 资产

无需将密码粘贴到标头中，而应以 %ASSETS/AssetName% 形式为标头提供值。 UiPath 会将其解析为资产的值，然后发送请求，并以调用身份从智能体的文件夹中读取资产。如果无法读取资产，则调用将失败，而不是转发未解析的占位符。

支持 Text、Secret、Bool、Integer、Credential 和 Windows Credential 资产；凭据和 Windows 凭据资产解析为密码值。键值列表资产被拒绝，因为一个标头值必须解析为一个字符串。解析的值将作为配置的标头转发到远程代理，因此仅对您信任的拥有这些机密信息的端点使用资产支持标头。

联系私有网络内的智能体

如果智能体在私有网络内运行，没有入站防火墙端口，则可通过中继访问：UiPath 将请求发送至中继服务器，网络内的中继客户端收集请求并将其转发给智能体。中继改变了 UiPath 联系智能体的方式，而非对其进行身份验证的方式：连接、标头、其优先级和资产引用的所有行为与上述完全相同。SSRF 检查不适用于调用或卡获取，因为请求未发送到公共地址。

调用已注册的智能体

有两种调用者会到达已注册的远程智能体。UiPath 客户端，例如 UiPath 智能体或 Maestro 流，将智能体作为工具，平台在运行时解析地址、令牌和协议版本。直接 HTTP 客户端本身会调用智能体的 URL，并且必须提供所有三个 URL。两者的 UiPath 身份验证方式相同；本节的其余部分仅在直接调用时才重要。

每个请求的 Authorization 标头中都包含一个持有者令牌。在轮次之间不会结转任何内容：对话中的每条消息都需要单独进行身份验证。

您目前所达到的目标	调用者的需求
智能体本身	组织和租户的有效令牌、对包含智能体的文件夹的访问权限，以及对该文件夹中MCP 服务器的查看权限。Automation User 、 Automation Developer 、 Folder Administrator和个人工作区管理员角色都包含该角色。
其智能体卡片	仅限文件夹访问。卡片是发现元数据，因此它比智能体本身更容易访问。

正在获取令牌

A2A 使用与平台的其他部分相同的令牌。

方法	令牌来源	何时使用
个人访问令牌 (PAT)	“UiPath Cloud”，在您的用户首选项下	最简单的测试选项。其过期时间可配置，并且适用于任何 HTTP 客户端。
交互式登录	uipath auth	本地开发。令牌有效期约一个小时，且不会自动刷新。
外部应用程序	管理员 > 外部 Apps，客户端凭据	无人值守的调用程序，例如 CI/CD（持续集成/持续交付）管道和服务帐户，没有人在场登录。

有关如何创建每个身份验证，请查看MCP 服务器身份验证。A2A 智能体和 MCP 服务器由同一管道进行验证，因此任何适用于 MCP 服务器的令牌也适用于 A2A 智能体。一个例外是 MCP OAuth 流程，只有 MCP 端点支持该流程，因为它依赖于 A2A 智能体不发布的发现元数据。

正在获取智能体 URL

已注册的远程智能体驻留在：

https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}

其智能体卡片位于相同地址，后跟 /.well-known/agent-card.json。选择智能体行上的“复制URL”，从Agent Gateway >“A2A 智能体”中获取 URL，而不是手动组合：文件夹密钥是 GUID（全局唯一标识符），而不是文件夹名称，缩略名不是显示名称。

选择协议版本

远程 A2A 智能体支持 A2A v0.3 和 v1.0，使用 A2A-Version 请求标头选择：

• 对于 v1.0，将标头值设置为 1.0。
• 对于 v0.3，请省略标头。会以相同方式处理空值。

请求智能体卡时相同的标头适用，并决定 UiPath 返回的卡的版本。UiPath 仅将请求转发到与所请求版本匹配的端点；它不会回退到另一个版本，因为这会以其无法理解的传输格式向远程代理发送一条消息。如果存储的智能体卡未发布该版本的 JSON-RPC 端点，则请求将被拒绝，并会在响应中指明版本。

从不跨越边界的内容

三个东西在边界处停止：

• 调用者的令牌永远不会到达远程代理。UiPath 会对其进行验证，将其提取，然后注入为智能体配置的凭据。远程智能体无法通过 UiPath 了解谁调用了它，也无法重用该身份。UiPath 还删除自己的内部标头，并注入自己的单个出站追踪标头。
• 永远不会向调用者公布远程代理的身份验证方案。无论上游发布了何种内容，UiPath 服务的智能体卡始终声明 UiPath 自己的持有者身份验证，并且原始卡上的任何签名都将被删除，因为重写卡会使其失效。要查看远程代理发布的卡片，请打开智能体，然后选择“编辑” 。
• 调用无法通过平台环回。注册智能体时，指回 UiPath 的智能体卡 URL 会被拒绝。除此之外，每个代理请求都带有一个标记，已经带有标记的请求会被拒绝。

故障排除

有关您最有可能遇到的错误及其解决方法，请查看A2A 测试及故障排除。其“出站”部分涵盖此路径上的失败。

对于相反的方向，即外部客户端调用您部署的智能体，请选中“入站（UiPath 的外部）” 。