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 de agente e usuários de agente usam o blueprint do agente e o código do agente que você criou.

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

1. Configurar o agente no portal do Desenvolvedor do Teams
2. Criar instância de agente
3. Testar seu agente implantado

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

Pré-requisitos

• Blueprint do agente configurado corretamente conforme descrito na etapa Configurar blueprint do agente.
• Aplicativo do agente publicado corretamente conforme descrito em Publicar agente para o centro de administração da Microsoft.

1. Configurar agente no portal do Desenvolvedor 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 do Microsoft 365. Sem essa configuração, seu agente não recebe mensagens do Teams, email ou outros serviços do Microsoft 365.

1. Obter sua ID do blueprint

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

2. Navegue até o Portal do Desenvolvedor

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

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

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

   Observação

   Caso não tenha acesso ao Portal do Desenvolvedor, entre em contato com o administrador do locatário para que ele conceda acesso a você ou conclua essa configuração em seu nome.

3. Configure o agente

   No Portal do Desenvolvedor:

   1. Defina Tipo de Agente como Baseado em API

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

   3. Selecione Salvar.

   

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

Saiba mais sobre blueprints de identidade de agente e configuração do Portal do Desenvolvedor.

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 locatário para aprovação. Os administradores podem revisar e aprovar solicitações na página Centro de Administração da Microsoft - Agentes Solicitados.

Após a aprovação do administrador, o Teams cria sua instância de agente e a disponibiliza no Teams.

3. Testar seu agente implantado

Depois de criar uma instância de agente, teste-a no Microsoft 365 para garantir que está funcionando corretamente em produção.

Após a implantação, e com as notificações do agente ativadas no SDK do Agent 365, seu agente se integra aos serviços do Microsoft 365. Ele funciona com o Teams para conversas, canais e reuniões, com email e calendário para enviar, receber e agendar, 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.

Ver agente implantado no centro de administração

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.

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

• Visualizar seu agente publicado
• Gerenciar as configurações do agente
• Uso de agente de monitoramento
• Configurar permissões

Testar agente no Teams

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

Iniciar teste

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

   Observação

   O processo de criação do usuário do agente é assíncrono. Pode levar de alguns minutos a algumas horas para que o usuário agente fique disponível para pesquisa depois que você o cria.

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 Email, envie esta mensagem para testar a funcionalidade do email. Atualize o endereço de email 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 email sem exigir confirmação adicional.

Lista de verificação

Após criar sua instância de agente, certifique-se de que está funcionando corretamente no Teams.

✅ Configuração do Portal do Desenvolvedor salva
✅ O agente aparece na pesquisa de aplicativos do Teams
✅ Você pode criar um agente da instância para o Teams
✅ Instância do agente criada
✅ O usuário do agente aparece na organização
✅ O agente responde às mensagens
✅ O agente pode realizar ações
✅ Os logs do aplicativo não apresentam erros
✅ Observabilidade atuando no centro de administração

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

Verifique se a configuração do portal do desenvolvedor foi salva

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

✅ O tipo de agente mostra: Baseada em API✅URL de notificação corresponde ao ponto de extremidade de mensagens do agente ✅ e exibe a mensagem Salva com êxito

Verifique se o agente aparece no Teams

1. Abra os >Aplicativos do Teams

2. Procure pelo nome do seu agente

   ✅ O agente aparece nos resultados da pesquisa ✅ Exibe o ícone e a descrição do seu agente

Verifique se você pode criar um agente da instância para o Teams

Selecione seu agente nos Aplicativos do Teams

✅ O botão Solicitar Instância/Criar Instância está habilitado ✅ Você pode solicitar instância sem erros

Verificar instância do agente criada

Após selecionar Solicitar Instância:

✅ A solicitação foi enviada com sucesso ao administrador

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

No centro de administração do Microsoft 365:

1. Vá para: https://admin.cloud.microsoft/#/agents/all
2. Navegar até a guia Todos os Agentes Solicitações

✅ Sua solicitação de instância de agente aparece com status de pendente de revisão ✅ O administrador pode aprovar a instância do agente para uso ✅ O usuário pode criar uma instância a partir do Teams e nomeá-la.

Verifique se o agente responde às mensagens

No chat do Teams com seu agente, envie uma mensagem de teste: Hello!

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

Verifique se o agente pode realizar ações

Se você configurar ferramentas, teste a funcionalidade das ferramentas. Por exemplo, se você adicionar o servidor MCP de email, envie um email de teste para si mesmo.

O agente deve:

✅ Acusar o recebimento da solicitação ✅ Executar a chamada de ferramenta ✅ Confirmar a conclusão bem-sucedida

Você deve verificar se o email chegou na sua caixa de entrada.

Verificar a funcionalidade

A seguinte lista de verificação 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 emails. ✅ Pode acessar o calendário. ✅ Pode pesquisar documentos. ✅ Pode realizar ações configuradas.

