Implementar o agente no Azure

Criou o seu agente e testou-o localmente. Agora, dá-lhe vida na cloud. Este passo é opcional. Pode omitir este passo se já implementou o seu agente em alguma cloud (nem precisa ser Azure).

Este guia orienta-o no processo de implementação do código do seu agente no Azure e publicação no centro de administração da Microsoft, onde se torna um ativo registado da sua organização.

Para atualizar o ponto final de mensagens, consulte os seguintes recursos. Mostram como pode atualizar o ponto final de mensagens se implementou o seu agente para outros fornecedores de cloud como o Amazon Web Services ou o Google Cloud Platform:

Pré-requisitos

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

Contas e permissões necessárias

Subscrição do Azure com acesso de contribuidor.
Código de agente funcional com um ponto final de mensagens válido e acessível. Certifique-se de que testou o seu agente localmente e, opcionalmente, testou com o Microsoft 365 através de Túneis de Desenvolvimento, para verificar se o código do agente pode ser criado e é executado como esperado.
Blueprint de agente válido ao concluir o passo de configuração do blueprint do agente.
Ficheiros de configuração atualizados a365.config.json, a365.generated.config.json e ficheiro de configuração no código (por exemplo, ficheiro .env).

Ferramentas necessárias

CLI do Azure instalado e autenticado (Instalar CLI do Azure)

Implementar no Azure

Implemente o código da sua aplicação de agente no Azure utilizando ferramentas padrão do Azure, como a CLI do Azure, o portal do Azure ou o GitHub Actions.

Implementar a aplicação do agente

Utilize o comando az webapp deploy da CLI do Azure para implementar a sua aplicação:

# 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, utilize a ação Azure Aplicações Web Deploy.

Aviso

Gestão de segredos: Armazene variáveis de ambiente, incluindo chaves de API e segredos, como Definições de Aplicação do Azure em vez de nos ficheiros de código ou de configuração. Para ambientes de produção, utilize o Azure Key Vault para segredos confidenciais. Saiba mais sobre o Armazenamento seguro de segredos de aplicações em desenvolvimento no ASP.NET Core e o Fornecedor de configuração do Azure Key Vault. Nunca comprometa ficheiros .env com informações confidenciais para o controlo de código fonte.

Verificar implementação

Após a conclusão da implementação, utilize esta lista e as instruções das secções seguintes para verificar a implementação.

✅ Comando de implementação concluído sem erros
✅ A aplicação Web está em execução
✅ Os registos de aplicação mostram arranque bem-sucedido
✅ As variáveis de ambiente estão configuradas
✅ O ponto final de mensagens responde

Verifique se o comando de implementação foi concluído sem erros

Após a conclusão da implementação, verifique o sucesso nos registos de implementação:

Aceda à aplicação Web no portal do Azure
Aceda a Definições>Configuração para verificar as definições da aplicação.
Verifique os registos de implementação no centro de implantação.

Para ver o histórico de implementação detalhado:

Aceda ao portal do Azure > A sua aplicação Web
Implementação>Centro de Implementação
Veja os registos da sua última implementação

Se a compilação falhar:

Limpe e recrie localmente primeiro para confirmar que a compilação funciona.
Verifique se há dependências em falta ou erros de sintaxe.
Consulte O comando de implementação falha.

Se a aplicação falhar após a implementação:

Verifique nos registos se existem mensagens de erro específicas.
Verifique se todas as variáveis de ambiente necessárias estão definidas.
Consulte A aplicação falha no arranque.

Verifique se a aplicação Web está em execução

Utilize o comando az webapp show para verificar se a aplicação 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 registos da aplicação mostram arranque bem-sucedido

Para ver os registos da aplicação Web no portal do Azure:

Procure a aplicação Web pelo nome no portal do Azure.
Aceda a Descrição geral>Registos>Fluxo de registos.

Em alternativa, pode usar o comando az webapp log tail do PowerShell para ler os registos da aplicação Web:

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

Se houver mensagens de erro ou falha nos registos, consulte Falhas da aplicação no arranque.

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

No portal do Azure:

