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

Depois de criar e testar um agente, muitas vezes quer partilhá-lo com outras pessoas nos ambientes onde já trabalham. Quando publica um agente Microsoft Foundry para o Microsoft 365 Copilot e Teams, você e outros podem interagir e descobrir o seu agente através do Microsoft 365 Copilot e da interface do Teams. Publicas o endpoint estável do agente, para que os utilizadores finais interajam sempre com um agente consistente enquanto implementas de forma fluida novas versões de agentes que recebem tráfego através do endpoint.

Este artigo explica como publicar agentes a partir do portal Foundry.

Pré-requisitos

• Acesso ao portal Microsoft Foundry.

• Um projeto Foundry com uma versão agente que testaste e queres publicar.

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

  • Permissão para criar um recurso Azure Bot Service (Microsoft.BotService/botServices/write) e configurar os seus canais (Microsoft.BotService/botServices/channels/write) no grupo de recursos onde publica. A Função de Colaborador do Azure Bot Service concede exatamente estas permissões. Os papéis mais amplos de Contribuinte ou Proprietário também funcionam. As funções do Foundry não concedem estas permissões. Para mais detalhes, veja Azure Bot Service configuração.

  • O papel de Utilizador Foundry no âmbito do projeto Foundry é criar, gerir e publicar agentes.

    Importante

    As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • Para mais detalhes, consulte Controlo de acesso baseado em funções no portal Foundry.

• Teste o seu agente cuidadosamente no portal da Foundry antes de publicar. Confirma se responde corretamente e que todas as ferramentas funcionam como esperado.

• Seleciona a versão do agente ativo com a qual queres que os consumidores interajam no Microsoft 365 e no Teams.

• Verifica se os fornecedores de recursos Azure necessários estão registados na tua subscrição. O processo de publicação cria um recurso Azure Bot Service, que requer o fornecedor Microsoft.BotService.

  Se usar CLI do Azure, pode registar o fornecedor com:

  az provider register --namespace Microsoft.BotService
  

Selecione uma versão de agente ativo

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

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 publicas?

Quando publica um agente, a Foundry executa os seguintes passos:

• Valida as propriedades que submete, como o nome de exibição, descrição e versão.
• Compila um manifesto de uma aplicação do Teams num pacote .zip. Para mais informações, consulte Esquema de manifestos de aplicação para Microsoft Teams.
• Submete o manifesto aos catálogos de agentes do Microsoft 365 Copilot e do Teams em seu nome.
• Ativa o activity protocolo que o agente precisa para trocar mensagens com Microsoft 365 e Teams.
• Permite um esquema de autorização, seja BotServiceRbac ou BotServiceTenant, que controla quem pode ligar para o agente, com base no âmbito que selecionar.

Quem pode ver e ligar ao agente

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

• Just you (portal Foundry) ou publishScope definido para Shared (REST API): Ativa BotServiceRbac e não requer aprovação do administrador. O agente aparece nas lojas apenas para ti. Se adicionares a um chat do Teams, os participantes que têm as permissões necessárias do Foundry no projeto podem usá-lo.
• Pessoas na sua organização (portal Foundry) ou publishScope configuradas para Tenant (REST API): Ativa BotServiceTenant e requer aprovação de administrador no centro de administração do Microsoft 365. Após a aprovação, o agente aparece para todos no seu tenant em Construído pela sua organização, e qualquer pessoa no tenant pode descobri-lo e usá-lo.

Publicar para Microsoft 365 e Teams

Publicar a partir do portal chama a API de publicação do Microsoft 365 da Foundry e constrói o pacote da aplicação Teams para si. Para publicar usando a API REST em vez disso, por exemplo para automatizar a publicação ou para publicar a partir de um projeto que desative o acesso à rede pública, veja Publicar agentes para Microsoft 365 Copilot e Microsoft Teams usando a API REST. Esse artigo também mostra como ativar a rota pública do Protocolo de Atividade filtrada por IP de origem para um agente de rede privada.

Pode abrir o diálogo de publicação a partir do separador Detalhes (na secção Canais, selecione Teams & Microsoft 365 Copilot) ou a partir do botão Publicar. Estes passos utilizam o botão Publicar .

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

   Resultado esperado: Abre-se o diálogo Publish to Teams e Microsoft 365.

2. Um recurso do Azure Bot Service é criado automaticamente ou exibido como só de leitura se já existir.

3. Preencha os metadados exigidos:

   Campo	Descrição
   Nome	Nome de exibição para o seu agente (aparece na loja do agente)
   Versão de publicação	Número de versão em três partes (major.minor.patch)
   Breve descrição	Descrição de uma frase do que o seu agente faz
   Descrição	Descrição mais detalhada das responsabilidades do seu agente e das ações que pode tomar
   Programador	O seu nome ou nome da organização (em Autor)

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

   Campo	Descrição
   Site do programador	URL do seu site (HTTPS necessário)
   Termos de utilização	URL para os seus termos de uso (HTTPS necessário)
   Declaração de privacidade	URL da sua política de privacidade (HTTPS necessário)

   Aviso

   Não inclua segredos, chaves API ou informações sensíveis em nenhum campo de metadados. Estes campos são visíveis para os utilizadores.

