Wdrażanie agenta na platformie Azure

Zbudowano agenta i przetestowano go lokalnie. Teraz ożyw go w chmurze. To krok jest opcjonalny. Możesz to pominąć, jeśli już wdrożono agenta w dowolnej chmurze (nawet nie musi to być Azure).

Ten przewodnik przeprowadza przez wdrażanie kodu agenta w Azure i jego publikację w Centrum administracyjnym Microsoft, gdzie staje się zarejestrowanym zasobem organizacji.

Aby zaktualizować punkt końcowy wiadomości, zapoznaj się z poniższymi materiałami. Pokazują, jak można zaktualizować punkt końcowy wiadomości, jeśli wdrożono agenta u innych dostawców usług chmury, takich jak Amazon Web Services czy Google Cloud Platform:

• Skorzystaj z kodu agenta wdrożonego na Amazon Web Services
• Skorzystaj z kodu agenta wdrożonego na Google Cloud Platform

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz następującą elementy:

Wymagane konta i uprawnienia

• Subskrypcja Azure z uprawnieniami współtwórcy.
• Działający kod agenta z prawidłowym i dostępnym punktem końcowym komunikacji. Upewnij się, że przetestowano agenta lokalnie oraz opcjonalnie przetestowano go z Microsoft 365, korzystając z tuneli dev, aby zweryfikować, że kod agenta można zbudować i że działa zgodnie z oczekiwaniami.
• Poprawny plan agenta po ukończeniu kroku konfiguracja kroku strategii agenta.
• Aktualne pliki konfiguracyjne a365.config.json, a365.generated.config.json oraz plik konfiguracyjny w kodzie (np. plik .env).

Wymagane narzędzia

• Interfejs wiersza polecenia platformy Azure zainstalowany i uwierzytelniony (Instrukcja instalacji Azure CLI)

Wdróż na platformie Azure

Wdroż kod aplikacji agenta na platformę Azure, korzystając ze standardowych narzędzi Azure, takich jak Azure CLI, Azure Portal lub GitHub Actions.

Wdrażanie aplikacji agenta

Użyj az webapp deploypolecenia Azure CLI, aby wdrożyć swoją aplikację:

# 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

Dla GitHub Actions użyj akcji Azure Web Apps Deploy.

Ostrzeżenie

Zarządzanie sekretami: Przechowuj zmienne środowiskowe, w tym klucze API i sekrety, jako ustawienia aplikacji Azure, a nie w kodzie lub plikach konfiguracyjnych. W środowiskach produkcyjnych używaj Azure Key Vault do wrażliwych sekretów. Dowiedz się więcej o bezpiecznym przechowywaniu sekretów aplikacji w środowisku deweloperskim w ASP.NET Core oraz o dostawcy konfiguracji Azure Key Vault. Nigdy nie zatwierdzaj .env plików zawierających wrażliwe informacje do systemu kontroli wersji.

Weryfikuj wdrażanie

Po zakończeniu wdrożenia skorzystaj z tej listy oraz instrukcji zawartych w poniższych sekcjach, aby zweryfikować wdrożenie.

✅ Polecenie wdrożenia zakończone bez błędów
✅ Aplikacja jest uruchomiona
✅ Dzienniki aplikacji pokazują udane uruchomienie
✅ Zmienne środowiskowe są skonfigurowane
✅ Punkt końcowy wiadomości odpowiada

Zweryfikuj, czy polecenie wdrożenia zakończyło się bez błędów

Po zakończeniu wdrożenia zweryfikuj poprawność w dziennikach wdrożeń:

1. Przejdź do zarządzania aplikacją internetową w Azure Portal.
2. Przejdź do Ustawienia>Konfiguracja, aby zweryfikować ustawienia aplikacji.
3. Sprawdź dzienniki wdrożeń w Centrum Wdrożeń.

Aby zobaczyć szczegółową historię wdrożeń:

1. Przejdź do portalu Azure Portal > aplikacja internetowa
2. Wdrażanie>Centrum wdrażania
3. Zobacz dzienniki z najnowszego wdrożenia

