Entrada (externo para a UiPath)

Como um agente ou cliente externo mantém uma conversa com um agente de conversação que você implantou no Orchestrator e como essas chamadas são autenticadas.

Observação:

Essa funcionalidade está em visualização.

A entrada A2A é um agente externo ou cliente que mantém uma conversa com um agente de conversa que você implantou na UiPath Platform. A UiPath é o destino da chamada, não um gateway na frente de outra coisa.

Não há nada para registrar para esta direção. Cada agente de conversa implantado em uma pasta já fala A2A: o Agent Gateway atende seu cartão de agente e traduz o tráfego A2A em uma conversa nativa com o agente. Qualquer cliente A2A pode usar o agente apenas com o URL do cartão e um token da UiPath.

Como o UiPath é o destino, há apenas uma autenticação a configurar: o chamador autenticando-se no UiPath. As conexões, cabeçalhos e referências de ativos do Orchestrator que aparecem na direção de saída não têm contraparte aqui.

Expor agentes de conversa implantados

O cartão do agente

Cada agente implantado tem um cartão em:

https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}/.well-known/agent-card.json

{folderKey} é a chave da pasta na qual o agente é implantado e {agentReleaseId} é o ID da versão do agente de conversa implantado.

O cartão é gerado a partir da implantação atual, portanto, seu nome, descrição e versão sempre correspondem ao que está implantado. Ele anuncia streaming, entrada/saída de texto e arquivo e autenticação do portador. Não há descoberta anônima: buscar o cartão já requer um token da UiPath.

Você pode copiar o URL A2A em Automações > Processos > Copiar URL do cartão A2A. Você também pode inspecionar a URL A2A e o cartão do agente na aba Agentes implantados , após selecionar o agente de conversa.

Chamando o agente

O ponto de extremidade JSON-RPC (Chamada de Procedimento Remoto JSON) é o URL do cartão sem o sufixo /.well-known/agent-card.json. Sobre a conexão, uma chamada se parece com isso:

POST https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}
Authorization: Bearer <your-access-token>

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "messageId": "m1",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "hi"
        }
      ]
    }
  }
}

Uma tarefa A2A representa uma conversa com o agente. A primeira mensagem cria a tarefa, e a resposta carrega um contextId; incluir esse ID na próxima mensagem continua a mesma conversa. Após cada resposta, o estado da tarefa é input-required, mantendo a conversa aberta para mensagens de acompanhamento.

message/stream retorna a resposta como um stream SSE (Eventos enviados pelo servidor). tasks/get lê o estado e o histórico de uma tarefa, e tasks/cancel cancela uma tarefa em execução. As notificações por push e tasks/resubscribe não são compatíveis, então a saída ao vivo requer message/stream.

Autenticação

A entrada A2A tem uma única autenticação: o chamador que se autentica na UiPath. A UiPath é o destino da chamada, portanto, não há um segundo salto e nenhuma credencial upstream para configurar.

Cada solicitação carrega um token de portador no cabeçalho Authorization, incluindo a solicitação para o cartão do agente. Não há descoberta anônima e nada é levado entre as etapas: cada mensagem em uma conversa é autenticada por conta própria.

O que o chamador precisa

O token deve ser válido para a organização e o tenant nomeados no URL, e a pasta nomeada no URL deve ser aquela que a identidade da chamada pode ver. Nada mais é necessário: nenhuma permissão de pasta, nenhum escopo específico para A2A e nenhum equivalente da permissão Visualizar em Servidores MCP de que uma chamada de saída precisa. Identidade e pasta são tudo o que o UiPath verifica aqui, e nada inspeciona o conteúdo de uma mensagem.

Qualquer token que funcione em outro lugar da plataforma funciona aqui: login interativo, aplicativos externos ou um token de acesso pessoal, que é o mais simples para testes.

Observação:

Crie um token de acesso pessoal com o recurso Acesso à API do Orchestrator selecionado, porque esse recurso define o público que esse ponto de extremidade verifica. Sem ele, o token é rejeitado antes que a chamada atinja o agente, e o erro nomeia o público em vez do token, portanto, não parece um problema de escopo.

Para obter cada tipo de token, consulte Autenticação do servidor MCP.

A UiPath valida o token, resolve a pasta e encaminha a solicitação para o serviço que executa o agente de conversa, com o token do chamador anexado. A entrada é a única direção na qual o token do chamador navega além do Agent Gateway. Ele permanece dentro da UiPath, porque o serviço que executa o agente é um serviço da UiPath. Em uma chamada de saída, o token é removido do limite e substituído pelas credenciais configuradas para o agente remoto.

Selecionando a versão do cartão

Apenas o ponto de extremidade do cartão do agente lê o A2A-Version cabeçalho opcional; o ponto de extremidade da mensagem o ignora. Um cliente v1.0 envia o cabeçalho por conta própria, portanto, raramente você precisa defini-lo por conta própria.

• Envie 1.0 para o cartão estrito v1.0.
• Enviar 0.3 para o cartão restrito v0.3, que não traz v1.0 campos e é adequado para um cliente cujo desserializador rejeita propriedades desconhecidas.
• Não envie nada ou qualquer outro valor, e você recebe um cartão v0.3 com a propriedade v1.0 supportedInterfaces adicionada, para que um cliente v1.0 que não enviou o cabeçalho ainda possa lê-lo.

O ponto de extremidade de mensagem aceita ambos os formatos de conexão, independentemente do cabeçalho, portanto, um cliente v1.0 e v0.3 podem se comunicar com o mesmo agente. O valor é correspondente exatamente, então 1.0.0 não é tratado como 1.0. E omitir o cabeçalho não dá a você o cartão estritamente v0.3 aqui, como dá para um agente remoto registrado. Se você está comparando as duas direções, é por isso que seus cartões diferem.

Solução de problemas

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

Para a direção oposto, onde a UiPath chama um agente hospedado em outro lugar, consulte Saída (UiPath para externo).