Saída (UiPath para externo)

Registre um agente A2A hospedado fora da UiPath no Agent Gateway e configure a autenticação para chamadas para ele.

Observação:

Essa funcionalidade está em visualização.

A saída A2A é a plataforma que chama um agente hospedado fora da UiPath, diretamente ou como uma ferramenta dentro de um agente da UiPath. Você registra o agente uma vez em Agent Gateway > Agentes A2A, e a UiPath atua como um gateway governado na frente dele.

Como existem dois saltos, há duas autenticações independentes: o chamador autentica-se na UiPath, e a UiPath autentica-se separadamente no agente remoto. Nenhum lado vê as credenciais do outro.

Tudo específico para esse segundo salto se aplica apenas para essa direção: conexões do Integration Service, cabeçalhos configurados, referências de ativos do Orchestrator e conexões por usuário.

Registrar um agente A2A remoto

O registro de um agente torna um agente A2A hospedado fora da UiPath chamável a partir da plataforma. O Agent Gateway armazena o cartão e as credenciais do agente, fornece a ele um URL da UiPath estável e, a partir de então, qualquer consumidor com capacidade de A2A na plataforma alcança o agente por meio desse URL.

Depois de registrado, o agente se comporta como qualquer outro artefato implantado na UiPath: ele reside em uma pasta, as permissões da pasta governam quem pode chamá-lo, as proteções podem filtrar suas mensagens, as chamadas aparecem em Traces e as alterações feitas nela são auditadas.

Um agente A2A registrado também pode ser consumido por clientes externos. Eles chamam a URL A2A exposta pela UiPath com um token da UiPath, exatamente como fariam para um agente hospedado pela UiPath. Para os tokens aceitos e as permissões necessárias, consulte Autenticação.

Pré-requisitos

• O cartão do agente: seu URL, normalmente terminando em /.well-known/agent-card.json, ou o cartão bruto JSON, para agentes cujo cartão não pode ser buscado diretamente.
• O que o agente espera para autenticação: valores de cabeçalho estáticos, como uma chave de API ou um token fixo, ou uma conexão já criada no Orchestrator.
• A permissão Criar no nível da pasta para servidores MCP na pasta de destino. Os agentes A2A remotos compartilham o conjunto de permissões Servidores MCP, e as funções Automation Developer, Folder Administrator e Personal Workspace Administrator incluem Criar. O Automation User tem apenas Visualização , o que é suficiente para chamar um agente, mas não para registrar um.

Registrar o agente

1. Em Agent Gateway > Agentes A2A, selecione Adicionar agente externo.

2. Insira um Nome, Campo de dados dinâmico e Descrição.

   Observação:

   O campo de dados dinâmico se torna parte do URL da UiPath do agente e não pode ser alterado após a criação. Use somente letras minúsculas, números e hifens.

3. Forneça o cartão do agente por URL ou como JSON colado.

   Observação:

   O JSON colado preenche automaticamente os campos Nome e Descrição , se houver.

4. Selecione o tipo de Conexão: padrão para um agente acessível pela internet pública ou Privado (Relay) para um agente em uma rede privada. Para obter detalhes, consulte Alcance de um agente dentro de uma rede privada.

5. Configure a autenticação para o agente, usando um ou ambos os seguintes:

   • Conexão: crie uma conexão para o conector Agent2Agent e, em seguida, selecione-a aqui. Após selecionado, o Agent Gateway recupera um novo token de portador da conexão em cada chamada, para que as credenciais que expiram não precisem ser rotacionadas manualmente.
   • Cabeçalhos: pares de nome e valor adicionados a cada solicitação, no formulário <key>:<value>, por exemplo Authorization:Bearer <your-api-key>. Os cabeçalhos são armazenados criptografados e mascarados quando lidos de volta. Em vez de colar um segredo, um valor de cabeçalho pode fazer referência a um ativo do Orchestrator, no formulário Authorization:%ASSETS/AssetName%.

   Se ambos estiverem definidos, a conexão fornece o cabeçalho Authorization, e os outros cabeçalhos ainda se aplicam.

6. Opcionalmente, expanda Proteções e configure-as. Para obter detalhes, consulte Proteções.

7. Selecione Salvar.

Resultado: o Agent Gateway busca o cartão do agente e o armazena em cache. O agente aparece na lista Agentes A2A . Se a busca falhar, o salvamento falha com o erro de busca e nada é armazenado até que o cartão esteja legível.

O que os clientes externos veem

O agente registrado reside em:

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