Jeśli proces budowania zakończy się niepowodzeniem:

• Najpierw wyczyść i zbuduj lokalnie, aby potwierdzić, że proces budowania działa poprawnie.
• Sprawdź, czy nie brakuje zależności lub błędów składniowych.
• Zobacz Niepowodzenie polecenia wdrożenia.

Jeśli aplikacja ulegnie awarii po wdrożeniu:

• Sprawdź dzienniki pod kątem konkretnych komunikatów o błędach.
• Sprawdź, czy ustawiono wszystkie wymagane zmienne środowiskowe.
• Zobacz Aplikacja ulega awarii podczas uruchamiania.

Sprawdź, czy aplikacja webowa działa

Użyj polecenia az webapp show, aby zweryfikować, czy aplikacja webowa działa.

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

Spodziewany wynik tego polecenia to Running.

Sprawdź, czy dzienniki aplikacji pokazują pomyślne uruchomienie

Aby wyświetlić dzienniki aplikacji webowej w portalu Azure Portal:

1. Wyszukaj aplikację webową według nazwy w portalu Azure Portal.
2. Przejdź do Przegląd>Dzienniki>Strumień dziennika.

Alternatywnie możesz użyć polecenia az webapp log tail PowerShell, aby odczytać logi aplikacji webowej:

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

Jeśli w dziennikach pojawiają się komunikaty o awarii lub błędach, zobacz Aplikacja ulega awarii przy uruchamianiu.

Sprawdź, czy zmienne środowiskowe są poprawnie skonfigurowane

W witrynie Azure Portal:

1. Przejdź do swojej aplikacji internetowej.
2. Przejdź do Ustawień>Zmienne środowiskowe.
3. Upewnij się, że ustawienia istnieją.

Jeśli zmienne środowiskowe nie są ustawione:

• Ponownie uruchom wdrożenie, aby zsynchronizować z plikiem .env.
• Lub ustaw je ręcznie w portalu Azure Portal.
• Zobacz Zmienne środowiskowe nie są ustawione lub są nieprawidłowe.

Weryfikacja odpowiedzi przez punkt końcowy komunikatów

Przetestuj, czy punkt końcowy, który znajdziesz na stronie Omówienie swojej aplikacji webowej, istnieje, korzystając z PowerShell lub innych narzędzi. W przeciwnym razie zobacz Błąd 404 dotyczący punktu końcowego komunikacji.

Następne kroki

Następnie opublikuj swoją aplikację agenta w centrum administracyjnym Microsoft, aby tworzyć z niej instancje agentów i użytkowników.

Opublikuj agenta

Twój agent jest już wdrożony w chmurze i gotowy do obsługi żądań agentowych. Kiedy Twój agent obsługuje rzeczywiste żądania, rozważ następujące kroki dla kodu agenta:

• Monitoruj działanie: Skorzystaj z funkcji obserwowalności, aby śledzić zachowanie agenta i optymalizować jego odpowiedzi.
• Dodaj nowe narzędzia: Skorzystaj z katalogu narzędzi, aby rozbudować funkcjonalność agenta.
• Udoskonalaj i rozwijaj: Aktualizuj kod agenta, wdrażaj go ponownie i publikuj (pamiętaj o zaktualizowaniu numeru wersji!).
• Skaluj w całej organizacji: Podziel się historiami sukcesu swojego agenta, aby zwiększyć adopcję.

Rozwiązywanie problemów

W tej sekcji opisano najczęstsze problemy podczas wdrażania agentów na platformę Azure.

Wskazówka

Przewodnik po rozwiązywaniu problemów Agent 365 zawiera wysokopoziomowe zalecenia dotyczące rozwiązywania problemów, najlepsze praktyki oraz odnośniki do treści dotyczących rozwiązywania problemów dla każdego etapu cyklu rozwoju Agent 365.

Niepowodzenie polecenia wdrożenia

Objaw: Wdrożenie na platformie Azure nie powiodło się.

