Autenticação Agent2Agent (A2A)

O protocolo Agent2Agent (A2A) permite que os seus agentes invoquem outros agentes. A maioria dos endpoints A2A requer autenticação para aceder ao endpoint e ao seu serviço subjacente. Configurar a autenticação garante que apenas utilizadores autorizados podem invocar as suas ferramentas A2A no Foundry Agent Service.

Este artigo explica os métodos de autenticação disponíveis para ligações A2A e ajuda-o a escolher a abordagem certa para o seu cenário.

Cenários de autenticação

Em geral, existem dois cenários de autenticação:

• Autenticação partilhada: Todos os utilizadores do seu agente usam a mesma identidade para autenticar no endpoint A2A. O contexto individual do utilizador não persiste. Esta abordagem é ideal quando todos os utilizadores devem ter o mesmo nível de acesso. Por exemplo, se criares um agente de chat para recuperar informação do Azure Cosmos DB para a tua organização, podes querer que todos os utilizadores acedam ao mesmo contentor partilhado sem necessidade de iniciar sessão individualmente.
• Autenticação individual: Cada utilizador do seu agente autentica-se com a sua própria conta, pelo que o seu contexto de utilizador persiste nas interações. Esta abordagem é essencial quando as ações devem ser submetidas às permissões do utilizador. Por exemplo, se criares um agente de programação que recupera commits e pull requests do GitHub, queres que cada programador faça login com a sua própria conta no GitHub para só ver repositórios a que tem acesso.

Pré-requisitos

Antes de escolher um método de autenticação, precisa de:

• Acesso ao Foundry portal e a um projeto. Se não tiveres um, vê Criar projetos no Foundry.
• O papel Azure AI User ou superior no seu projeto. Esta função concede permissões para criar ligações a projetos e configurar agentes. Para mais informações, consulte Controlo de acesso baseado em funções no portal Foundry.
• O URL do endpoint A2A ao qual queres ligar-te. Contacte o editor do endpoint para confirmar quais os métodos de autenticação que o endpoint suporta.
• Credenciais para o método de autenticação selecionado:
  • Baseado em chaves: Uma chave API, token de acesso pessoal (PAT) ou outro token secreto do editor do endpoint.
  • Autenticação Microsoft Entra: Atribuições de funções para a identidade do agente ou a identidade gerida do projeto no serviço subjacente. Os papéis específicos dependem do serviço (por exemplo, Cosmos DB Data Reader para Azure Cosmos DB).

Escolha um método de autenticação

O método de autenticação que escolher depende se precisa de contexto partilhado ou individual do utilizador, e dos protocolos de autenticação que o endpoint A2A suporta.

Use a tabela seguinte para escolher o método certo para o seu cenário:

Métodos de autenticação suportados

A tabela seguinte resume os métodos de autenticação disponíveis para ligações A2A:

Autenticação baseada em chaves

Utilize autenticação baseada em chaves quando o endpoint A2A aceita uma chave API, um token de acesso pessoal (PAT) ou outra credencial secreta. Para melhorar a segurança, armazene credenciais partilhadas numa ligação de projeto em vez de as passar em tempo de execução.

Quando liga o seu endpoint A2A a um agente no portal da Foundry, a Foundry cria uma ligação ao projeto para si. Forneça o nome da credencial (o nome do cabeçalho HTTP) e o valor da credencial (o valor do cabeçalho). O formato depende do que o endpoint espera.

Formatos comuns de credenciais:

Quando o agente invoca o endpoint A2A, o Agent Service recupera as credenciais da ligação ao projeto e inclui-as nos cabeçalhos do pedido.

Melhores práticas de segurança para autenticação baseada em chaves

• Use credenciais de privilégio mínimo: Peça apenas as permissões mínimas necessárias para as tarefas do agente.
• Rodar os tokens regularmente: Defina um lembrete para regenerar tokens antes de expirarem.
• Restringir o acesso a projetos: Limitar quem pode aceder a projetos que contenham segredos partilhados.
• Auditar uso de credenciais: Monitorar o acesso à conexão de projeto nos registos de atividade do Azure.

Autenticação do Microsoft Entra ID

