Implantar agente no Azure

Você criou seu agente e o testou localmente — agora é hora de trazê-lo à vida na nuvem. Essa etapa é opcional e pode ser ignorada se você já implantou seu agente em alguma nuvem (nem precisa ser Azure).

Este guia explica como implantar o código do agente para Azure e publicá-lo no Centro de administração da Microsoft, onde ele se torna um ativo detectável para sua organização.

Também há recursos disponíveis para mostrar como você pode atualizar o endpoint de mensagens caso, ao invés do Microsoft Azure, você já tenha implantado seu agente em outros provedores de nuvem, como Amazon Web Services ou Google Cloud Platform.

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

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

Contas e permissões necessárias

• Assinatura do Azure com acesso de contribuidor.
• Código de agente funcionando com um endpoint de mensagens válido e acessível. Verifique se você teste seu agente localmente e, opcionalmente, testado com Microsoft 365 usando Túneis de Desenvolvimento para verificar se o código do agente pode ser compilado e executado conforme o esperado.
• Conclua a etapa de configuração do blueprint do agente para ter um blueprint válido do agente.
• Certifique-se de que os arquivos a365.config.jsonde configuração e a365.generated.config.json o arquivo de configuração no código (por exemplo, arquivo .env) estejam atualizados.

Ferramentas necessárias

• Azure CLI instalado e autenticado (Instalar Azure CLI)
• CLI A365 instalado (Agente 365 CLI)

Implantar no Azure

O a365 deploy comando possui dois subcomandos:

• a365 deploy app – implanta o código do agente no Aplicativo Web do Azure criado durante a instalação.
• a365 deploy mcp - Atualiza as permissões do servidor MCP no blueprint do seu agente.

Este guia se concentra na implantação do código do aplicativo do agente para Azure.

Implantar aplicação de agente

Execute o a365 deploy comando:

a365 deploy

Opções de implantação

O comando deploy suporta várias opções úteis:

Exemplo de implantação

# Preview what will be deployed
a365 deploy --dry-run

# Deploy with verbose logging for troubleshooting
a365 deploy --verbose

# Inspect the deployment package before uploading
a365 deploy --inspect

Como a implantação funciona

A implantação funciona de forma diferente dependendo da linguagem de programação que você usa.

Verificar a implantação

Após o término da implantação, use esta lista e as instruções abaixo para verificar a implantação

✅ Comando de implantação concluído sem erros
✅ O aplicativo web está rodando
✅ Os logs de aplicação mostram uma startup bem-sucedida
✅ As variáveis de ambiente são configuradas
✅ Endpoint de mensagens responde

Verificar o comando de implantação concluído sem erros

Quando você executa o comando deploy, você deve ver:

✓ Build completed successfully
✓ Deployment completed successfully

Você também deve ver o sucesso indicado nos logs de implantação:

1. Pesquise seu webAppName configurado e acesse seu Aplicativo Web no portal do Azure.
2. Vá para Configurações>Configuração para verificar as configurações do app.
3. Verifique os registros de implantação no centro de implantação.

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

1. Navegue até Azure Portal > seu aplicativo Web
2. Implantação>Centro de Implantação
3. Veja os registros da sua última implantação

Se a compilação falhar:

• Limpe e reconstrua localmente primeiro para confirmar se a construção funciona.
• Verifique se há dependências faltando ou erros de sintaxe.
• Veja o comando Deploy fails.

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

• Verifique os logs para mensagens de erro específicas.
• Verifique se todas as variáveis de ambiente necessárias estão definidas.
• Veja Aplicação trava ao inicializar.

Verifique se o aplicativo web está rodando

Use o az webapp show comando para verificar se o aplicativo web está rodando.

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

A saída esperada desse comando é Running.

Verifique os logs do aplicativo que mostram a 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. Vá para Visão Geral>Logs>Fluxo de Logs.

Alternativamente, você pode usar o comando PowerShell az webapp log tail para ler logs da web app:

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

Se houver mensagens de travamento ou erro nos logs, veja Aplicação trava ao inicializar.

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

No portal do Azure:

1. Navegue até seu aplicativo web.
2. Vá para Configurações>Variáveis de Ambiente.
3. Verifique se suas configurações existem

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

• Reexecute o deploy para sincronizar a partir do .env arquivo.
• Ou configurado manualmente em Azure Portal.
• Veja Variáveis de ambiente não definidas ou incorretas.