Você pode copiar este URL da lista de Agentes A2A . Um cliente externo o usa exatamente como faria para qualquer agente A2A: o Agent Gateway atende o cartão do agente em <that URL>/.well-known/agent-card.json, reescrito para que cada endpoint anunciado aponte no gateway em vez do host upstream e o cliente se autentique para a UiPath em vez de para o agente upstream. O próprio esquema de autenticação do upstream nunca vaza.

Em cada chamada, o Agent Gateway valida o token UiPath e o acesso à pasta do chamador, o que requer a permissão Visualizar em Servidores MCP, pois A2A compartilha o conjunto de permissões Servidores MCP. Em seguida, ele filtra a solicitação contra as proteções do agente, remove o cabeçalho Authorization do chamador, injeta as credenciais configuradas e transmite a resposta de volta intacta, incluindo SSE (Server-Sent Events). As mensagens não são analisadas ou reescritas; portanto, os clientes A2A 0.3 e 1.0 funcionam e um cliente seleciona uma versão com o cabeçalho A2A-Version. As chamadas aparecem em Traces.

Após o registro

• Atualizar cartão busca novamente o cartão quando o agente remoto muda, por exemplo, um novo ponto de extremidade, novas habilidades ou uma descrição atualizada.
• Configurações do usuário permite que usuários individuais anexem sua própria conexão. Para suas chamadas, tem precedência sobre a conexão padrão do agente.

Autenticação

A chamada de um agente A2A por meio da UiPath envolve duas autenticações separadas e elas são independentes uma da outra. A UiPath autentica-se no agente para o qual encaminha a solicitação, usando credenciais configuradas uma vez quando o agente é registrado. O chamador autentica-se na UiPath separadamente, com um token de plataforma comum. Nenhum lado vê as credenciais do outro.

O registro de um agente configura duas coisas. O cartão do agente informa à UiPath para onde enviar mensagens. As credenciais permitem que a UiPath autentique para o agente em todas as chamadas, já que o token do chamador nunca é encaminhado. As credenciais podem ser fornecidas como uma conexão do Integration Service, como cabeçalhos ou como ambos.

O cartão do agente

Um cartão de agente é o documento JSON que um agente A2A publica para descrever a si mesmo: seu nome, suas habilidades e o endpoint que aceita mensagens JSON-RPC (Chamada de Procedimento Remoto JSON). A UiPath não pode rotear uma chamada sem um, então cada registro persiste o cartão do agente como o registro de roteamento e autenticação.

O registro de um agente requer a permissão Criar em servidores MCP na pasta de destino. Os agentes A2A remotos compartilham o conjunto de permissões dos Servidores MCP, portanto, as permissões dos Servidores MCP também governam o A2A.

Opção 1: forneça o URL para o cartão do agente

Insira a URL do cartão do agente, geralmente a URL base do agente seguida /.well-known/agent-card.json por. A UiPath a busca nesse momento, usando as credenciais configuradas na mesma tela: a conexão anexada, se houver, ou os cabeçalhos configurados, caso contrário. As referências de ativos nesses cabeçalhos também foram resolvidas para esta solicitação. Assim, um cartão atrás de uma chave de API armazenada no Orchestrator pode ser lido sem colar a chave.

O URL é verificado contra a proteção SSRF (Server-Side Request Forgery) antes que a solicitação seja feita, a menos que o agente seja alcançado por meio do relay. Se a UiPath não puder alcançar o endereço ou a resposta não for um sucesso, o agente não será criado. Essa é a única opção compatível com Atualizar cartão posteriormente.

Opção 2: colar o JSON do cartão

Cole o documento do cartão diretamente. A UiPath não faz nenhuma solicitação de saída, portanto, nenhuma credencial é necessária no momento do registro, e a verificação SSRF não se aplica. Use esta opção para um agente que não é acessível a partir da UiPath no momento do registro ou cujo cartão não é servido em um endereço público. Se um URL e o JSON colado forem fornecidos, o JSON colado será usado e nenhuma busca acontecerá.

Independentemente de como o cartão chegar, a UiPath o aceitará apenas se for um objeto JSON que anuncia um ponto de extremidade HTTP ou HTTPS JSON-RPC utilizável, por meio do campo v0.3 url ou da lista supportedInterfaces v1.0. Um cartão sem um é rejeitado no registro e não no momento da chamada.

O cartão armazenado não é buscado novamente em cada chamada, portanto, um cartão que muda upstream não é atualizado por conta própria. Atualizar cartão busca-o novamente, requer a permissão Editar em Servidores MCP e requer um URL de cartão: um agente registrado colando JSON não tem nenhum, e a atualização é recusada.