Najczęstsze przyczyny i rozwiązania:

• Błędy kompilacji

  Przebuduj projekt lokalnie, aby zobaczyć szczegółowe błędy kompilacji:

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

• Uwierzytelnienie Azure wygasło

  Ponownie zaloguj się do Azure:

  az login
  az account show  # Verify correct subscription
  

• Aplikacja webowa nie została utworzona

  Wyświetl aplikacje internetowe, aby potwierdzić, że docelowa aplikacja istnieje:

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

• Sprawdź dzienniki wdrożeń

  Użyj polecenia az webapp log tail, aby wyświetlić szczegółowe dzienniki wdrożeń:

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

• Weryfikacja:

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

Aplikacja webowa jest zatrzymana

Objaw: wdrożenie zakończyło się sukcesem, ale aplikacja webowa nie jest uruchomiona.

Rozwiązanie: użyj az webapp start i az webapp show aby uruchomić aplikację webową i sprawdzić, czy działa.

# 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

Aplikacja ulega awarii podczas uruchamiania

Objaw: Aplikacja webowa uruchamia się, ale natychmiast ulega awarii; w logach występują błędy.

Najczęstsze przyczyny:

• Brakujące zależności – Sprawdź log kompilacji, aby upewnić się, że zawiera wszystkie wymagane pakiety.
• Brakujące zmienne środowiskowe – Sprawdź, czy wszystkie wymagane zmienne środowiskowe zostały poprawnie ustawione.
• Niezgodność wersji środowiska uruchomieniowego – upewnij się, że środowisko uruchomieniowe Azure odpowiada twojemu środowisku deweloperskiemu.
• Błędy kodu – Sprawdź dzienniki aplikacji pod kątem określonych wyjątków.

Rozwiązanie: Użyj poleceń az webapp log tail, az webapp config appsettings list oraz az webapp config appsettings set do wyświetlania dzienników, sprawdzania zmiennych środowiskowych oraz uzupełniania brakujących zmiennych środowiskowych.

# 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 na punkcie końcowym komunikacyjnym

Objaw: Aplikacja webowa działa, ale punkt końcowy /api/messages zwraca 404.

Rozwiązanie:

1. Sprawdź konfigurację trasy w kodzie agenta.
2. Sprawdź, czy procedura obsługi punktu końcowego jest poprawnie zarejestrowany.
3. Upewnij się, że we wdrożeniu wskazano właściwy punkt wejścia.

Przetestuj punkt końcowy, wysyłając żądanie GET na adres URL. Użyj polecenia az webapp config show, aby sprawdzić konfigurację aplikacji webowej.

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

Zmienne środowiskowe nie są ustawione lub są nieprawidłowe

Objaw: Wdrożenie zakończyło się sukcesem, ale agent nie działa; w logach występują błędy związane z brakującą konfiguracją.

Rozwiązanie: Zweryfikuj i zaktualizuj zmienne środowiskowe. Użyj poleceń az webapp config appsettings list i az webapp config appsettings set, aby sprawdzić zmienne środowiskowe i ustawić brakujące zmienne. Następnie wdroż ponownie.

# 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

Kompilacja działa lokalnie, ale w Azure zawodzi

Objaw: Kod kompiluje się poprawnie na lokalnej maszynie, ale kończy się niepowodzeniem podczas wdrożenia w Azure.

Rozwiązania:

• Sprawdź zależności platformowe

  • Niektóre pakiety mają kompilacje dedykowane określonym platformom.
  • Upewnij się, że zależności działają na Linuksie (Azure Web Apps domyślnie działają na Linuksie).

• Zweryfikuj zgodność wersji środowiska uruchomieniowego

  Uruchom następujące polecenia:

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

  Porównaj ze środowiskiem uruchomieniowym Azure w Portalu: Ustawienia>Konfiguracja>Ustawienia ogólne>Ustawienia stosu.

Aby uzyskać dodatkową pomoc, zobacz: Rozwiązywanie problemów z punktem końcowym komunikacji.