Implantar o agente no Azure

Você criou seu agente e o testou localmente. Agora, coloque isso em prática na nuvem. Esta etapa é opcional. Você pode ignorar esta etapa se já implantou seu agente em algum serviço de nuvem (não precisa ser necessariamente o Azure).

Este guia mostra como implantar seu código de agente no Azure e publicá-lo no centro de administração da Microsoft, onde ele se torna um ativo registrado para sua organização.

Para atualizar o ponto de extremidade de mensagens, consulte os seguintes recursos. Eles mostram como você pode atualizar o ponto de extremidade de mensagens se implantou seu agente em outros provedores de nuvem, como Amazon Web Services ou Google Cloud Platform:

• Use o código do agente implantado no Amazon Web Services
• Use o código do agente implantado no Google Cloud Platform

Pré-requisitos

Antes de começar, certifique-se de ter os seguintes itens:

Contas e permissões obrigatórias

• Assinatura do Azure com acesso de colaborador.
• Código de agente funcional com um ponto de extremidade de mensagens válido e acessível. Certifique-se de ter testado seu agente localmente e, opcionalmente, testado com o Microsoft 365 usando Túneis do Desenvolvedor para verificar se o código do agente pode ser criado e funciona como esperado.
• Blueprint de agente válido ao concluir a etapa de configuração de blueprint do agente.
• Arquivos de configuração atualizados a365.config.json, a365.generated.config.json e arquivo de configuração presente no código (por exemplo, arquivo .env).

Ferramentas necessárias

• CLI do Azure instalada e autenticada (Instalar CLI do Azure)

Implantar no Azure

Implante o código do seu aplicativo de agente no Azure usando ferramentas padrão do Azure, como CLI do Azure, portal do Azure ou GitHub Actions.

Implantar aplicativo do agente

Use o comando da CLI do Azure az webapp deploy para implantar seu aplicativo:

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

Para o GitHub Actions, use a ação de Implantação de Aplicativos Web do Azure.

Verificar a implantação

Depois que a implantação for concluída, use esta lista e as instruções nas próximas seções para verificar a implantação.

✅ Comando de implantação concluído sem erros
✅ Aplicativo Web em execução
✅ Os logs do aplicativo mostram que a inicialização foi concluída com êxito
✅ As variáveis do ambiente estão configuradas
✅ O ponto de extremidade de mensagens está respondendo

Certifique-se de que o comando de implantação foi concluído sem erros

Após o término da implantação, verifique o sucesso nos logs de implantação:

1. No portal do Azure, vá para seu aplicativo web.
2. Acesse Configurações>Configuração para verificar as configurações do aplicativo.
3. Verifique os registros de implantação no centro de implantação.

Para ver o histórico detalhado de implantações:

1. Acesse portal do Azure > Seu aplicativo Web
2. Implantação>Centro de Implantação
3. Veja os logs da sua implantação mais recente

Se a compilação falhar:

• Limpe e recrie localmente primeiro para confirmar se a compilação funciona.
• Verifique se há dependências ausentes ou erros de sintaxe.
• Consulte Falha no comando de implantação.

Se o aplicativo travar após a implantação:

• Verifique os logs em busca de mensagens de erro específicas.
• Verifique se todas as variáveis de ambiente necessárias estão definidas.
• Consulte O aplicativo trava ao inicializar.

Verifique se o aplicativo Web está em execução

Use o comando az webapp show para verificar se o aplicativo Web está em execução.

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

A saída esperada deste comando é Running.

Verifique se os logs do aplicativo mostram uma inicialização bem-sucedida

Para exibir os logs do aplicativo Web no portal do Azure:

1. Pesquise o aplicativo Web pelo nome no portal do Azure.
2. Acesse Visão Geral>Logs>Fluxo de Logs.

Como alternativa, você pode usar o comando az webapp log tail do PowerShell para ler os logs do aplicativo da Web:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

Se houver mensagens de travamento ou erro nos logs, consulte O aplicativo trava ao inicializar.

Verificar se as variáveis de ambiente estão configuradas

No portal do Azure:

1. Acesse o aplicativo da Web.
2. Vá para Configurações>Variáveis do Ambiente.
3. Verifique se suas configurações existem.

Se as variáveis de ambiente não estiverem definidas:

• Execute novamente a implantação para sincronizar a partir do arquivo .env.
• Ou defina-as manualmente no portal do Azure.
• Consulte Variáveis de ambiente não definidas ou incorretas.

Verifique se o ponto de extremidade de mensagens responde

