Criar instâncias de agente

Após publicar o seu agente e disponibilizá-lo no centro de administração da Microsoft, pode criar instâncias de agentes e utilizadores de agentes. Estas instâncias e utilizadores utilizam o esquema de agente e o código do agente que criou.

Este artigo divide o processo em três passos principais:

  1. Configurar o agente no portal do programador do Teams
  2. Criar instância de agente
  3. Testar o agente implementado

Se encontrar dificuldades, consulte a secção Resolução de problemas.

Pré-requisitos

1. Configurar agente no portal do programador do Teams

Depois de publicar, configure o esquema de agente no Portal do Programador do Teams para ligar o seu agente à infraestrutura de mensagens do Microsoft 365. Sem esta configuração, o seu agente não recebe mensagens do Teams, do e-mail ou de outros serviços do Microsoft 365.

  1. Obter o ID do esquema

    Abra a365.generated.config.json no seu diretório de trabalho e copie o valor agentBlueprintId.

  2. Navegar para o Portal do Programador

    Abra o browser e aceda à página de configuração:

    https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    Substitua <your-blueprint-id> pelo valor agentBlueprintId que copiou.

    Nota

    Se não tiver acesso ao Portal do Programador, contacte o administrador do seu inquilino para que lhe conceda acesso ou conclua esta configuração em seu nome.

  3. Configurar o agente

    No Portal do Programador:

    1. Defina Tipo de Agente como Baseado em API

    2. Defina o URL de notificação para o ponto final de mensagens do seu agente. Encontre o valor messagingEndpoint em a365.generated.config.json.

    3. Selecione Guardar.

    Captura de ecrã a mostrar a página de configuração do Portal do Programador com o Tipo de Agente definido como Baseado em API e o campo URL de Notificação.

Necessita desta configuração antes de poder criar instâncias de agente no Teams.

Saiba mais sobre esquemas de identidade de agente e a configuração do Portal do Programador.

2. Criar instância de agente

Agora pode pedir uma instância do seu esquema de agente no Teams. Saiba mais sobre como descobrir, criar e integrar um agente.

Quando pede uma instância de agente, o Teams envia o pedido ao administrador do seu inquilino para aprovação. Os administradores podem rever e aprovar pedidos na página centro de administração da Microsoft - Agentes Pedidos.

Depois de o administrador aprovar o seu pedido, o Teams cria a sua instância de agente e disponibiliza-a no Teams.

3. Testar o seu agente implementado

Após criar uma instância de agente, teste-a no Microsoft 365 para garantir que funciona corretamente em produção.

Após a implementação, e com as notificações de agente ativadas no SDK do Agent 365, o seu agente integra-se com os serviços do Microsoft 365. Funciona com o Teams para chats, canais e reuniões; com e-mail e calendário para envio, receção e agendamento; e com SharePoint e OneDrive para acesso a documentos e partilha de ficheiros. Também suporta funcionalidades de colaboração, como presença organizacional, tarefas do Planner e comentários de documentos.

Importante

Tal como os utilizadores comuns, os utilizadores de agentes também necessitam das licenças Microsoft 365 adequadas para aceder aos serviços. As licenças comuns incluem Microsoft 365 E5, Teams Enterprise e Microsoft 365 Copilot.

Ver o agente implementado no centro de administração

Depois de publicar o seu agente, este aparece no centro de administração da Microsoft para contratação. Pode demorar algum tempo a propagar.

Aceda ao Centro de administração do Microsoft 365 - Agentes para:

  • Ver o agente publicado
  • Gerir definições do agente
  • Monitorizar a utilização do agente
  • Configurar permissões

Testar agentes no Teams

Depois de implementar, publicar e configurar o esquema de agente e de criar um utilizador de agente, teste diretamente esse utilizador de agente no Microsoft Teams:

Iniciar testes

  1. Pesquise o seu novo utilizador de agente no Teams.

    Nota

    O processo de criação do utilizador de agente é assíncrono. Pode demorar de alguns minutos a algumas horas para que o utilizador de agente passe a estar disponível para pesquisa após ser criado.

  2. Inicie um novo chat com a instância de agente recém-criada.

  3. Envie mensagens de teste para verificar a funcionalidade do agente.

Exemplo de mensagem de teste

Se configurou o agente com Email, envie esta mensagem para testar a funcionalidade de e-mail. Atualize o valor do e-mail recipient@contoso.com do destinatário.

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

O agente processa o pedido e envia o e-mail sem necessidade de confirmação adicional.

Lista de verificação

Depois de criar a instância do agente, verifique se está a funcionar corretamente no Teams.

✅ A configuração do portal do programador foi guardada
✅ O agente aparece na pesquisa de aplicações do Teams
✅ Pode criar uma instância de agente para o Teams
✅ Instância de agente criada
✅ O utilizador de agente aparece na organização
✅ O agente responde às mensagens
✅ O agente pode realizar ações
✅ Os registos da aplicação não apresentam erros
✅ A observabilidade está a funcionar no centro de administração

Se a sua instância de agente não estiver a funcionar como esperado, consulte a secção Resolução de Problemas para obter soluções detalhadas para problemas comuns.

