Criar instâncias de agente

Depois de publicar seu agente e disponibilizá-lo no centro de administração da Microsoft, você pode criar instâncias de agentes e usuários de agentes. Essas instâncias e usuários usam o modelo do agente e o código do agente que você criou.

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

1. Configurar agente no portal de desenvolvedores do Teams
2. Criar instância de agente
3. Teste seu agente implantado

Se você tiver dificuldades, consulte a seção de Solução de Problemas .

Pré-requisitos

• Blueprint do agente configurado corretamente conforme a etapa do Blueprint do agente de configuração.
• Aplicativo do agente publicado corretamente conforme Publicar agente no centro de administração da Microsoft.

1. Configurar agente no portal de desenvolvedores do Teams

Após a publicação, configure o blueprint do agente no Portal do Desenvolvedor do Teams para conectar seu agente à infraestrutura de mensagens Microsoft 365. Sem essa configuração, seu agente não recebe mensagens do Teams, email ou outros serviços de Microsoft 365.

1. Obtenha seu ID de projeto

   Execute o comando a365 config display -g para exibir sua configuração:

   a365 config display -g
   

   Copie o agentBlueprintId valor da saída.

2. Navegar até o Portal de Desenvolvedores

   Abra seu navegador e vá para a página de configuração:

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

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

   Observação

   Se você não tiver acesso ao Portal do Desenvolvedor, entre em contato com o administrador do seu inquilino para conceder acesso ou completar essa configuração em seu nome.

3. Configurar o agente

   No Portal do Desenvolvedor:

   1. Defina o tipo de agente para baseado em bots
   2. Defina o ID do Bot para seu agentBlueprintId valor
   3. Selecione Salvar

   

Você precisa dessa configuração antes de poder criar instâncias de agente no Teams.

Saiba mais sobre Modelos de Identidade de Agente e Configuração do Portal para Desenvolvedores.

2. Criar instância de agente

Agora você pode solicitar uma instância do seu blueprint de agente pelo Teams. Saiba mais sobre como descobrir, criar e integrar um agente.

Quando você solicita uma instância de agente, o Teams envia a solicitação para o administrador do seu tenant para aprovação. Administradores podem revisar e aprovar solicitações a partir da página de Agentes Solicitados do centro de administração da Microsoft .

Depois que o administrador aprova sua solicitação, o Teams cria sua instância de agente e a disponibiliza no Teams.

3. Teste seu agente destacado

Depois de criar uma instância de agente, teste-a em Microsoft 365 para garantir que ela funcione corretamente na produção.

Após a implantação e com as notificações do agente habilitadas no SDK do Agent 365, seu agente se integra aos serviços de Microsoft 365. Ele funciona com o Teams para chats, canais e reuniões; com email e calendário para envio, recebimento e agendamento; e com SharePoint e OneDrive para acesso a documentos e compartilhamento de arquivos. Também suporta recursos de colaboração, como presença organizacional, tarefas do Planner e comentários de documentos.

Visualizar agente implantado no centro administrativo

Depois que você publica seu agente, ele aparece no centro de administração da Microsoft para contratação. Pode levar algum tempo para se propagar.

Vá para o centro de administração Microsoft 365 - Agentes para:

• Veja seu agente publicado
• Gerenciar configurações do agente
• Monitorizar a utilização do agente
• Configurar permissões

Agente de teste no Teams

Depois de implantar, publicar e configurar o blueprint do agente e criar um usuário do agente, teste o usuário do agente diretamente no Microsoft Teams:

Comece a testar

1. Procure pelo seu novo usuário agente no Teams

   Observação

   O processo de criação do usuário agente é assíncrono e pode levar de alguns minutos a algumas horas para o usuário agente se tornar pesquisável após a criação.

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

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

Exemplo de mensagem de teste

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

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 a solicitação e envia o e-mail sem precisar de mais confirmação.

Lista de verificação

Depois de criar sua instância de agente, verifique se está funcionando corretamente no Teams.

✅ Configuração do portal do desenvolvedor salva
✅ Agente aparece na busca de aplicativos do Teams
✅ Você pode criar um instance agent para Teams
✅ Instância de agente criada
✅ Usuário agente aparece na organização
✅ Agente responde às mensagens
✅ O agente pode realizar ações
✅ Logs de aplicação não mostram erros
✅ Observabilidade no centro de administração

Se sua instância de agente não estiver funcionando como esperado, veja a seção Solução de Problemas para soluções detalhadas para problemas comuns.

