Adicionar um agente Agent2Agent (A2A) como agente conectado (GitHub Copilot)

Use agentes ligados para permitir que o seu agente principal delegue tarefas específicas a agentes especializados. Este artigo mostra-lhe como ligar um agente remoto disponível através do protocolo Agent2Agent (A2A), para que o seu agente principal possa passar tarefas para ele.

Note

A estrutura usada para construir este agente utiliza faturação baseada no uso. Usar, construir, testar e avaliar agentes podem consumir Créditos Copilot. Saiba mais em Visão Geral da faturação baseada no uso.

O protocolo A2A é um padrão aberto para comunicação e colaboração entre agentes. Como é um standard aberto, podes ligar agentes que estão alojados fora do Copilot Studio e construídos sobre outros frameworks, desde que implementem A2A. O Copilot Studio descobre o agente remoto a partir do agent card e usa o protocolo A2A para delegar tarefas a ele em tempo de execução.

Adicionam-se todos os agentes ligados a partir do mesmo diálogo Adicionar um agente ligado. Para uma visão geral dos agentes conectados e de como funciona o encaminhamento, veja Visão Geral dos Agentes Conectados. Para associar outro agente do Copilot Studio, veja Adicionar um agente do Copilot Studio como agente associado. Para ligar um agente Microsoft Foundry, veja Adicionar um agente Foundry como agente ligado.

Prerequisites

  • Um agente criado com o GitHub Copilot harness para ser o agente principal. Consulte Criar um agente (pré-visualização).
  • Um agente remoto que implementa o protocolo Agente-a-Agente e é acessível a partir do Copilot Studio através da internet pública.
  • O URL do cartão de agente do agente remoto, normalmente https://<your-agent-host>/.well-known/agent-card.json.
  • Os detalhes de autenticação que o agente remoto exige, se houver. O Copilot Studio suporta sem autenticação, chave de API e OAuth 2.0.
  • Para o OAuth 2.0, permissão para adicionar um URI de redirecionamento ao registo da aplicação que o fornecedor de identidade do agente remoto utiliza. O Copilot Studio gera a URL de redirecionamento durante o assistente, e tem de registá-la antes de criar a ligação.

Note

Como as ligações A2A utilizam a infraestrutura de conectores personalizados, também pode usá-las para se ligar a agentes A2A que estão a funcionar localmente ou dentro de uma rede virtual.

Adicionar um agente Agent2Agent (A2A)

