Adicionar um agente Foundry como agente ligado (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 Microsoft Foundry existente 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.

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 remoto através do protocolo Agent2Agent (A2A), veja Adicionar um agente A2A como agente ligado. Para ligar um agente construído com o SDK de Agentes do Microsoft 365, consulte Adicionar um agente SDK de Agentes do Microsoft 365 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 Foundry existente criado num projeto no portal Microsoft Foundry, com o protocolo Activity ativado e o ID do agente disponível. Os agentes da Foundry não têm o protocolo Activity ativado por defeito. Consulte Ativar o protocolo de Atividade no seu agente Foundry.
  • O URL do endpoint do Azure AI Project para o projeto que aloja o agente Foundry.
  • Permissão para aceder ao projeto Foundry. A conexão autentica-se com as credenciais de início de sessão do seu utilizador do Microsoft Entra ID.

Note

Só pode estabelecer ligação a agentes criados no portal atual do Microsoft Foundry. Ligar a um agente criado no portal anterior devolve um 404 - Version not found erro.

Adicione um agente da Foundry

  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 Foundry.

  6. No passo Connect to Azure AI Foundry, escolha a ligação que este agente usa para aceder à Microsoft Foundry:

    • Selecione uma conexão existente da lista Conexão.
    • Se não houver conexão disponível, selecione Criar nova conexão e continue para o passo seguinte.

  7. Se estiver a criar uma nova ligação, introduza os detalhes da ligação e depois selecione Criar:

    • Nome de exibição (opcional): um nome que ajuda a identificar esta ligação mais tarde.
    • Tipo de Autenticação: Login de Utilizador do Microsoft Entra ID. Este valor é definido para si.
    • Azure AI Project Endpoint: a URL do endpoint do project Foundry que hospeda o agente.

  8. De volta ao passo Connect to Azure AI Foundry, confirme que a sua ligação está selecionada e depois selecione Próximo.

  9. No passo Rever e adicionar, introduza os dados do agente Foundry ao qual pretende estabelecer ligação e depois selecione Adicionar ao agente:

    • Nome: o nome mostrado ao agente autor.
    • Descrição: uma descrição clara de quando este agente da Foundry deve ser utilizado. 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. Para obter mais informações, consulte escrever metadados eficazes.
    • ID do agente: o ID do agente da Foundry com quem quer ligar-se.

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

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.

Ative o protocolo de Atividade no seu agente Foundry

O Copilot Studio comunica com um agente Foundry ligado através do protocolo Activity. Os agentes da Foundry não têm este protocolo ativado por defeito, por isso deve ativá-lo antes de o seu agente principal poder trocar mensagens com o agente da Foundry. Se o protocolo de Atividade não estiver ativado, ainda podes adicionar a ligação, mas a chamada ao agente Foundry falha.

Pode ativar o protocolo Activity de qualquer uma das seguintes formas:

  • Publique o agente Foundry para o Microsoft 365 ou para o Microsoft Teams. Quando publica um agente de prompt para o Microsoft 365 ou Teams, o protocolo Activity e o esquema de autorização necessário BotServiceRbac são ativados automaticamente. Escolha esta opção se já planeia publicar o agente nesses canais.

  • Ative-o manualmente com uma chamada REST API. Se não publicares o agente no Microsoft 365 ou Teams, chama a API REST do Foundry Agents - Update agent para adicionar o activity protocolo e o BotServiceRbac esquema de autorização ao agente.

Para mais informações sobre como configurar e partilhar o seu agente Foundry, consulte Configurar e partilhar o seu agente Microsoft Foundry.

Ativar o protocolo Activity com uma chamada à API REST

Chame a API REST Agents - Update agent da Foundry. Substitua {{endpoint}}, {{agent_name}}, e {{token}} pelo endpoint, nome do agente e token de acesso para o seu projeto Foundry.

Importante

Mantenha responses e Entra nas listas. Removê-los impede conversar com o agente pelo portal da Foundry ou pelo SDK.

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json
Foundry-Features: AgentEndpoints=V1Preview

{
    "agent_endpoint": {
        "protocols": [
            "responses",
            "activity"
        ],
        "authorization_schemes": [
            {
                "type": "Entra",
                "isolation_key_source": {
                    "kind": "Entra"
                }
            },
            {
                "type": "BotServiceRbac"
            }
        ]
    }
}

Como o orquestrador encaminha para o agente da Foundry

Depois de adicionares o agente Foundry, o runtime de orquestração determina automaticamente quando lhe delegar. 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 Foundry 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 da Foundry:

  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 da Foundry.

  3. Verifique se a resposta vem do agente da Foundry e se é apropriada.

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

Se precisares de alterar o ID do Agente ou a descrição mais tarde, edita o agente ligado a partir do painel de componentes. Veja Gerir agentes ligados no Agent.

  • Última atualização a