Verifique se o ponto de extremidade que você encontra na página Visão Geral do seu aplicativo Web existe, utilizando PowerShell ou outros meios. Caso contrário, consulte 404 no ponto de extremidade da mensagens.

Próximas etapas

Em seguida, publique seu aplicativo de agente no centro de administração da Microsoft para que você possa criar instâncias de agente e usuários a partir dele.

Seu agente agora está disponível na nuvem e pronto para responder a solicitações do agente. À medida que seu agente lida com solicitações do mundo real, considere as próximas etapas para seu código:

• Monitore o desempenho: use recursos de observabilidade para acompanhar o comportamento do agente e otimizar respostas.
• Adicione mais ferramentas: explore o catálogo de ferramentas para expandir as capacidades do seu agente.
• Iterar e melhorar: atualize o código do seu agente, reimplante e republique (lembre-se de incrementar o número da versão!).
• Escalar em toda a sua organização: compartilhe histórias de sucesso do seu agente para impulsionar a adoção.

Solução de Problemas

Esta seção descreve problemas comuns ao implantar agentes no Azure.

Falha no comando Implantar

Sintoma: a implantação falha no Azure.

Causas e soluções comuns:

• Erros de compilação

  Recrie o projeto localmente para ver erros detalhados de compilação:

  # .NET
  dotnet clean
  dotnet build --verbosity detailed
  
  # Python
  uv build
  
  # Node.js
  npm install
  npm run build
  

• Autenticação do Azure expirada

  Entre no Azure novamente:

  az login
  az account show  # Verify correct subscription
  

• Aplicativo Web não criado

  Liste Aplicativos Web para confirmar que o destino existe:

  # List Web Apps in resource group
  az webapp list --resource-group <your-resource-group> --output table
  

• Verificar logs de implantação

  Use o comando az webapp log tail para exibir logs detalhados de implantação:

  az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
  

• Verificação:

  # Web App should be running
  az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
  # Expected: "Running"
  

O aplicativo Web foi interrompido

Sintoma: a implantação é bem-sucedida, mas o aplicativo Web não está em execução.

Solução: use az webapp start e az webapp show para iniciar o aplicativo Web e verificar sua execução.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

O aplicativo trava ao inicializar

Sintoma: o aplicativo Web inicia, mas trava imediatamente; os logs mostram erros.

Causas comuns:

• Dependências ausentes - verifique a saída da compilação para garantir que inclua todos os pacotes necessários.
• Variáveis de ambiente ausentes - verifique se todas configurações obrigatórias estão definidas.
• Incompatibilidade de versão no runtime - Certifique-se de que o runtime do Azure seja compatível com o seu ambiente de desenvolvimento.
• Erros de código - Verifique os logs do aplicativo para identificar exceções específicas.

Solução: use os comandos az webapp log tail, az webapp config appsettings list e az webapp config appsettings set para visualizar logs, verificar variáveis do ambiente e definir variáveis ausentes.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

404 no ponto de extremidade da mensagem

Sintoma: o aplicativo Web está em execução, mas o ponto de extremidade /api/messages retorna 404.

Solução:

1. Verifique a configuração da rota no código do agente.
2. Verifique se o manipulador do ponto de extremidade está corretamente registrado.
3. Certifique-se de que o ponto de entrada correto esteja especificado na implantação.

Teste o ponto de extremidade enviando uma solicitação GET para a URL. Use o comando az webapp config show para verificar a configuração do aplicativo Web.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

Variáveis de ambiente não definidas ou incorretas

Sintoma: a implantação é bem-sucedida, mas o agente não funciona; erros de configuração ausentes nos logs.

Solução: verifique e atualize as variáveis de ambiente. Use os comandos az webapp config appsettings list e az webapp config appsettings set para verificar as variáveis de ambiente e definir as que estão faltando. Depois reimplante.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

A compilação é bem-sucedida localmente, mas falha no Azure

Sintoma: o código é compilado com sucesso localmente, mas falha ao ser implantado no Azure.

Soluções:

• Verifique dependências específicas para plataformas

  • Alguns pacotes têm compilações específicas para cada plataforma.
  • Garanta que as dependências sejam compatíveis com Linux (Aplicativos Web do Azure são executados no Linux por padrão).

• Verifique a correspondência das versões no runtime

  Execute estes comandos:

  # Check your local version
  dotnet --version  # .NET
  node --version    # Node.js
  python --version  # Python
  

  Compare com o runtime do Azure no Portal: Definições>Configuração>Configurações gerais>Configurações da pilha.

Para ajuda adicional, consulte: Solução de problemas de ponto de extremidade de mensagens.