Utilize autenticação Microsoft Entra ID quando o endpoint A2A e o seu serviço subjacente aceitarem tokens Microsoft Entra ID. Este método elimina a necessidade de gerir segredos porque o Azure gere automaticamente a aquisição e renovação dos tokens.

Identidade do agente

Use a identidade gerida do seu agente para autenticar com endpoints A2A que suportem autenticação Microsoft Entra ID. Quando cria um agente no Serviço de Agentes, o agente recebe automaticamente uma identidade gerida.

Ciclo de vida da identidade:

• Antes da publicação: Todos os agentes do mesmo projeto partilham uma identidade comum. Isto simplifica o desenvolvimento e os testes.
• Após a publicação: Cada agente publicado recebe uma identidade única. Isto proporciona isolamento e permite um controlo de acesso granular.

Para mais informações sobre o ciclo de vida da identidade do agente, consulte Conceitos de identidade do agente no Microsoft Foundry.

Para configurar a autenticação da identidade do agente:

1. Identifique o serviço subjacente que alimenta o endpoint A2A (por exemplo, Azure Cosmos DB ou Armazenamento do Azure).
2. Atribuir as funções necessárias à identidade do agente nesse serviço. Os papéis específicos dependem do serviço e das operações que o seu agente precisa de realizar.
3. Configure a ligação A2A para usar autenticação de identidade de agente.

Quando o agente invoca o endpoint A2A, o Agent Service utiliza a identidade do agente para solicitar um token de autorização ao Microsoft Entra ID e inclui-o no pedido.

Identidade gerida de um projeto Foundry

Utilize a identidade gerida do seu projeto Foundry para autenticar nos endpoints A2A. Esta opção é útil quando se quer que todos os agentes de um projeto partilhem a mesma identidade para aceder a recursos.

Para configurar a autenticação de identidade gerida por projeto:

1. Identifique o serviço subjacente que alimenta o endpoint A2A.
2. Atribua os papéis necessários à identidade gerida do projeto nesse serviço.
3. Configure a ligação A2A para usar autenticação de identidade gerida por projeto.

Quando o agente invoca o endpoint A2A, o Agent Service utiliza a identidade gerida do projeto para solicitar um token de autorização ao Microsoft Entra ID e inclui-lo no pedido.

Passagem de identidade OAuth

O passthrough de identidade OAuth permite que o seu agente atue em nome de utilizadores individuais. Use este método quando as ações devem estar subordinadas às permissões de cada utilizador, como aceder aos seus ficheiros pessoais, repositórios ou outros recursos protegidos.

A passagem de identidade OAuth funciona com endpoints A2A da Microsoft e não-Microsoft que suportam OAuth 2.0, incluindo serviços que utilizam o Microsoft Entra ID.

Como funciona o passthrough da identidade OAuth

1. Primeira interação: Quando um utilizador interage pela primeira vez com o seu agente, o Serviço de Agente gera um link de consentimento.
2. Consentimento do utilizador: O utilizador abre o link, inicia sessão no serviço subjacente e autoriza o agente a aceder aos seus dados.
3. Armazenamento de tokens: O Serviço de Agente armazena de forma segura os tokens OAuth do utilizador (token de acesso e token de atualização). Estes tokens estão direcionados para essa combinação específica de utilizador e agente.
4. Pedidos subsequentes: Quando o agente invoca o endpoint A2A, o Serviço do Agente inclui o token de acesso do utilizador no pedido. Se o token de acesso expirar, o Serviço de Agente usa o token de atualização para obter um novo.

Tipos de tokens OAuth

O OAuth utiliza dois tipos de tokens:

Os scopos OAuth definem o que o agente pode aceder e fazer em nome do utilizador. Os escopos são especificados quando configura a ligação e são apresentados ao utilizador durante o fluxo de consentimento. Para mais informações sobre o OAuth, consulte a documentação de segurança Microsoft.

OAuth gerido vs. OAuth personalizado

O Agent Service suporta duas opções de configuração OAuth:

Para configurar um OAuth personalizado, forneça a seguinte informação:

• ID do Cliente: O ID da sua aplicação registada no OAuth.
• Segredo do cliente (se necessário): O segredo associado ao registo da sua aplicação.
• URL de autorização: O endpoint onde os utilizadores autorizam o acesso.
• URL do Token: O ponto final onde o Serviço Agente troca o código de autorização dos tokens.
• URL de atualização: O endpoint para atualizar tokens de acesso expirados.
• Scopes: As permissões que o seu agente precisa (por exemplo, repo para GitHub ou Files.Read para Microsoft Graph).

Acesso não autenticado

Utilize acesso não autenticado apenas quando o endpoint A2A for publicamente acessível e não exigir autenticação. Esta opção é rara em cenários de produção, mas pode ser adequada para:

• APIs públicas que não requerem autenticação
• Endpoints internos de desenvolvimento ou teste
• Endpoints protegidos por segurança ao nível da rede (como endpoints privados) em vez de autenticação

Configurar autenticação para uma ligação A2A

Siga estes passos para configurar a autenticação para uma ligação A2A:

1. Identifique o endpoint A2A e os métodos de autenticação suportados. Contacte o editor do endpoint ou consulte a documentação do endpoint para determinar quais os métodos de autenticação suportados.

2. Recolha as credenciais necessárias com base no método de autenticação escolhido:

   • Baseado em chave: Obter a chave API ou token do publicador do endpoint.
   • Microsoft Entra ID: Identificar as atribuições de funções necessárias para o serviço subjacente.
   • OAuth: Determine se o OAuth gerido está disponível, ou reúna os detalhes personalizados do registo da sua aplicação OAuth.

3. Crie uma ligação ao projeto no portal da Foundry. A ligação armazena o URL do endpoint A2A, o método de autenticação e as credenciais.

   • Para orientações gerais sobre ligações, consulte Adicionar uma nova ligação ao seu projeto.
   • Para configuração específica de A2A, veja Adicionar um endpoint de agente A2A ao Serviço de Agentes Foundry.

4. Configurar atribuições de funções (apenas autenticação do Microsoft Entra ID). Atribuir os papéis necessários à identidade do agente ou à identidade gerida do projeto no serviço subjacente.

5. Adicione a ferramenta A2A ao seu agente. Consulte a ligação ao projeto que criou e configure quais as ferramentas do endpoint A2A que o seu agente pode invocar.

Validar autenticação

Depois de configurares a autenticação, testa a ligação para confirmar se funciona corretamente.

Validar a autenticação baseada em chave ou Microsoft Entra ID

1. Abra o seu agente no portal da Foundry.
2. Inicia uma conversa e desencadeia uma ação que invoca a ferramenta A2A.
3. Confirme que a chamada de ferramenta foi concluída com sucesso. Se a chamada falhar, verifique a mensagem de erro e veja Resolução de Problemas.

Validar a autenticação de passagem de identidade do OAuth

1. Abra o seu agente no portal Foundry usando uma conta de utilizador de teste que não tenha consentido anteriormente.
2. Inicia uma conversa e desencadeia uma ação que invoca a ferramenta A2A.
3. Confirme que aparece um link de consentimento na resposta do agente.
4. Abra o link de consentimento e inicie sessão com as credenciais do utilizador de teste.
5. Autorize as permissões solicitadas.
6. Retorne ao agente e ative novamente a ferramenta A2A.
7. Confirme que a chamada à ferramenta foi concluída com sucesso usando as credenciais do utilizador de teste.
8. (Opcional) Teste com outra conta de utilizador para confirmar que os fluxos de consentimento funcionam para vários utilizadores.

Resolução de problemas

Use a tabela seguinte para diagnosticar e resolver problemas comuns de autenticação:

Conteúdo relacionado

• Adicione um endpoint de agente A2A ao Foundry Agent Service: Guia passo a passo para configurar uma ferramenta A2A para o seu agente.
• Conceitos de identidade de agente em Microsoft Foundry: Aprenda como funcionam as identidades dos agentes e o seu ciclo de vida.
• Controlo de acesso baseado em papéis para Microsoft Foundry: Compreenda os papéis e permissões disponíveis no Foundry.
• Adicione uma nova ligação ao seu projeto: Orientação geral para criar ligações ao projeto.