Publicar agentes para Microsoft 365 Copilot e Microsoft Teams no portal do Foundry

Depois de criar e testar um agente, você geralmente deseja compartilhá-lo com outras pessoas nos ambientes em que elas já trabalham. Quando você publica um agente do Microsoft Foundry no Microsoft 365 Copilot e no Teams, você e outras pessoas podem interagir e descobrir seu agente por meio do Microsoft 365 Copilot e da interface do usuário do Teams. Você publica o ponto de extremidade estável do agente, para que os usuários finais sempre interajam com um agente consistente enquanto você distribui perfeitamente novas versões de agente que recebem tráfego por meio do ponto de extremidade.

Este artigo explica como publicar agentes no portal do Foundry.

Aviso

Quando você publica agentes no Microsoft 365 e no Teams, esses serviços processam e armazenam determinados dados associados à publicação e ao uso do agente. Esses dados estão sujeitos aos termos, compromissos de conformidade, compromissos de residência de dados e práticas de tratamento de dados aplicáveis ao Microsoft 365 e ao Teams.

Esses dados podem incluir dados necessários para publicar o agente, como o nome, o ícone e a descrição do agente. Ele também inclui dados contidos em respostas fornecidas pelo agente quando os usuários em sua organização enviam consultas ao agente do Microsoft 365 e do Teams.

Antes de publicar um agente no Microsoft 365 e no Teams, avalie se os fluxos de dados resultantes e o processamento são consistentes com os requisitos de conformidade, residência de dados e governança da sua organização.

Nota

Não há suporte para publicação no portal do Foundry para projetos que desabilitem o acesso à rede pública. Para publicar esses agentes, use a API REST e habilite a rota do Protocolo de Atividade pública filtrada por IP de origem com enable_m365_public_endpoint. As solicitações devem se originar do Azure Serviço de Bot ou dos intervalos de origem do Microsoft 365 e ainda assim atender aos requisitos de autorização configurados. Para obter mais informações, consulte Publicar agentes para Microsoft 365 Copilot e Microsoft Teams usando a API REST.

Pré-requisitos

• Acesso ao portal Microsoft Foundry.

• Um projeto do Foundry com uma versão do agente que você testou e deseja publicar.

• As seguintes atribuições de função:

  • Permissão para criar um recurso de Azure Serviço de Bot (Microsoft.BotService/botServices/write) e configurar seus canais (Microsoft.BotService/botServices/channels/write) no grupo de recursos em que você publica. A Função de Colaborador do Azure Serviço de Bot concede exatamente estas permissões. As funções colaborador ou proprietário mais amplas também funcionam. As funções do Foundry não concedem essas permissões. Para obter detalhes, consulte Azure Serviço de Bot configuração.

  • Função Usuário do Foundry no escopo de projeto do Foundry para criar, gerenciar e publicar agentes.

    Importante

    As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

  • Para obter detalhes, consulte o controle de acesso baseado em função no portal do Foundry.

• Teste seu agente minuciosamente no portal do Foundry antes da publicação. Confirme se ele responde corretamente e todas as ferramentas funcionam conforme o esperado.

• Selecione a versão do agente ativo com a qual você deseja que os consumidores interajam no Microsoft 365 e no Teams.

• Verifique se os provedores de recursos do Azure necessários estão registrados em sua assinatura. O processo de publicação cria um recurso do Azure Serviço de Bot, que requer o provedor Microsoft.BotService.

  Se você usar a CLI do Azure, poderá registrar o provedor com:

  az provider register --namespace Microsoft.BotService
  

Selecionar uma versão do agente ativo

A versão ativa é a versão que o endpoint estável do seu agente disponibiliza aos consumidores, portanto confirme-a antes de publicar. Para obter mais informações sobre as versões do agente e outras configurações, consulte Configure o endpoint e as configurações do agente.

Portal da Foundry

Defina a versão ativa a partir de um de dois pontos de entrada.

Na guia Detalhes

1. Abra o agente e selecione a guia Detalhes .
2. Na configuração do Agente, ao lado da versão Ativa, selecione Editar.
3. Selecione Sempre usar a versão mais recente ou selecione uma versão específica.

No botão Publicar

1. No portal do Microsoft Foundry, selecione Publicar.
2. Ao lado da versão ativa, selecione a seta.
3. Selecione Sempre usar a versão mais recente ou selecione uma versão específica.

REST API

Para direcionar o tráfego para uma versão específica, atualize o version_selector do agente. Defina agent_version para a versão que você deseja servir.

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: ******
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "version_selector": {
      "version_selection_rules": [
        {
          "type": "FixedRatio",
          "agent_version": "2",
          "traffic_percentage": 100
        }
      ]
    }
  }
}

O que acontece quando você publica?

Quando você publica um agente, o Foundry executa as seguintes etapas:

• Valida as propriedades enviadas, como o nome de exibição, a descrição e a versão.
• Compila um manifesto de aplicativo do Teams em um pacote .zip. Para obter mais informações, consulte o esquema de manifesto do aplicativo para Microsoft Teams.
• Envia o manifesto para os catálogos de agentes do Microsoft 365 Copilot e do Teams em seu nome.
• Habilita o activity protocolo, que o agente precisa para trocar mensagens com o Microsoft 365 e o Teams.
• Habilita um esquema de autorização, seja BotServiceRbac ou BotServiceTenant, que controla quem pode chamar o agente, com base no escopo que você selecionar.

Quem pode ver e chamar o agente

O escopo que você selecionar controla a visibilidade — quem pode descobrir o agente nas lojas do Microsoft 365 Copilot e do Teams. A Foundry define o esquema de autorização correspondente, que controla quem pode invocar o agente:

• Apenas você (portal do Foundry) ou publishScope definido como Shared (API REST): habilita BotServiceRbac e não requer aprovação de administrador. O agente aparece nas lojas somente para você. Se você adicioná-lo a um chat do Teams, os participantes que tiverem as permissões necessárias do Foundry no projeto poderão usá-lo.
• Pessoas na sua organização (portal Foundry) ou publishScope definido como Tenant (API REST): habilita BotServiceTenant e exige aprovação de um administrador no centro de administração do Microsoft 365. Após a aprovação, o agente aparecerá para todos no seu locatário em Criado pela sua organização, e qualquer pessoa no locatário poderá descobri-lo e usá-lo.

Publicar no Microsoft 365 e no Teams

Publicar no portal invoca a API de publicação do Microsoft 365 do Foundry e cria o pacote de aplicativo do Teams para você. Para publicar usando a API REST, por exemplo, para automatizar a publicação ou publicar de um projeto que desabilita o acesso à rede pública, consulte Publicar agentes para Microsoft 365 Copilot e Microsoft Teams usando a API REST. Esse artigo também mostra como habilitar a rota do Protocolo de Atividade pública filtrada por IP de origem para um agente de rede privada.

Você pode abrir a caixa de diálogo de publicação na guia Detalhes (na seção Canais, selecione Teams & Microsoft 365 Copilot) ou pelo botão Publicar. Estas etapas usam o botão Publicar .

1. No portal do Microsoft Foundry, selecione Publicar e selecione Teams e Microsoft 365 Copilot.

   Resultado esperado: a caixa de diálogo Publicar no Teams e no Microsoft 365 é aberta.

2. Um recurso do Serviço de Bot do Azure é criado automaticamente ou exibido como somente leitura, caso já exista.

3. Conclua os metadados necessários:

   Campo	Descrição
   Nome	Nome de exibição do seu agente (aparece na loja de agentes)
   Versão de publicação	Número da versão de três partes (major.minor.patch)
   Descrição curta	Descrição de uma frase do que seu agente faz
   Descrição	Descrição mais longa das responsabilidades do agente e das ações que ele pode tomar
   Desenvolvedor	Seu nome ou nome da organização (em Author)

   Para adicionar metadados opcionais, expanda Mais e conclua os seguintes campos:

   Campo	Descrição
   Site do desenvolvedor	URL para seu site (HTTPS necessário)
   Termos de uso	URL para seus termos de uso (HTTPS necessário)
   Política de privacidade	URL para sua política de privacidade (HTTPS necessário)

   Aviso

   Não inclua segredos, chaves de API ou informações confidenciais em campos de metadados. Esses campos são visíveis para os usuários.

4. Selecione Avançar: Opções de publicação.

5. Escolha como publicar. Você pode publicar seu agente diretamente do Foundry ou baixar e personalizar o manifesto do agente e, em seguida, carregá-lo manualmente no Teams.

Publicação direta

1. Nas opções Publicar, selecione a guia Publicação Direta .

   Resultado esperado: a seção Escolher quem pode usar esse agente será exibida.

2. Em Escolher quem pode usar esse agente, selecione um escopo:

   Opção	Comportamento	Aprovação do administrador	Melhor para
   Só você	Disponível imediatamente. O agente aparece em Seus agentes na loja de agentes. Compartilhe-o com outras pessoas enviando o link do agente.	Não é necessário	Testes pessoais, equipes pequenas, pilotos
   Pessoas em sua organização	O agente é enviado para aprovação do administrador. O administrador do Microsoft 365 analisa a solicitação e atribui acesso. Depois de aprovado, o agente aparece em Criado pela sua organização para todos os usuários do locatário.	Necessário	Distribuição em toda a organização, implantações de produção

   Apenas você:

   • Disponível imediatamente após a publicação — nenhuma aprovação de administrador é necessária.
   • Somente você vê o agente inicialmente em Seus agentes na loja de agentes.
   • Compartilhe com usuários específicos enviando o link do agente.

   Pessoas em sua organização:

   • Após a publicação, um administrador do Microsoft 365 deve examinar e aprovar a solicitação no Centro de administração do Microsoft 365.

   • Após a aprovação, o agente aparece em Criado pela sua organização na loja de agentes para todos os usuários do locatário.

   • As políticas do aplicativo em seu locatário controlam quais usuários podem acessar o agente.

   • Para verificar o status de aprovação, acesse o Centro de administração do Microsoft 365 e procure seu agente em Solicitações.

     

