Een agent implementeren in Azure

U hebt uw agent gebouwd en lokaal getest. Breng deze nu tot leven in de cloud. Deze stap is optioneel. U kunt deze stap overslaan als u uw agent al naar een cloud hebt uitgerold (het hoeft niet eens Azure te zijn).

Deze handleiding helpt u bij het implementeren van uw agentcode in Azure en het publiceren ervan in het Microsoft-beheercentrum, waar het een geregistreerde asset voor uw organisatie wordt.

Als u het berichten-eindpunt wilt bijwerken, raadpleegt u de volgende informatiebronnen. Ze laten zien hoe u het berichten-eindpunt kunt bijwerken als u uw agent hebt geïmplementeerd in andere cloudproviders, zoals Amazon Web Services of Google Cloud Platform:

• Agentcode gebruiken die is geïmplementeerd in Amazon Web Services
• Agentcode gebruiken die is geïmplementeerd in Google Cloud Platform

Vereisten

Controleer voordat u begint, of u over de volgende items beschikt:

Vereiste accounts en machtigingen

• Azure-abonnement met toegang als Inzender.
• Werkende agentcode met een geldig en bereikbaar berichten-eindpunt. Zorg ervoor dat u uw agent lokaal hebt getest en eventueel met Microsoft 365 via Dev Tunnels hebt getest om er zeker van te zijn dan de agentcode gebouwd kan worden en wordt uitgevoerd zoals verwacht.
• Geldige agent-blauwdruk door de stap agent-blauwdruk instellen te voltooien.
• Actuele configuratiebestanden a365.config.json, a365.generated.config.json en een configuratiebestand in de code (bijvoorbeeld .env-bestand).

Vereiste hulpprogramma's

• Azure CLI geïnstalleerd en geverifieerd (Azure CLI installeren)

Implementeren op Azure

Implementeer uw agent-toepassingscode in Azure door gebruik te maken van standaard Azure-tools, zoals de Azure CLI, Azure Portal of GitHub Actions.

Agenttoepassing implementeren

Voer de Azure CLI-opdracht az webapp deploy uit om uw toepassing te implementeren:

# 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

Gebruik voor GitHub Actions de actie Azure Web Apps Deploy.

Waarschuwing

Beheer van geheimen: Sla omgevingsvariabelen, waaronder API-sleutels en geheimen, op als Azure-app-instellingen in plaats van ze op te slaan in code of configuratiebestanden. Gebruik voor productieomgevingen Azure Key Vault voor gevoelige geheimen. Zie Veilige opslag van app-geheimen in ontwikkeling in ASP.NET Core en Azure Key Vault-configuratieprovider voor meer informatie. Voer nooit .env bestanden met gevoelige informatie door aan broncodebeheer.

Implementatie controleren

Na voltooiing van de implementatie gebruikt u deze lijst en de instructies in de volgende secties om de implementatie te verifiëren.

✅ Implementatie-opdracht voltooid zonder fouten
✅ Web-app wordt uitgevoerd
✅ Toepassingslogboeken tonen een succesvolle start
✅ Omgevingsvariabelen zijn geconfigureerd
✅ Berichten-eindpunt reageert

Controleer of de implementatieopdracht zonder fouten is uitgevoerd

Controleer na afronding van de implementatie of deze succesvol is verlopen in de implementatielogboeken:

1. Ga naar uw web-app in de Azure-portal.
2. Ga naar Instellingen>Configuratie om de app-instellingen te verifiëren.
3. Controleer de implementatielogboeken in het implementatiecentrum

Ga als volgt te werk als u de gedetailleerde implementatiegeschiedenis wilt bekijken:

1. Ga naar Azure Portal > Uw web-app
2. Implementatie>Implementatiecentrum
3. Logboeken bekijken van uw laatste implementatie

Als de build mislukt:

• Maak lokaal eerst schoon en bouw opnieuw om te controleren of de build slaagt.
• Controleer op ontbrekende afhankelijkheden of syntaxisfouten.
• Zie Implementatie-opdracht mislukt.

Als de app crasht na de implementatie:

• Controleer de logboeken op specifieke foutmeldingen.
• Controleer of alle vereiste omgevingsvariabelen zijn ingesteld.
• Zie Toepassing crasht bij opstarten.

Controleer of de webapp draait

Gebruik de opdracht az webapp show om te controleren of de web-app wordt uitgevoerd.

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

De verwachte uitvoer van deze opdracht is Running.

Controleer of de logboeken van de toepassing een succesvolle start aangeven

Als u logboeken van de web-app wilt bekijken in de Azure Portal:

1. Zoek naar de naam van de web-app in de Azure Portal.
2. Ga naar Overzicht>Logboeken>Logboekstream.

U kunt ook de PowerShell-opdracht az webapp log tail gebruiken om de logboeken van de web-app te lezen:

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

Als er crash- of foutmeldingen in de logboeken staan, zie Toepassing crasht bij opstarten.

Controleren of omgevingsvariabelen zijn geconfigureerd

In de Azure Portal:

1. Ga naar uw web-app.
2. Ga naar Instellingen>Omgevingsvariabelen.
3. Controleer of uw instellingen bestaan.

Als de omgevingsvariabelen niet zijn ingesteld:

• Voer de implementatie opnieuw uit om te synchroniseren vanuit het .env-bestand.
• Of stel ze handmatig in in de Azure Portal.
• Zie Omgevingsvariabelen niet ingesteld of onjuist.

Controleer of het berichten-eindpunt reageert

Controleer met PowerShell of andere middelen of het eindpunt dat u vindt op de Overzichtspagina van uw web-app, daadwerkelijk bestaat. Raadpleeg anders 404-fout voor berichten-eindpunt.

Volgende stappen

Publiceer vervolgens uw agenttoepassing in het Microsoft-beheercentrum zodat u agent-instanties en gebruikers kunt aanmaken.

Publiceer uw agent

Uw agent is nu live in de cloud en klaar om te reageren op agentische aanvragen. Als uw agent echte aanvragen verwerkt, kunt u de volgende stappen overwegen voor uw code:

• Prestaties monitoren: gebruik observability-functies om het gedrag van agenten bij te houden en responsen te optimaliseren.
• Meer hulpprogramma's toevoegen: Verken de catalogus met tools om de mogelijkheden van uw agent uit te breiden.
• Herhalen en verbeteren: Werk uw agentcode bij, implementeer opnieuw en publiceer deze opnieuw (vergeet niet om het versienummer te verhogen!).
• Schalen in uw organisatie: Deel de succesverhalen van uw agent om de acceptatie te stimuleren.

Probleemoplossing

Deze sectie beschrijft veelvoorkomende problemen bij het implementeren van agenten in Azure.

Fooi

De Gids voor probleemoplossing in Agent 365 bevat aanbevelingen voor probleemoplossing op hoog niveau, best practices en links naar relevante probleemoplossingsinformatie voor elk onderdeel van de Agent 365-ontwikkelingscyclus.

Implementatie-opdracht mislukt

Symptoom: Implementatie in Azure mislukt.

Veelvoorkomende oorzaken en oplossingen:

• Build-fouten

  Herbouw het project lokaal om de gedetailleerde compilatiefouten te bekijken:

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

• Azure-verificatie is verlopen

  Meld u opnieuw aan bij Azure:

  az login
  az account show  # Verify correct subscription
  

• Web-app niet aangemaakt

  Geef web-apps weer om te controleren of het doel bestaat:

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

• Implementatielogboeken controleren

  Gebruik de opdracht az webapp log tail om gedetailleerde implementatielogboeken te bekijken:

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

• Verificatie:

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

Web-app is gestopt

Symptoom: De implementatie is geslaagd, maar de web-app wordt niet uitgevoerd.

Oplossing: Gebruik az webapp start en az webapp show om de web-app te starten en te controleren of deze wordt uitgevoerd.

# 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

Toepassing crasht bij opstarten

Symptoom: De web-app start op maar crasht meteen; logboeken tonen fouten.

Veelvoorkomende oorzaken:

• Ontbrekende afhankelijkheden - Controleer de build-uitvoer om te controleren of deze alle vereiste pakketten bevat.
• Ontbrekende omgevingsvariabelen - Verifieer of alle vereiste omgevingsvariabelen zijn geconfigureerd.
• Runtime-versie-mismatch - Zorg ervoor dat de Azure-runtime overeenkomt met uw ontwikkelomgeving.
• Codefouten - Controleer toepassingslogboeken op specifieke uitzonderingen.

Oplossing: Gebruik de opdrachten az webapp log tail, az webapp config appsettings list en az webapp config appsettings set om logboeken te bekijken, omgevingsvariabelen te controleren en ontbrekende variabelen in te stellen.

# 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 op berichten-eindpunt

Symptoom: De web-app wordt uitgevoerd, maar het /api/messages-eindpunt retourneert 404.

Oplossing:

1. Controleer de routeconfiguratie in uw agentcode.
2. Controleer of de eindpunt-handler correct is geregistreerd.
3. Zorg ervoor dat het juiste toegangspunt is gespecificeerd bij de implementatie.

Test het eindpunt door een GET-aanvraag naar de URL te verzenden. Gebruik de opdracht az webapp config show om de configuratie van de web-app te controleren.

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

Omgevingsvariabelen niet ingesteld of onjuist

Symptoom: De implementatie is geslaagd, maar de agent werkt niet; logboeken bevatten fouten vanwege ontbrekende configuratie.

Oplossing: Controleer de omgevingsvariabelen en werk deze bij. Gebruik de opdrachten az webapp config appsettings list en az webapp config appsettings set om omgevingsvariabelen te controleren en ontbrekende variabelen in te stellen. Implementeer vervolgens opnieuw.

# 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

De build slaagt lokaal maar mislukt in Azure

Symptoom: Code wordt zonder problemen gebouwd op uw machine, maar mislukt tijdens de implementatie in Azure.

Oplossingen:

• Controleer op platformspecifieke afhankelijkheden

  • Sommige pakketten hebben platformspecifieke builds.
  • Zorg ervoor dat afhankelijkheden Linux ondersteunen (Azure-web-apps draaien standaard op Linux).

• Controleer of runtime-versies overeenkomen

  Voer deze opdrachten uit:

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

  Vergelijk met Azure runtime in Portal: Instellingen>Configuratie>Algemene instellingen>Stack-instellingen.

Voor extra hulp zie: Probleemoplossing voor het berichten-eindpunt.