Guia de solução de problemas do Agent 365

Use este guia para diagnosticar e resolver problemas ao longo de todo o ciclo de vida de desenvolvimento do Agent 365. Use este artigo como ponto de partida para solução de problemas e, em seguida, acesse seções específicas para soluções detalhadas.

Etapas para solucionar problemas

Cada um dos links nesta tabela fornece etapas de solução de problemas para áreas específicas. O conteúdo é agrupado conforme o estágio do ciclo de vida de desenvolvimento do SDK do Agent 365.

Referência de comandos de diagnóstico

Antes de abordar problemas específicos, utilize estes comandos para verificar o estado atual da configuração do Agent 365:

Verifique a CLI e a configuração

Use esses comandos para validar a CLI e a configuração.

# Verify CLI is installed and check version
a365 --version

# Display current configuration
Get-Content a365.config.json | ConvertFrom-Json

# Display generated configuration (after setup)
Get-Content a365.generated.config.json | ConvertFrom-Json

Verificar recursos do Azure

Use esses comandos para inspecionar os recursos do Azure e o status do aplicativo.

# Set these variables with appropriate data for your app
$resource-group = <your-resource-group>
$app-name = <your-app-name>

# Authenticate with Azure
az login

# List resources in your resource group
az resource list --resource-group $resource-group --output table

# Check Web App status
az webapp show --name $app-name --resource-group $resource-group --query state

# View Web App logs (real-time)
az webapp log tail --name $app-name --resource-group $resource-group

Verificar blueprint do agente

Verifique se o blueprint do agente existe e foi configurado corretamente.

# Check if blueprint ID is set
Get-Content a365.generated.config.json | Select-String "agentBlueprintId"

Verificar blueprint no Microsoft Entra

1. Vá para https://entra.microsoft.com>Registros de aplicativo>Todas as inscrições.
2. Procurar por agentBlueprintId.

Melhores práticas preventivas

Use estas recomendações para evitar problemas comuns e agilizar a solução de problemas.

Antes de começar

Lista de verificação de pré-requisito:

✅ .NET 8.0 SDK instalado
✅ CLI do Azure instalada e autenticada
✅Permissões necessárias do Entra atribuídas
✅ Aplicativo cliente personalizado criado e configurado
✅ Locatário habilitado para o Microsoft Agent 365 Frontier

Comandos de validação:

# Check .NET
dotnet --version

# Check Azure CLI
az --version
az account show

# Check CLI installation
a365 --version

Durante o desenvolvimento

Salve suas configurações:

• Mantenha backups dos arquivos de configuração.
• Documente suas escolhas de configuração.
• Salve IDs geradas, como ID de blueprint e ID de identidade gerenciada.

Mantenha a CLI atualizada:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

Teste de forma incremental:

• Teste após cada etapa principal.
• Verifique se obteve sucesso antes de prosseguir.
• Mantenha as configurações em funcionamento.

Antes da implantação

Lista de verificação de pré-implantação:

✅ O agente funciona localmente no Agents Playground.
✅ Todas as variáveis de ambiente documentadas.
✅ Arquivos de configuração enviados para o controle de versão.
✅ Servidores MCP configurados e testados.
✅ Observabilidade habilitada e verificada.

Obter ajuda técnica

Para revisar código de exemplo, relatar problemas ou pesquisar problemas existentes, utilize estes repositórios:

• Exemplos do Agent 365
• Agent 365 DevTools (CLI)
• Agent 365 SDK - .NET
• SDK do Agent 365 - Python
• SDK do Agent 365 - Node.js