O assistente guia-o por três ou quatro passos, dependendo do método de autenticação que escolher:

  • Se escolher Nenhum ou chave API: Ligue-se a um agente A2A, ligue-se ao agente A2A, depois Revise e adicione.
  • Se escolher OAuth 2.0: Ligue-se a um agente A2A, adicione URL de redirecionamento, ligue-se ao agente A2A, depois revise e adicione.

  1. Inicia sessão no Copilot Studio.

  2. Escolha e abra o agente que pretende usar como agente principal.

  3. Na barra de navegação do agente, selecione o separador Build .

  4. No painel de componentes, selecione Agentes ligados para abrir o diálogo Adicionar um agente ligado.

  5. No diálogo, selecione Adicionar e depois selecione Adicionar agente A2A.

  6. No passo Ligar a um agente A2A , introduza os dados do agente remoto:

    • URL do cartão do agente: o URL do cartão do agente remoto, por exemplo, https://agent.example.com/.well-known/agent-card.json. O Copilot Studio lê o cartão para descobrir o endpoint e as capacidades do agente.
    • Nome: o nome mostrado ao agente autor. Se o cartão de agente incluir um nome, o Copilot Studio preenche este campo para si.
    • Descrição: uma descrição clara de quando este agente A2A deve ser utilizado, entre 30 e 1.000 caracteres. Se o cartão do agente incluir uma descrição, o Copilot Studio preenche este campo por si. O orquestrador usa esta descrição para decidir quando encaminhar um pedido para o agente, por isso, torne-a específica e evite sobreposições com as suas outras ferramentas e agentes. Saiba mais sobre como escrever metadados eficazes.

    Note

    Se o nome e a descrição não forem preenchidos automaticamente, o agente remoto pode não ter cartão de agente, o cartão pode estar numa URL diferente daquela que introduziu, ou o Copilot Studio pode não conseguir aceder a ele. Verifique primeiro o URL e tente abrir o cartão do agente no seu navegador. Se o cartão não estiver disponível, introduza manualmente um nome e uma descrição.

  7. Em Autenticação, selecione como o Copilot Studio autentica com o agente remoto e, em seguida, complete os detalhes do método que escolheu:

    Não pode continuar até que os detalhes da autenticação estejam completos.

  8. Selecione Seguinte.

  9. Se selecionares o OAuth 2.0, aparece o passo Adicionar URL de redirecionamento . O Copilot Studio cria o conector para o agente A2A, e a plataforma gera um URL de redirecionamento para ele. Registe esse URL junto do seu fornecedor de identidade antes de criar a ligação:

    1. Espera que o campo do URL de Redirecionamento seja preenchido. O conector tem de existir antes de a URL ser gerada.
    2. Selecione o botão de copiar ao lado do campo para copiar o URL.
    3. No registo da tua app OAuth, adiciona o URL como URI de redirecionamento e guarda o registo da app.
    4. Selecione Seguinte.

    Importante

    Se não registares primeiro o URL de redirecionamento, a primeira tentativa de autorizar a ligação falha. O URL de redirecionamento é gerado por conector, por isso é específico para este agente A2A e não pode ser reutilizado a partir de outro conector. Se precisares do URL novamente mais tarde, seleciona o agente A2A em Agentes Conectados no painel de componentes para o reabrir.

  10. No passo Ligar ao agente A2A , escolha a ligação que este agente usa para chegar ao agente remoto:

    • Selecione uma conexão existente da lista de conexões disponíveis.
    • Se não houver conexão disponível, crie uma nova conexão. Se o agente remoto usar autenticação por chave API, introduz o valor da chave API ao criar a ligação.

  11. Selecione Seguinte.

  12. No passo de Revisão e Adicionar , revê o nome, descrição e URL do cartão do agente, e depois seleciona Adicionar ao agente.

  13. Confirme que o agente ligado aparece em Agentes conectados no painel de componentes.

Se voltares atrás e mudares as definições de autenticação no passo Connect to an A2A agent, o Copilot Studio descarta o conector que foi construído a partir das definições anteriores. Tens de registar um novo URL de redirecionamento e escolher uma ligação novamente.

Note

És responsável por rever e testar cuidadosamente os agentes ligados no contexto dos teus casos de uso específicos, bem como por tomar todas as decisões e personalizações apropriadas. Quando se liga a agentes fora do Copilot Studio, é responsável pela utilização desses agentes. As considerações incluem garantir:

  • Os fluxos de dados, o tratamento e a partilha de dados entre agentes são adequados ao seu caso de uso e cumprem os requisitos e leis relevantes.
  • Os agentes cumprem normas adequadas em matéria de qualidade, fiabilidade, segurança e confiança.
  • São previstas permissões, limites e aprovações apropriadas, se for prudente para o seu caso de uso.
  • Estão implementadas a observabilidade, identidade e rastreabilidade adequadas, bem como funções de supervisão humana.

Configurar autenticação de chave de API

Ao selecionar a chave API, escolha para onde o Copilot Studio envia a chave selecionando um tipo de Parâmetro:

  • Cabeçalho: a chave é enviada como cabeçalho do pedido. Em Nome do cabeçalho, introduza o nome do cabeçalho que o agente remoto espera, como x-api-key.
  • Query string: a chave é enviada como um parâmetro de query string. No rótulo Parâmetro, introduza o nome do parâmetro da string de consulta que o agente remoto espera.

Introduz o valor da chave da API quando cria a ligação, não neste passo. Assim, a chave fica armazenada com a ligação e não é visível na configuração do agente.