Observação:

Uma atualização é autenticada da forma como uma chamada é, não da forma como o registro era: ela usa a conexão configurada para o usuário que a dispara e retorna à conexão padrão do agente. Portanto, uma atualização pode ser bem-sucedida para um usuário e falhar para outro.

Uma conexão do Integration Service

Anexar uma conexão ao agente significa que a UiPath recupera um novo token de portador em cada chamada. Essa é a melhor opção para qualquer agente cujas credenciais expiram, já que nada precisa ser girado manualmente. A conexão é usada junto com a pasta a que ela pertence; se essa pasta estiver ausente, a chamada falhará em vez de recair em outra pasta ou para um cabeçalho configurado.

Cabeçalhos

Ou então, configure os cabeçalhos que o agente espera como pares de nome e valor. O caso comum é Authorization: Bearer <your-api-key>. Os cabeçalhos são armazenados criptografados e mascarados quando lidos de volta, portanto, um segredo colado uma vez não fica visível depois.

Preferência de conexão e cabeçalho

Se uma conexão estiver anexada, ela fornecerá o cabeçalho Authorization, e qualquer cabeçalho Authorization configurado também será ignorado em vez de simplesmente substituído: a linha configurada é removida antes que as referências de ativos sejam resolvidas, portanto, um cabeçalho apontando para um ativo não é nem mesmo olha para cima. Todos os outros cabeçalhos configurados ainda são enviados. A mesma precedência se aplica à busca do cartão no momento do registro.

Conexões por usuário

Os usuários individuais podem anexar uma conexão própria por meio das Configurações do usuário na linha do agente, o que requer a permissão Editar em Conexões. Quando o agente é chamado, a conexão é selecionada nesta ordem:

1. A conexão configurada para o usuário de chamada.
2. A conexão padrão do agente.
3. Sem conexão; no caso, os cabeçalhos configurados são usados ou nenhuma autenticação é enviada se nenhum estiver configurado.

A conexão é escolhida para qualquer identidade que o token represente. Em uma execução agendada ou unattended, essa identidade não é a pessoa que criou ou agendou o agente, portanto, uma conexão anexada sob o próprio usuário de alguém não é usada lá. Se um agente precisar ser acessível a partir de execuções unattended, dê a ele uma conexão padrão em vez de depender de conexões por usuário.

As configurações do usuário também mostram o estado de cada conexão:

Status	Significado
Ativo	A conexão foi autorizada e está pronta.
Requer autenticação	Nenhuma conexão de trabalho está disponível para este usuário, seja porque nenhuma está configurada ou porque ele precisa de autorização novamente.
Indisponível	A conexão padrão compartilhada está ausente, está desabilitada, expirou ou não pôde ser atingida.
Inativo	O agente não está ativo ou a conexão está desabilitada.

Referenciar um ativo do Orchestrator

Em vez de colar um segredo em um cabeçalho, dê ao cabeçalho um valor no formulário %ASSETS/AssetName%. A UiPath o resolve para o valor do ativo antes de enviar a solicitação, lendo o ativo da pasta do agente sob a identidade da chamada. Se o ativo não puder ser lido, a chamada falhará em vez de encaminhar o espaço reservado não resolvido.

Os ativos Text, Secret, Bool, Integer, Credential e Windows Credential são compatíveis; Os ativos Credential e Windows Credential são resolvidos no valor da senha. Os ativos da lista de valores-chave são rejeitados, pois um valor de cabeçalho deve ser resolvido em uma string. O valor resolvido é encaminhado para o agente remoto como o cabeçalho configurado; portanto, use cabeçalhos baseados em ativos apenas para pontos de extremidade em que você confia com esses segredos.

Alcance de um agente dentro de uma rede privada

Um agente que é executado dentro de uma rede privada sem portas de firewall de entrada é alcançado por meio do relay: a UiPath envia a solicitação para um servidor de relay, e um cliente de relay dentro da rede a coleta e encaminha para o agente. O relay muda como a UiPath alcança o agente, não como se autentica nele: a conexão, os cabeçalhos, sua precedência e as referências de ativos se comportam exatamente conforme descrito acima. A verificação SSRF não se aplica à chamada ou à busca do cartão, pois a solicitação não é enviada para um endereço público.

Chamada de um agente registrado