Tratamento de erros:

✅ Lida com solicitações inválidas de forma adequada. ✅ 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 da solicitação

Para ver o que seu agente está fazendo, verifique os logs do aplicativo usando 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 logs:

✅ Solicitações recebidas do Teams ✅ Autenticação realizada com sucesso ✅ Execução de chamadas de ferramenta ✅ Respostas enviadas ❌ Mensagens de erro ou exceções

Verificar observabilidade no centro de administração

Depois que seu agente começar a executar:

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

2. Selecione seu agente e abra a guia Atividade.

   Você deverá ver:

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

Próximas etapas

Seu agente agora está ativo na nuvem e pronto para trabalhar ao lado da sua equipe no Microsoft 365. O que começou como código local agora é um assistente registrado e pronto para empresas, 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 foi criado no ciclo de desenvolvimento do Agent 365 é de código aberto e está aberto a contribuições da comunidade. Criar bugs, solicitações de recursos e pull requests:

• Exemplos do Agent 365: você tem alguns agentes de exemplo interessantes e divertidos? Compartilhe seu código de agente com a comunidade de código aberto aqui!
• Node.js SDK: o SDK do Agent 365 em Node.js.
• Python SDK: o SDK do Agent 365 no Python.
• .NET SDK: o SDK do Agent 365 no C# (.NET).
• CLI do Agent 365 DevTools: uma CLI para ajudar você durante todo o ciclo de desenvolvimento do Agent 365.

Solução de Problemas

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

O agente não aparece no Teams

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

Causa raiz: configuração do Portal do Desenvolvedor faltando.

Solução:

1. Obtenha sua ID de blueprint de a365.generated.config.json - procure agentBlueprintId.

2. Configure no Portal do Desenvolvedor:

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

   2. Defina Tipo de Agente como Baseado em API

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

   4. Selecione Salvar.

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

Verificação:

• Abra Teams > Aplicativos > Procurar seu agente.
• O agente aparece e está disponível para 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 Solicitar Instância não funciona.

Causa raiz: o Microsoft Agent 365 Frontier não está ativado para o locatário.

Solução: entre em contato com o administrador do locatário para verificar se o Microsoft Agent 365 Frontier está ativado para o locatário.

Saiba mais sobre o Frontier.

Verificação:

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

O agente não responde às mensagens

Sintoma: você cria uma instância de agente, mas ela não responde às mensagens. Não aparecem logs no aplicativo.

Causa principal: diversas causas possíveis – problemas no ponto de extremidade de mensagens, problemas de autenticação ou erros de configuração.

Solução de problemas básicos

1. Verifique se o aplicativo 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 de extremidade de mensagens:

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

3. Teste o ponto de extremidade diretamente:

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

4. Verifique os logs do aplicativo:

   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 expiraram. Renove-os se necessário.
   • Verifique as credenciais na configuração de Aplicativos Web

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

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

3. Teste localmente:

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

Soluções comuns

• Ponto de extremidade de mensagens incorreto: atualização no portal do Azure e no Portal do Desenvolvedor.
• Aplicativo Web interrompido: inicie-o usando o portal do Azure ou da CLI.
• Token expirado: atualize os tokens nas variáveis de ambiente do Aplicativo Web.
• Variáveis de ambiente faltantes: verifique as Configurações do Aplicativo no Portal do Azure.
• Problemas no servidor MCP: verifique a entidade de serviço e as permissões.
• Erros de código: Verifique os logs do aplicativo para identificar exceções.

Verificação

Envie uma mensagem para seu agente no Teams e verifique os logs do aplicativo para solicitações recebidas.

Você também pode tentar:

• Solucionar problemas ao implantar um agente no Amazon Web Services.
• Solucionar problemas ao implantar um agente no Google Cloud Platform.

Falhas nas chamadas de ferramenta

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

Causa raiz: permissões do servidor MCP ausentes, entidade de serviço não configurada, 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 as permissões no centro de administração

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

  • Vá para: 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

• Verificar entidade 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
  

• Verifique a configuração do ponto de extremidade de MCP

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

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

• Verificar identidade gerenciada

  Verifique se a identidade gerenciada está habilitada 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 tentar estas etapas:

• Ferramentas de solução de problemas
• Solucionar problemas no servidor de ferramentas de simulação

A atribuição de licença falha

Sintoma: você não pode atribuir uma licença a um usuário agente. Erros de licença são exibidos no centro de administração.

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

Soluções

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

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

   • Marque >Cobrança>Licenças no centro de administração do Microsoft 365.
   • Certifique-se de que o Microsoft Agent 365 Frontier está habilitado para o locatário.

2. Atribuir licença manualmente:

   • Acesse >Usuários no centro de administração do Microsoft 365.
   • Localize o usuário do 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 recursos do Copilot).

Verificação

Verifique se o perfil do usuário no centro de administração mostra as licenças atribuídas.