Verificar se a configuração do portal do programador está guardada

Navegar para: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ O Tipo de Agente mostra: Baseado em API✅O URL de Notificação corresponde ao ponto final de mensagens do seu agente ✅ Mostra a mensagem Guardado com sucesso

Verificar se o agente aparece no Teams

  1. Abra o Teams >Aplicações

  2. Pesquise o nome do seu agente

    ✅ O agente aparece nos resultados de pesquisa. ✅ Mostra o ícone e a descrição do seu agente

Verificar se consegue criar uma instância de agente no Teams

Selecione o seu agente nas aplicações Teams

✅ O botão Pedir Instância/Criar Instância está ativado ✅ É possível pedir a instância sem erros

Verificar se a instância de agente foi criada

Depois de selecionar Pedir Instância:

✅ O pedido é enviado com sucesso para o administrador

Verificar se o utilizador de agente aparece na organização

No centro de administração do Microsoft 365:

  1. Aceda a: https://admin.cloud.microsoft/#/agents/all
  2. Navegue para o separador Pedidos de Todos os Agentes

✅ O pedido de instância de agente está listado com o estado pendente de revisão ✅ O administrador pode aprovar a instância de agente para utilização ✅ O utilizador pode criar a instância a partir do Teams e atribuir-lhe um nome.

Verificar se o agente responde às mensagens

No chat do Teams com o seu agente - Envie uma mensagem de teste: Hello!

✅ O agente mostra o indicador de escrita ✅ O agente responde em poucos segundos ✅ A resposta é coerente e relevante

Verificar se o agente pode realizar ações

Se configurar ferramentas, teste a funcionalidade das mesmas. Por exemplo, se adicionar o servidor Mail MCP, envie um e-mail de teste para si.

O agente deve:

✅ Reconhecer o pedido ✅ Executar a chamada de ferramenta ✅ Confirmar a conclusão bem-sucedida

Deve verificar se o e-mail chegou à sua caixa de entrada.

Verificar a funcionalidade

A seguinte lista de verificação fornece uma abordagem sistemática de testes para o seu agente:

Funcionalidade básica:

✅ O agente responde a saudações simples. ✅ O agente processa conversações com vários passos. ✅ O agente fornece respostas relevantes.

Funcionalidade das ferramentas:

Depende da configuração do servidor MCP

✅ Pode enviar emails. ✅ Pode aceder ao calendário. ✅ Pode pesquisar documentos. ✅ Pode realizar ações configuradas.

Processamento de erros:

✅ Processa pedidos inválidos de forma adequada. ✅ Fornece mensagens de erro úteis. ✅ Não falha perante entradas inesperadas.

Desempenho:

✅ Responde em poucos segundos. ✅ Sem erros de tempo limite. ✅ Tempos de resposta consistentes.

Verificar registos de aplicação

Para ver o que o seu agente está a fazer, verifique os registos de aplicação utilizando o comando az webapp log tail.

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

O que procurar nos registos:

✅ Pedidos recebidos do Teams ✅ Autenticação bem-sucedida ✅ Chamadas de ferramentas a ser executadas ✅ Respostas enviadas ❌ Mensagens de erro ou exceções

Verificar a observabilidade no centro de administração

Depois de o seu agente começar a ser executado:

  1. Aceda a: https://admin.cloud.microsoft/#/agents/all.

  2. Selecione o seu agente e abra o separador Atividade.

    Deverá ver:

    ✅ Sessões a aparecer. ✅ Cada sessão mostra acionadores e ações. ✅ As chamadas de ferramentas são registadas com carimbos de data/hora.

Passos seguintes

O seu agente está agora live na cloud e pronto para trabalhar em conjunto com a sua equipa no Microsoft 365. O que começou como código local é agora um assistente registado, preparado para empresas, onde os utilizadores podem criar instâncias de agente em toda a sua organização.

O ciclo de vida de desenvolvimento do seu agente está concluído, mas o seu impacto está apenas a começar. Grande parte do que foi criado no ciclo de vida de desenvolvimento do Agent 365 é open source e acolhe contribuições da comunidade. Comunique erros, pedidos de funcionalidades e pedidos Pull:

Resolução de Problemas

Esta secção contém problemas comuns que surgem durante a criação e o teste de instâncias de agente.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

O agente não aparece no Teams

Sintoma: O agente aparece no centro de administração, mas não o consegue encontrar nas Aplicações do Teams.

Causa raiz: Configuração em falta no Portal do Programador.

Solução:

  1. Obtenha o seu ID de esquema a partir de a365.generated.config.json — procure o agentBlueprintId.

  2. Configure no Portal do programador:

    1. Aceda a: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    2. Defina Tipo de Agente como Baseado em API

    3. Defina o URL de notificação para o ponto final de mensagens do seu agente. Encontre o valor messagingEndpoint em a365.generated.config.json.

    4. Selecione Guardar.

  3. Aguarde entre 5 a 10 minutos para a propagação.

Verificação:

  • Abra o Teams > Aplicações > Pesquise o seu agente.
  • O agente aparece e pode ser adicionado.