Dois tipos de chamador alcançam um agente remoto registrado. Um cliente UiPath, como um agente UiPath ou um fluxo Maestro, usa o agente como uma ferramenta, e a plataforma resolve o endereço, o token e a versão do protocolo no runtime. Um cliente HTTP direto chama a própria URL do agente e deve fornecer as três. Ambos autenticam para a UiPath da mesma maneira; o resto desta seção é importante apenas ao chamar diretamente.

Cada solicitação carrega um token de portador no cabeçalho.Authorization Nada é carregado entre as etapas: cada mensagem em uma conversa é autenticada por conta própria.

O que você está alcançando	O que o chamador precisa
O próprio agente	Um token válido para a organização e o tenant, acesso à pasta que contém o agente e a permissão Visualizar em servidores MCP nessa pasta. As funções Automation User, Automation Developer, Folder Administrator e Personal Workspace Administrator o incluem.
Seu cartão de agente	Somente acesso à pasta. O cartão é metadados de descoberta, então é deliberadamente mais fácil de alcançar do que o próprio agente.

Como obter um token

O A2A usa os mesmos tokens que o restante da plataforma.

Método	Origem do token	quando usar
Token de acesso pessoal (PAT)	UiPath Cloud, em suas preferências de usuário	A opção mais simples para testes. Sua expiração é configurável e funciona com qualquer cliente HTTP.
Logon interativo	uipath auth	Desenvolvimento local. O token dura cerca de uma hora e não é atualizado automaticamente.
Aplicativo Externo	Administrador > Apps externos, credenciais do cliente	Chamadores não assistidos, como pipelines de CI/CD (Integração contínua/Entrega contínua) e contas de serviço, onde ninguém está presente para fazer login.

Para saber como criar cada uma, consulte Autenticação do servidor MCP. Os agentes A2A e servidores MCP são validados pelo mesmo pipeline, portanto, qualquer token que funcione para um servidor MCP também funciona para um agente A2A. A única exceção é o fluxo MCP OAuth, que apenas os pontos de extremidade do MCP suportam, pois depende de metadados de descoberta que os agentes A2A não publicam.

Obtendo a URL do agente

Um agente remoto registrado reside em:

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

Seu cartão de agente está no mesmo endereço seguido /.well-known/agent-card.json por. Obtenha o URL do Agent Gateway > Agentes A2A selecionando Copiar URL na linha do agente, em vez de montar o URL manualmente: a chave da pasta é um GUID (identificador exclusivo global), em vez de um nome de pasta, e o campo de dados dinâmico não é a exibição nome.

Selecionando a versão do protocolo

Os agentes A2A remotos são compatíveis com A2A v0.3 e v1.0, selecionados com o cabeçalho de solicitação A2A-Version:

• Para v1.0, defina o valor do cabeçalho 1.0 como.
• Para v0.3, omita o cabeçalho. Um valor vazio ou em branco é tratado da mesma maneira.

O mesmo cabeçalho aplica-se ao solicitar o cartão de agente e determina qual versão do cartão a UiPath retorna. A UiPath encaminha uma solicitação apenas para um ponto de extremidade que corresponda à versão solicitada; ele não recairá em outra versão, pois isso enviaria ao agente remoto uma mensagem em um formato de conexão que ele não compreende. Se o cartão do agente armazenado não publicar nenhum ponto de extremidade JSON-RPC para essa versão, a solicitação será rejeitada e a versão será nomeada na resposta.

O que nunca ultrapassa o limite

Três coisas são interrompidas no limite:

• O token do chamador nunca chega ao agente remoto. A UiPath o valida, o remove e injeta as credenciais configuradas para o agente. O agente remoto não tem como saber quem o chamado por meio da UiPath ou reutilizar essa identidade. A UiPath também remove seus próprios cabeçalhos internos e injeta um único cabeçalho de trace de saída.
• O esquema de autenticação do agente remoto nunca é anunciado para os chamadores. O cartão de agente que a UiPath atende sempre declara a própria autenticação de portador da UiPath, independentemente do upstream publicado, e qualquer assinatura no cartão original é removida, pois reescrever o cartão o invalida. Para ver o cartão como o agente remoto o publicou, abra o agente e selecione Editar.
• Uma chamada não pode retornar pela plataforma. Uma URL do cartão de agente que aponta para a UiPath é rejeitada ao registrar o agente. Além disso, toda solicitação proxy carrega um marcador, e uma solicitação que já o carrega é recusada.

Solução de problemas

Para os erros que você mais provavelmente encontrará e como resolvê-los, consulte Testar e solucionar problemas A2A. Sua seção de Saída abrange as falhas nesse caminho.

Para a direção oposto, onde um cliente externo chama um agente que você implantou, consulte Entrada (externo à UiPath).