Aceda à sua aplicação Web.
Aceda a Definições>Variáveis de Ambiente.
Verifique se as suas definições existem.

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

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

Verifique se o ponto final de mensagens responde

Teste se o ponto final que encontra na página Descrição Geral da sua aplicação Web existe, utilizando PowerShell ou outros métodos. Caso contrário, consulte 404 no ponto final de mensagens.

Passos seguintes

De seguida, publique a sua aplicação de agente no centro de administração da Microsoft para que possa criar instâncias de agente e utilizadores a partir dela.

Publicar o seu agente

O seu agente está agora em direto na cloud e pronto para responder a pedidos por meio de agentes. À medida que o seu agente processa pedidos do mundo real, considere estes próximos passos para o seu código:

Monitorizar o desempenho: Utilize funcionalidades de observabilidade para monitorizar o comportamento do agente e otimizar as respostas.
Adicione mais ferramentas: Explore o catálogo de ferramentas para expandir as capacidades do seu agente.
Itere e melhore: Atualize o código do seu agente, volte a implementar e republique (lembre-se de incrementar o número da versão!).
Dimensione na sua organização: Partilhe as histórias de sucesso do seu agente para promover a adoção.

Resolução de Problemas

Esta secção descreve problemas comuns ao implementar agentes no Azure.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

O comando de implementação falha

Sintoma: A implementação no Azure falha.

Causas e soluções comuns:

Erros de compilação

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

# .NET
dotnet clean
dotnet build --verbosity detailed

# Python
uv build

# Node.js
npm install
npm run build

Autenticação do Azure expirada

Inicie sessão novamente no Azure:
```
az login
az account show  # Verify correct subscription
```

Aplicação Web não criada

Liste as Aplicações Web para confirmar que o destino existe:

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

Verificar registos de implementação

Use o comando az webapp log tail para ver registos de implementação detalhados:
```
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"

A aplicação Web está parada

Sintoma: A implementação é bem-sucedida, mas a aplicação Web não está em execução.

Solução: Utilize az webapp start e az webapp show para iniciar a aplicação Web e verificar se 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

A aplicação falha no arranque

Sintoma: A aplicação Web inicia mas falha de imediato; os registos mostram erros.

Causas comuns:

Dependências em falta - Verifique o resultado da compilação para garantir que inclui todos os pacotes necessários.
Variáveis de ambiente em falta - Verifique se todas as definições necessárias estão configuradas.
Incompatibilidade de versão do runtime - Certifique-se de que o runtime do Azure corresponde ao seu ambiente de desenvolvimento.
Erros de código - Verifique os registos da aplicação para exceções específicas.

Solução: Utilize os comandos az webapp log tail, az webapp config appsettings list e az webapp config appsettings set para ver registos, verificar variáveis de ambiente e definir as variáveis em falta.

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

Sintoma: A aplicação Web está em execução, mas o ponto final /api/messages devolve 404.

Solução:

Verifique a configuração da rota no código do agente.
Verifique se o processador do ponto final está devidamente registado.
Certifique-se de que o ponto de entrada correto está especificado na implementação.

Teste o ponto final enviando um pedido GET para o URL. Utilize o comando az webapp config show para verificar a configuração da aplicação 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 implementação é bem-sucedida mas o agente não funciona; faltam erros de configuração nos registos.

Solução: Verifique e atualize variáveis de ambiente. Utilize os comandos az webapp config appsettings list e az webapp config appsettings set para verificar as variáveis de ambiente e definir as que estejam em falta. Depois, reimplemente.

# 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 compila corretamente na sua máquina, mas falha durante a implementação no Azure.

Soluções:

Verifique dependências específicas da plataforma
- Alguns pacotes têm compilações específicas para cada plataforma.
- Garanta que as dependências suportam Linux (as Aplicações Web do Azure são executadas no Linux por predefinição).
Verifique se as versões em tempo de execução correspondem

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>Definições gerais>Definições da pilha.

Para obter ajuda adicional, consulte: Resolução de problemas do ponto final de mensagens.

Comentários

Esta página foi útil?

Last updated on 2026-07-30