Verifique se o endpoint de mensagens responde

Teste se o endpoint que você encontra na página de Visão Geral do seu aplicativo web existe via Powershell ou outros meios. Caso contrário, veja 404 no endpoint de 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 e usuários de agentes a partir dele.

Seu agente agora está ao vivo na nuvem e pronto para responder a solicitações agentais. Enquanto seu agente lida com solicitações do mundo real, considere os próximos passos para o 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 corretor.
• Itere e melhore: Atualize o código do seu agente, redistribua e republique (lembre-se de incrementar o número da versão!).
• Escale em toda a sua organização: Compartilhe histórias de sucesso do seu agente para impulsionar a adoção.

Resolução de problemas

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

Falha no comando de implantação

Sintoma: Erro durante a365 deploy a execução do comando.

Causas comuns e soluções:

• Erros de compilação

  Reconstrua 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
  

• Configuração ausente

  Certifique-se de que ambos os arquivos de configuração existem e estão corretos:

  # Verify configuration files exist
  Test-Path a365.config.json
  Test-Path a365.generated.config.json
  
  # Display configuration file contents
  a365 config display
  
  # Display generated configuration file contents
  a365 config display -g
  

• Autenticação do Azure expirou

  Entre novamente no Azure:

  az login
  az account show  # Verify correct subscription
  

• Aplicativo Web não criado

  Liste Aplicativos Web para confirmar a existência do destino.

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

  Se o Web App não existir, execute a configuração novamente:

  # Verify setup was completed
  a365 config display -g
  # Check for: webAppName
  
  # Check Azure resources exist
  az resource list --resource-group <your-resource-group>
  

• Verifique os logs de implantação

  Use o az webapp log tail comando para visualizar 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 é encerrado

Sintoma: A implantação é bem-sucedida, mas o Web App não está rodando.

Solução: Use az webapp start e az webapp show inicie o aplicativo web e verifique se ele está rodando.

# 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 na inicialização

Sintoma: O aplicativo web inicia, mas trava imediatamente; Os logs mostram erros.

Causas comuns:

• Dependências ausentes - Verifique se a saída da compilação inclui todos os pacotes necessários
• Variáveis de ambiente faltantes - Verifique se todas as configurações necessárias estão configuradas
• Incompatibilidade de versão do Runtime – verifique se o runtime do Azure corresponde ao seu ambiente de desenvolvimento
• Erros de código - Verifique logs de aplicação para exceções específicas

Solução: Use os az webapp log tailcomandos , az webapp config appsettings list, e az webapp config appsettings set para visualizar logs, verificar variáveis de ambiente e definir variáveis faltantes.

# 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 endpoint de mensagens

Sintoma: O aplicativo web está rodando, mas /api/messages o endpoint retorna 404.

Solution:

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

Teste o endpoint enviando uma GET requisição para a URL. Use o az webapp config show comando 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 do ambiente. Use os az webapp config appsettings listcomandos , e az webapp config appsettings set para verificar variáveis de ambiente e definir as variáveis ausentes. 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

# Re-run deployment (it will update app settings from .env)
a365 deploy

Problemas com o pacote de implantação

Sintoma: A implantação é enviada, mas a aplicação não inicia corretamente.

Solução: Use a a365 deploy --inspect flag para examinar o pacote de implantação:

# Inspect what will be deployed
a365 deploy --inspect

Essa bandeira pausa antes do upload, permitindo que você:

• Verifique o conteúdo da pasta de publicação
• Verificar o conteúdo do ZIP
• Certifique-se de que todos os arquivos estejam incluídos

Questões comuns para verificar:

• Ausente node_modules (Node.js)
• DLLs compiladas ausentes (.NET)
• Pacotes de Python ausentes

O build é bem-sucedido localmente, mas falha no Azure

Sintoma: O código compila corretamente em seu computador, mas falha durante a implantação no Azure.

Soluções:

• Verifique dependências específicas de cada plataforma

  • Alguns pacotes têm builds específicas para cada plataforma.
  • Verifique se as dependências dão suporte ao Linux (Azure Web Apps são executadas no Linux por padrão).

• Verifique a correspondência das versões em tempo de execução

  Execute estes comandos:

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

  Comparar com Azure runtime no Portal: Configurações > Configuração > Configurações gerais > Configurações de stack.

• Teste com registro verboso

  a365 deploy --verbose
  

Para ajuda adicional, veja: Solução de problemas de endpoint de mensagens