Verifique se a configuração do portal do desenvolvedor está salva

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

✅ Tipo de agente mostra: Baseado em bot
✅ O ID do bot corresponde ao seu agentBlueprintId
✅Mostra a mensagem Salvo com sucesso

Verificar que o agente aparece no Teams

1. > Abrir Aplicativos do Teams

2. Procure pelo nome do seu agente

   ✅ Agente aparece nos resultados de busca
   ✅ Mostra o ícone e a descrição do seu agente

Verifique se você pode criar um instance agent para Teams

Selecione seu agente nos aplicativos do Teams

✅ O botão Solicitar Instância/Criar Instância está ativado
✅ É possível solicitar uma instância sem erros

Verificar instância do agente criada

Após selecionar a Instância de Solicitação:

✅ Solicitação enviada com sucesso para o administrador

Verifique se o usuário do agente aparece na organização

No centro de administração do Microsoft 365:

1. Acesse: https://admin.cloud.microsoft/#/agents/all
2. Navegar até a aba Solicitações de Todos os Agentes

✅ Sua solicitação de instância de agente está listada no estado de pendente de revisão
✅ O administrador pode aprovar a instância do agente para uso
✅ O usuário pode então criar uma instância no Teams e dar um nome a ela.

Verificar que o agente responde às mensagens

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

✅ Agente mostra indicador de digitação
✅ O agente responde em poucos segundos
✅ A resposta é coerente e relevante

Verifique se o agente pode realizar ações

Se as ferramentas estiverem configuradas, teste a funcionalidade das ferramentas. Por exemplo, se você adicionou o servidor MCP do Mail, envie um e-mail de teste para si mesmo.

O agente deve:

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

Você deve verificar se o e-mail chegou à sua caixa de entrada.

Verificar a funcionalidade

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

Funcionalidade básica:

✅ O agente responde a cumprimentos simples.
✅ O agente lida com conversas em várias etapas.
✅ O agente fornece respostas relevantes.

Funcionalidade da ferramenta:

Depende da configuração do servidor MCP

✅ Pode enviar e-mails.
✅ Dá para acessar o calendário.
✅ Pode pesquisar documentos.
✅ Pode realizar ações configuradas.

Tratamento de erros:

✅ Trata pedidos inválidos com elegância.
✅ Fornece mensagens de erro úteis.
✅ Não trava com entrada inesperada.

Desempenho:

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

Verificar logs de aplicação

Para ver o que seu agente está fazendo, verifique os logs de aplicação usando o comando log tail do az-webapp .

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

O que observar nos registros:

✅ Solicitações recebidas do Teams
✅ Autenticação bem-sucedida
✅ Chamadas de ferramenta sendo executadas
✅ Respostas sendo enviadas
❌ Mensagens de erro ou exceções

Verificar a observabilidade no centro administrativo

Depois que seu agente começar a correr:

1. Acesse: https://admin.cloud.microsoft/#/agents/all

2. Selecione seu agente e abra a aba Atividade .

   Você deve ver:

   ✅ Sessões em exibição.
   ✅ Cada sessão mostra gatilhos e ações.
   ✅ Chamadas de ferramentas são registradas com carimbos de data.

Próximas etapas

Seu agente agora está ativo na nuvem e pronto para trabalhar ao lado de sua equipe em Microsoft 365. O que começou como código local agora é um assistente descoberto e pronto para uso corporativo, onde os usuários podem criar instâncias de agentes em toda a sua organização.

O ciclo de desenvolvimento do seu agente está completo, mas seu impacto está apenas começando. Muito do que você criou no ciclo de vida do desenvolvedor do agente 365 é open source e recebe contribuições da comunidade. Levantar bugs, solicitações de recursos e pull requests:

• Amostras de Agente 365: Tem alguns exemplos de agentes interessantes e divertidos? Compartilhe seu código de agente com a comunidade de open source aqui!
• Node.js SDK: O SDK Agente 365 em Node.js
• Python SDK: O SDK do Agente 365 no Python
• .NET SDK: O SDK do Agente 365 em C# (.NET)
• Agent 365 DevTools CLI: Uma CLI para ajudar você durante todo o ciclo de desenvolvimento do Agent 365

Resolução de problemas

Esta seção contém problemas comuns ao criar e testar instâncias de agentes.

agente não aparece no Microsoft Teams

Sintoma: O agente aparece no centro de administração, mas não consigo encontrá-lo nos aplicativos do Teams.

Causa raiz: Falta a configuração do Portal para Desenvolvedores.

Solution:

