Implantar agente no Azure

Importante

Você precisa fazer parte do programa de prévia Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. As versões preliminares da Frontier estão sujeitas aos termos de versão preliminar existentes dos contratos de cliente. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

Você criou seu agente e testou-o localmente. Agora, traga-o à vida na nuvem. Esta etapa é opcional. Você pode ignorá-lo se já tiver implantado seu agente em alguma nuvem (ele nem precisa ser o 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.

Para atualizar o endpoint de mensagem, consulte os recursos a seguir. 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:

Pré-requisitos

Antes de começar, verifique se você tem os seguintes itens:

Contas e permissões necessárias

Ferramentas necessárias

Implantar no Azure

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

Implantar aplicação de agente

Use o comando da CLI az webapp deploy do Azure 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 Azure Web Apps Deploy.

Aviso

Gerenciamento de segredos: armazene variáveis de ambiente, incluindo chaves de API e segredos, como Configurações de Aplicativo do Azure em vez de arquivos de código ou configuração. Para ambientes de produção, use Azure Key Vault para segredos confidenciais. Saiba mais sobre o armazenamento seguro de segredos do aplicativo em desenvolvimento no ASP.NET Core e o provedor de configuração do Azure Key Vault. Nunca confirme arquivos .env com informações confidenciais para o controle do código-fonte.

Verificar a implantação

Após a conclusão da implantação, use esta lista e as instruções nas seções a seguir 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
✅ O ponto de extremidade de mensagens responde

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

Após a conclusão da implantação, verifique o êxito nos logs de implantação:

  1. No portal do Azure, vá para seu aplicativo web.
  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. Acesse o portal > do Azure 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 recrie localmente primeiro para confirmar se a compilação funciona.
  • Verifique se há dependências faltando ou erros de sintaxe.
  • Consulte Falha no comando de implantação.

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. Vá para seu aplicativo Web.
  2. Vá para Configurações>Variáveis de Ambiente.
  3. Verifique se as configurações existem.

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

Verifique se o endpoint de mensagens responde

Teste se o ponto de extremidade encontrado na página visão geral do aplicativo Web existe usando o PowerShell ou outros meios. Caso contrário, consulte 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.

Publique seu agente

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!).
  • Escalar 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.

Dica

O Guia de Solução de Problemas do Agente 365 contém recomendações de resolução de problemas de alto nível, melhores práticas e links para conteúdo de solução de problemas para cada parte do ciclo de desenvolvimento do Agente 365.

Falha no comando de implantação

Sintoma: Falha na implantação no Azure.

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

  • 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

  • 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 aplicativo Web não está em execução.

Solução: Use az webapp start e az webapp show inicie o aplicativo Web e verifique se ele está em 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 na inicialização

Sintoma: O aplicativo Web é iniciado, mas falha imediatamente; os logs mostram erros.

Causas comuns:

  • Dependências ausentes – verifique a saída do build para garantir que ela inclua todos os pacotes necessários.
  • Variáveis de ambiente ausentes – verifique se todas as configurações necessárias estão configuradas.
  • Incompatibilidade de versão de runtime – verifique se o runtime do Azure corresponde ao seu ambiente de desenvolvimento.
  • Erros de código – verifique os logs de aplicativos em busca de 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 ponto de extremidade da mensagem

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

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.

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

  • Last updated on