3. Selecione Publicar.

   Resultado esperado: uma caixa de diálogo Publicação bem-sucedida confirma que o agente foi publicado com sucesso.

Baixar e personalizar

Se você quiser personalizar o manifesto do agente antes de distribuí-lo:

1. Nas opções Publicar, selecione a guia Baixar & personalizar .

   Resultado esperado: a guia exibe instruções para depois de baixar e um botão Baixar ZIP .

2. Selecione Baixar ZIP.

   Resultado esperado: um .zip arquivo que contém o manifesto do agente é baixado no computador local.

3. Personalize o manifesto no pacote baixado conforme necessário.

4. Em Microsoft Teams, carregue o pacote que você baixou.

   1. Vá para Aplicativos>Gerenciar seus aplicativos>Carregar um aplicativo.
   2. Selecione Carregar um aplicativo personalizado ou Enviar um aplicativo para sua organização e escolha o arquivo baixado .zip .

Atualizar um agente publicado no M365/Teams

Atualizar a versão do agente ativo

Para implementar uma nova versão do agente, atualize o seletor de versão do agente no portal do Foundry. A URL do ponto de extremidade estável permanece a mesma, não é necessário republicar no M365/Teams.

Atualizar metadados do usuário final no M365/Teams

Para atualizar os metadados visíveis no Teams e no M365 (nome de exibição, descrições, URLs), na lista suspensa Publicar , selecione o agente de atualização Teams e as propriedades de exibição do Microsoft 365 Copilot. Os campos atualizados substituem os valores existentes. Campos inalterados são levados adiante. A versão é incrementada automaticamente se você não incrementá-la manualmente.

Limitações

Para limitações de publicação de agente, incluindo requisitos quando seu projeto desabilita o acesso à rede pública, consulte Limitações.

Solucionar problemas de publicação

Use a tabela a seguir para resolver erros que ocorrem durante a publicação no portal. Para obter uma solução de problemas mais abrangente, incluindo como encontrar um agente publicado no repositório e resolver erros ao conversar com ele, consulte Solução de problemas.

Sintoma	Causa	Resolução
Erro ao publicar o agente	Metadados ou versão inválidos	Verifique se o agente tem uma identidade exclusiva (agent.identity não é nula). Confirme se o nome do desenvolvedor tem 32 caracteres ou menos.
Falha na criação do Serviço de Bot do Azure	Permissões ausentes ou provedor não registrado	Confirme se você tem permissão para criar recursos. Registre-se Microsoft.BotService , se necessário.
O campo Azure bot services mostra um erro de 403 AuthorizationFailed para Microsoft.BotService/botServices/write	Sua identidade não tem permissão para criar ou atualizar o recurso Azure Serviço de Bot no grupo de recursos de destino	Atribua a função de colaborador Azure Serviço de Bot (ou a função colaborador ou proprietário mais ampla) no grupo de recursos que contém o bot service e atualize suas credenciais e reabra o fluxo de publicação.

Se o portal mostrar Este agente usa um formato antigo que não pode mais ser publicado no Teams e no Microsoft 365 Copilot. Atualize para o novo formato para poder publicar., o agente usa o formato antigo de aplicativo de agente, que o fluxo de publicação de disponibilidade geral não oferece suporte a novas publicações. Atualize o agente para o novo formato e, em seguida, publique. Os agentes existentes no formato mais antigo continuam funcionando e ainda podem ser atualizados. Consulte Migrar de aplicativos de agente para o novo modelo de agente.

Faqs

Se selecionar o escopo da Organização, onde eu aprovo o agente?

Aprove o agente no centro de administração do Microsoft 365. Após a aprovação, o agente aparece na seção Built by your org da loja de agentes.

Se eu publicar meu agente no Escopo Individual (anteriormente chamado de Escopo Compartilhado), como compartilhá-lo com outras pessoas na minha organização?

O agente aparece em Seus agentes no repositório de agentes para Microsoft 365 Copilot. Compartilhe-o enviando o link do agente para usuários selecionados em sua organização.

O que acontece quando crio uma nova versão do agente se meu agente estiver publicado no M365?

Se o seletor de versão estiver definido como Sempre usar o mais recente (o padrão), a nova versão servirá automaticamente no M365 e no Teams. Se você fixar em uma versão específica, deverá atualizar o seletor de versão para atender à nova versão.

Conteúdo relacionado

• Definir o ponto de extremidade e as configurações do agente
• Publicar agentes para Microsoft 365 Copilot e Microsoft Teams usando a API REST
• Controle de acesso baseado em função no portal do Foundry
• Migrar de Aplicações de Agente para o novo modelo de agente