1. Obtenha seu ID de projeto:

   a365 config display -g
   # Copy the agentBlueprintId value
   

2. Configure no Portal do Desenvolvedor:

   1. Acesse: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
   2. Defina o tipo de agente para baseado em bots
   3. Defina o ID do bot para seu agentBlueprintId
   4. Selecione Salvar

3. Espere de 5 a 10 minutos para a propagação.

Verificação:

• Aplicativos do Open Teams >> Procure pelo seu agente
• Agente aparece e está disponível para adicionar

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

Sintoma: O agente aparece no Teams, mas não pode adicionar ou criar instâncias; O botão Solicitar Instância não funciona.

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

Solução: Entre em contato com o administrador do seu tenant para verificar se o Microsoft Agent 365 Frontier está ativado para o tenant

Saiba mais sobre a Frontier

Verificação:

Os recursos do Frontier aparecem no Microsoft 365 Copilot e nos aplicativos do Microsoft 365 assim que as configurações de licença e de administrador permitirem.

Agente não está respondendo às mensagens

Sintoma: Criei a instância do agente, mas não responde às mensagens; Sem logs na aplicação.

Causa raiz: Múltiplas causas possíveis - problemas no endpoint de mensagens, problemas de autenticação ou erros de configuração.

Solução de problemas básicos

1. Verifique se o aplicativo web está rodando:

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

2. Verifique o endpoint de mensagens:

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

3. Teste o endpoint diretamente:

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

4. Verifique os registros de inscriçã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. Verifique a autenticação:

   • Verifique se os tokens estão vencidos. Renove-os se necessário.
   • Verifique credenciais na configuração do Web App.

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

   • Verifique se os servidores MCP estão configurados.
   • Permissões de verificação são concedidas.

3. Teste localmente:

   • Execute o agente localmente com a mesma configuração.
   • Teste com o Agents Playground.
   • Funciona localmente, mas não no problema de implantação na nuvem >

Soluções comuns

• Endpoint de mensagens incorreto: Atualize no portal do Azure e no portal do desenvolvedor
• Web app stopped: Inicie-o usando o portal do Azure ou CLI.
• Token expirado: Atualize os tokens nas variáveis de ambiente do Web App
• Variáveis de ambiente ausentes: Verifique as Configurações do Aplicativo no portal do Azure
• Problemas com o servidor MCP: Verificar o principal do serviço e as permissões
• Erros de código: Verifique os registros de aplicações para exceções

Verificação

Envie uma mensagem para seu agente no Teams e verifique os registros de inscrição para solicitações recebidas.

Você também pode querer tentar:

• Solução de problemas ao implantar um agente na Amazon Web Services
• Solução de problemas ao implantar um agente na Google Cloud Platform

Falhas nas chamadas de ferramenta

Sintoma: O agente responde às mensagens, mas as chamadas de ferramenta falham. Você vê erro de permissão negada ou de tempo de espera.

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

Soluções

Tente as seguintes soluções quando as chamadas de ferramenta falharem:

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

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

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

• Verifique o principal do serviço

  Execute o script de configuração única se você não o executou antes:

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

• Verifique a configuração do endpoint MCP

  Certifique-se de que você está usando o endpoint MCP de produção:

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

• Verifique identidade gerenciada

  Verifique se a identidade gerenciada está ativada no seu aplicativo web:

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

Verificação

Teste chamadas de ferramentas pelo Teams e verifique os logs para ver se a execução foi bem-sucedida.

Você também pode querer tentar estes passos:

• Ferramentas de solução de problemas
• Solução de problemas do servidor de ferramentas simuladas

Falha na cessão da licença

Sintoma: Não é possível atribuir licença ao usuário agente; Erros de licença no Centro de Administração.

Causa raiz: Licenças insuficientes disponíveis, tipo de licença incorreto ou emissão de permissões.

Soluções

Tente as seguintes soluções quando a cessão de licença falhar:

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

   • Verifique Microsoft 365 centro de administração >Billing>Licenses
   • Garanta que o Microsoft Agent 365 Frontier esteja ativado para o tenant

2. Atribuir licença manualmente:

   • Vá para Microsoft 365 centro de administração >Users
   • Encontre o usuário agente
   • Atribuir a licença apropriada

3. Licenças exigidas para funcionalidade total:

   • Microsoft 365 E5 (ou equivalente)
   • Teams Enterprise
   • Microsoft 365 Copilot (para os recursos do Copilot)

Verificação

Verifique o perfil de usuário no centro de administração para ver as licenças atribuídas.