Não é possível criar uma instância de agente no Teams

Sintoma: O agente aparece no Teams, mas não é possível adicionar ou criar uma instância; o botão Pedir Instância não funciona.

Causa raiz: O Microsoft Agent 365 Frontier não está ativado para o inquilino.

Solução: Contacte o administrador do seu inquilino para verificar se o Microsoft Agent 365 Frontier está ativado para o inquilino.

Saiba mais sobre o Frontier.

Verificação:

As funcionalidades do Frontier aparecem no Microsoft 365 Copilot e no Microsoft 365 Apps assim que a sua licença e as definições de administração o permitirem.

O agente não responde às mensagens

Sintoma: É criada uma instância de agente, mas esta não responde às mensagens. Não há registos na aplicação.

Causa raiz: Diversas causas possíveis - problemas no ponto final de mensagens, problemas de autenticação ou erros de configuração.

Resolução de problemas básicos

  1. Verifique se a aplicação Web está em execução:

    az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Should be: "Running"

  2. Verifique o ponto final de mensagens:

    • Deve ser: https://<your-app-root-url>/api/messages
    • Verifique-o em a365.config.json e a365.generated.config.json

  3. Teste o ponto final diretamente:

    curl https://<your-app-root-url>/api/messages
# Should not return 404

  4. Verifique os registos da aplicação:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
# Look for incoming requests and errors

Diagnóstico avançado

  1. Verificar autenticação:

    • Verifique se os tokens estão expirados. Renove-os se necessário.
    • Verifique as credenciais na configuração da aplicação Web.

  2. Verificar a configuração da ferramenta/MCP:

    • Verifique se os servidores MCP estão configurados.
    • Verifique se as permissões estão concedidas.

  3. Testar localmente:

    • Execute o agente localmente com a mesma configuração.
    • Teste com o Ambiente de Demonstração de Agentes.
    • Se funciona localmente, mas não na cloud >, é um problema de implementação

Soluções comuns

  • Ponto final de mensagens incorreto: Atualizar no portal do Azure e no Portal do Programador.
  • Aplicação Web parada: Inicie-a através da CLI ou do portal do Azure.
  • Token expirado: Atualize os tokens nas variáveis de ambiente da Aplicação Web.
  • Variáveis de ambiente em falta: Verifique as Definições da Aplicação no portal do Azure.
  • Problemas no servidor MCP: Verifique o principal de serviço e as permissões.
  • Erros de código: Verifique os registos de aplicação para identificar exceções.

Verificação

Envie uma mensagem ao seu agente no Teams e verifique os registos da aplicação para pedidos recebidos.

Também pode querer experimentar:

Falhas nas chamadas de ferramentas

Sintoma: O agente responde às mensagens, mas as chamadas de ferramentas falham. São apresentados erros de permissão negada ou de tempo limite.

Causa raiz: Permissões do servidor MCP em falta, principal de serviço não configurado, problemas de conectividade de rede ou configuração incorreta da ferramenta.

Soluções

Experimente as seguintes soluções quando as chamadas de ferramentas falharem:

  • Verificar permissões no centro de administração

    Reveja e aprove as permissões necessárias do servidor MCP:

    • Aceda a: https://admin.cloud.microsoft/#/agents/all
    • Selecione o seu agente > Permissões
    • Certifique-se de que a lista inclui e aprova os servidores MCP necessários

  • Verificar o principal de serviço

    Execute o script de configuração única caso ainda não o tenha executado:

    # Download and run:
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Verificar a configuração do ponto final MCP

    Certifique-se de que está a utilizar o ponto final MCP de produção:

    # Should be production endpoint, not mock
MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft

  • Verificar a identidade gerida

    Verifique se a identidade gerida está ativada na sua Aplicação Web.

    # Verify managed identity is enabled
az webapp identity show --name <your-app-name> --resource-group <your-resource-group>

Verificação

Teste as chamadas de ferramentas através do Teams e verifique os registos para confirmar a execução concluída com êxito.

Também pode querer experimentar estes passos:

A atribuição de licenças falha

Sintoma: Não é possível atribuir uma licença a um utilizador de agente. São apresentados erros de licenças no centro de administração.

Causa raiz: Número insuficiente de licenças disponíveis, tipo de licença incorreto ou problema de permissões.

Soluções

Experimente as seguintes soluções quando a atribuição de licenças falhar:

  1. Verificar se as licenças estão disponíveis:

    • Verifique o centro de administração do Microsoft 365 >Faturação>Licenças.
    • Certifique-se de que o Microsoft Agent 365 Frontier está ativado para o inquilino.

  2. Atribuir licença manualmente:

    • Aceda ao centro de administração do Microsoft 365 >Utilizadores.
    • Localize o utilizador de agente.
    • Atribua a licença adequada.

  3. Licenças necessárias para funcionalidade completa:

    • Microsoft 365 E5 (ou equivalente).
    • Teams Enterprise.
    • Microsoft 365 Copilot (para funcionalidades do Copilot).

Verificação

Verifique se o perfil de utilizador no centro de administração mostra as licenças atribuídas.

  • Last updated on