Configurar a autenticação OAuth 2.0

Ao selecionar OAuth 2.0, escolha um tipo de Configuração:

  • Dinâmica: O Copilot Studio regista um cliente junto do fornecedor de identidade do agente remoto por si. Introduza o URL de autorização e o URL do Token.

  • Manual: usa um registo de aplicação que já criaste junto do fornecedor de identidade do agente remoto. Insira os seguintes valores:

    • ID do cliente: o ID de cliente do registo da sua aplicação.
    • Segredo do cliente: o segredo do cliente do registo de aplicações.
    • URL de autorização: o endpoint de autorização do fornecedor de identidade.
    • URL do token: o endpoint de token do fornecedor de identidade.
    • URL de atualização do token: o endpoint usado para atualizar tokens de acesso.
    • Escopos (opcional): os escopos a solicitar, separados por espaços.

Utilize Dinâmica quando o provedor de identidade do agente remoto suportar o registo dinâmico de cliente. Utilize o Manual quando precisar de controlar o registo da aplicação, por exemplo, quando o seu fornecedor de identidade exigir URIs de redirecionamento pré-registados ou consentimento.

Qualquer um dos tipos de configuração exige que registe uma URL de redirecionamento junto do seu fornecedor de identidade. Depois de selecionar Próximo, o Copilot Studio cria o conector e mostra o URL de redirecionamento gerado no passo Adicionar URL de redirecionamento.

Encontrar o URL de redirecionamento mais tarde

Se fechares o assistente ou perderes a URL de redirecionamento, podes vê-la novamente a qualquer momento:

  1. No separador Build, selecione o agente A2A nos Agentes Conectados no painel de componentes.

  2. No diálogo Editar agente A2A , copie o valor no campo URL de Redirecionamento .

O campo URL de Redirecionamento aparece apenas para agentes A2A que utilizam OAuth 2.0.

Como o orquestrador encaminha para o agente A2A

Depois de adicionares o agente A2A, o runtime de orquestração determina automaticamente quando delegar nesse agente. A decisão de encaminhamento baseia-se em:

  • Nome e descrição do agente ligado
  • A mensagem do utilizador e o contexto da conversa
  • Instruções do agente principal

Tip

Escreva uma descrição clara e específica para o agente A2A para que o orquestrador possa determinar com precisão quando encaminhar pedidos para ele. Evite descrições sobrepostas entre agentes ligados.

Delegação de teste

Depois de adicionar o agente A2A:

  1. Na barra de navegação do agente, selecione o separador Pré-visualização.

  2. Envie uma mensagem que corresponda ao domínio do agente A2A.

  3. Verifique se a resposta vem do agente da A2A e é adequada.

  4. Envia uma mensagem fora do domínio do agente A2A para confirmar que o teu agente principal trata disso.

Se precisares de mudar o nome ou a descrição mais tarde, edita o agente ligado a partir do painel de componentes. Veja Gerir agentes ligados de um agente.

Resolver problemas de ligação

Problema O que deve verificar
Autorizar a ligação falha com um erro de URI de redirecionamento A URL de redirecionamento que o Copilot Studio gerou não está registada com o seu fornecedor de identidade. Copie o URL do diálogo Editar agente A2A , adicione-o ao registo da sua aplicação e depois autorize novamente a ligação.
O campo URL de Redirecionar mantém-se vazio no assistente O conector ainda está a ser criado. Se o passo mostrar um erro em vez disso, selecione Retry.
O nome e a descrição não se preenchem a partir do cartão do agente Verifica se o URL do cartão do agente está correto e se o Copilot Studio consegue aceder ao cartão. Introduza o nome e a descrição manualmente se o cartão não estiver disponível.
A ligação que criaste deixou de funcionar depois de editares o wizard Alterar as definições de autenticação descarta o conector construído a partir das definições anteriores. Regista a nova URL de redirecionamento e escolhe novamente uma conexão.
  • Última atualização a