4. Selecione Próximo: Opções de publicação.

5. Escolha como publicar. Podes publicar o teu agente diretamente do Foundry ou descarregar e personalizar o manifesto do agente, e depois instalá-lo manualmente no Teams.

Publicação direta

1. Nas opções de publicação, selecione o separador Publicação Direta.

   Resultado esperado: A secção Escolha quem pode usar este agente aparece.

2. Em Escolher quem pode usar este agente, selecione um âmbito:

   Opção	Comportamento	Aprovação administrativa	Melhor para
   Só tu	Disponível imediatamente. O agente aparece em Os teus agentes na loja de agentes. Partilhe-o com outras pessoas enviando-lhes o link do agente.	Não é obrigatório	Testes pessoais, equipas pequenas, pilotos
   Pessoas na sua organização	O agente é submetido para aprovação administrativa. O administrador do Microsoft 365 analisa o pedido e atribui acesso. Uma vez aprovado, o agente aparece em Construído pela sua organização para todos os utilizadores de inquilino.	Obrigatório	Distribuição em toda a organização, implementações em produção

   Só tu:

   • Disponível imediatamente após a publicação — sem necessidade de aprovação de administrador.
   • Só tu vês o agente inicialmente sob os teus agentes na loja de agentes.
   • Partilhe com utilizadores específicos enviando o link do agente.

   Pessoas na sua organização:

   • Após a publicação, um administrador Microsoft 365 deve rever e aprovar o pedido no centro de administração do Microsoft 365.

   • Uma vez aprovado, o agente aparece em Construído pela sua organização na loja de agentes para todos os utilizadores do locatário.

   • As políticas da aplicação no seu ambiente controlam quais os utilizadores podem aceder ao agente.

   • Para verificar o estado da aprovação, vá ao centro de administração do Microsoft 365 e procure o seu agente em Requests.

     

3. Selecionar Publicar.

   Resultado esperado: Um diálogo que confirma que a publicação foi bem-sucedida confirma que o agente foi publicado com sucesso.

Descarregue e personalize

Se quiseres personalizar o manifesto do agente antes de o distribuir:

1. Nas opções de publicação, selecione o separador Download & personalizar.

   Resultado esperado: O separador mostra instruções para depois do download e um botão de Download ZIP .

2. Selecionar Baixar ZIP.

   Resultado esperado: Um .zip ficheiro contendo o manifesto do agente é descarregado para a sua máquina local.

3. Personaliza o manifesto no pacote descarregado conforme necessário.

4. No Microsoft Teams, carregue o pacote que descarregou.

   1. Vá a Apps>Gerir as suas apps>Carregar uma app.
   2. Selecione Carregar uma aplicação personalizada ou Submeter uma aplicação para a sua organização e escolha o ficheiro descarregado .zip .

Atualizar um agente publicado no M365/Teams

Atualizar a versão do agente ativo

Para lançar uma nova versão do agente, atualize o seletor de versões do agente no portal da Foundry. O URL estável do endpoint mantém-se igual — não é necessário republicar para M365/Teams.

Atualizar metadados do utilizador final no M365/Teams

Para atualizar metadados visíveis no Teams e no M365 (nome de exibição, descrições, URLs), no menu Publicar selecione Atualizar propriedades de exibição do agente Teams e do Microsoft 365 Copilot. Os campos atualizados sobrescrevem os valores existentes. Os campos inalterados são mantidos para a frente. A versão incrementa automaticamente se não a incrementares manualmente.

Limitações

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

Resolver problemas de publicação

Use a tabela seguinte para resolver erros que ocorram enquanto publica a partir do portal. Para uma resolução de problemas mais detalhada, incluindo como encontrar um agente publicado na loja e resolver erros quando conversar com ele, consulte Resolução de Problemas.

Se o portal mostrar Este agente usa um formato antigo que já não pode ser publicado no Teams e no Microsoft 365 Copilot. Atualize para o novo formato para publicar., o agente usa o formato antigo da aplicação do agente, que o fluxo de publicação de disponibilidade geral não suporta para novas publicações. Atualiza o agente para o novo formato e depois publica. Os agentes existentes no formato mais antigo continuam a funcionar e ainda podem ser atualizados. Veja Migrar das aplicações de agente para o novo modelo de agente.

Perguntas Frequentes

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

Aprove o agente 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.

Se eu publicar o meu agente no Âmbito Individual (anteriormente chamado de Âmbito Partilhado), como é que o partilho com outros membros da minha organização?

O agente aparece em Os seus agentes na loja de agentes do Microsoft 365 Copilot. Partilhe-o enviando o link do agente a utilizadores selecionados da sua organização.

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

Se o seletor de versões estiver definido para Sempre usar o mais recente (o padrão), a nova versão serve automaticamente no M365 e no Teams. Se fixares uma versão específica, tens de atualizar o seletor de versões para servir a nova versão.

Conteúdo relacionado

• Configure o endpoint e as definições do seu agente
• Publicar agentes para Microsoft 365 Copilot e Microsoft Teams usando a API REST
• Controlo de acesso baseado em funções no portal da Foundry
• Migrar das Aplicações de Agente para o novo modelo de agente