Skonfiguruj agenta Agent 365 wdrożonego w Amazon Web Services (AWS)

Dowiedz się, jak zbudować, hostować, zarejestrować i opublikować agenta Agent 365, który działa na AWS Elastic Beanstalk, przy użyciu Agent 365 CLI. Microsoft Entra i Graph dostarczają tożsamość agenta, uprawnienia oraz blueprint, natomiast AWS Elastic Beanstalk zapewnia środowisko uruchomieniowe.

Jeśli chcesz skierować swojego agenta na kod znajdujący się za punktem końcowym AWS, potrzebujesz tylko następującego kroku: Skonfiguruj hosting nie-Azure. Następnie wykonaj wszystkie pozostałe kroki z Rozpocznij rozwój Agent 365.

Cele

Dowiedz się, jak używać Agent 365 i Microsoft 365 jako warstwy kontrolnej oraz:

  • Wdrożenie środowiska uruchomieniowego agenta na AWS Elastic Beanstalk
  • Skonfiguruj a365.config.json dla hostingu poza Azure
  • Utwórz Agent Blueprint w Entra ID
  • Skonfiguruj OAuth2 oraz dziedziczne uprawnienia
  • Zarejestruj punkt końcowy komunikacji Bot Framework kierujący na AWS
  • Utwórz tożsamość agenta i użytkownika agenta
  • (Opcjonalnie) Opublikuj w obszarach aplikacji Microsoft 365
  • Testowanie interakcji od początku do końca

Wymagania wstępne

Zanim rozpoczniesz, upewnij się, że spełnione są następujące wymagania wstępne dotyczące Azure / Microsoft 365, AWS oraz środowiska lokalnego.

Wymagania wstępne dotyczące platformy Azure / Microsoft 365

Potwierdź dostęp do swojego najemcy Microsoft Entra i zainstaluj następujące narzędzia do tworzenia tożsamości, szablonów oraz rejestracji agenta.

Amazon Web Services (AWS) – wymagania wstępne

Upewnij się, że następujące usługi i narzędzia AWS są skonfigurowane do wdrażania i zarządzania środowiskiem Elastic Beanstalk.

Wymagania wstępne dotyczące środowiska lokalnego

Zainstaluj i skonfiguruj następujące narzędzia w środowisku lokalnym, aby zbudować, uruchomić i wdrożyć agenta.

Tworzenie i wdrażanie agenta .NET

Poniższe instrukcje opisują, jak stworzyć minimalnego agenta, który:

  • Odpowiada na GET /
  • Obsługuje działania Bot Framework na POST /api/messages

Utwórz katalog projektu

mkdir aws-a365-agent
cd aws-a365-agent

Zainicjalizuj projekt .NET

Aby usprawnić pracę, w tym artykule wykorzystano już przygotowany przykład. Sklonuj repozytorium Agent365 Samples i przejdź do dotnet\semantic-kernel\sample-agent.

Przykładowy agent Semantic Kernel – C#/.NET zawiera:

  • Minimalne API internetowe w ASP.NET Core
  • Handler wiadomości Bot Framework pod /api/messages
  • Punkt końcowy kontroli zdrowotnej pod /
  • Integracja Semantic Kernel dla obsługi AI

Przejdź do dotnet\semantic-kernel\sample-agent i sprawdź, czy projekt buduje się pomyślnie:

dotnet restore
dotnet build

Skonfiguruj model

Postępuj zgodnie z instrukcjami zawartymi w Krok 2: Konfiguracja LLM, aby skonfigurować projekt przy użyciu swojego klucza Open API.

Test lokalny (opcjonalnie)

  1. Przed wdrożeniem na AWS przetestuj swojego agenta lokalnie:

    # Run the application
dotnet run

  2. Przetestuj punkty końcowe w innym terminalu:

    # Test agent endpoint locally
curl http://localhost:3978

  3. Naciśnij klawisz Ctrl+C, aby zatrzymać lokalny serwer.

Kompiluj i wdróż

Wybierz preferowaną opcję do zbudowania i wdrożenia tej przykładowej aplikacji:

Opcja A: Kompilacja i wdrożenie z poziomu programu Visual Studio

Użyj AWS Toolkit for Visual Studio, aby opublikować aplikację do Elastic Beanstalk, korzystając z kreatora.

  1. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy swój projekt.

  2. Wybierz „Opublikuj do AWS Elastic Beanstalk”.

  3. Postępuj zgodnie z instrukcjami Kreatora wdrażania Beanstalk:

    • Wybierz profil poświadczeń AWS.
    • Wybierz region (na przykład us-east-1).
    • Wybierz platformę (.NET Core on Linux).
    • Konfigurowanie ustawień środowiska.

  4. Wybierz Wdróż.

Kreator buduje, pakuje i wdraża aplikację na AWS.

Opcja B: Buduj i wdrażaj na AWS Elastic Beanstalk za pomocą CLI

Użyj Elastic Beanstalk CLI, aby zapakować i wdrożyć agenta .NET na 64-bitowe środowisko Amazon Linux 2. Upewnij się, że AWS CLI i EB CLI są skonfigurowane. Aplikacja korzysta ze zmiennej środowiskowej PORT ustawionej przez Beanstalk.

  1. Skompiluj i opublikuj swoją aplikację .NET:

    # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
dotnet publish -c Release -o ./publish --runtime linux-x64

    Utwórz plik Procfile z następującą zawartością.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Zainicjuj Elastic Beanstalk dla .NET. Pojawi się monit z prośbą o wybór regionu i platformy:

    eb init

  3. Wybierz pozycję:

    • Platforma: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Region: Twój preferowany region AWS (np.: us-east-1)

  4. Utwórz pakiet wdrożeniowy i przeprowadź wdrożenie:

    cd publish
zip -r ../deploy.zip .
cd ..
eb create aws-a365-agent-env
eb deploy

    To polecenie:

    • Tworzy aplikację Elastic Beanstalk.
    • Tworzy środowisko z load balancerem.
    • Wdraża Twoją aplikację.
    • Zapewnia niezbędne zasoby AWS.

  5. Po zakończeniu uzyskaj swój punkt końcowy Elastic Beanstalk:

    eb status

    Zanotuj swój punkt końcowy. Powinna to wyglądać następująco:

    http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com

    To jest punkt końcowy messagingEndpoint, który jest używany przez Agent 365 Dev Tools CLI.

Notatka

W środowiskach produkcyjnych skonfiguruj HTTPS, dodając certyfikat SSL/TLS w Elastic Beanstalk. Bot Framework wymaga HTTPS dla punktów końcowych w środowisku produkcyjnym.

Konfiguracja dla hostingu poza Azure

Utwórz a365.config.json ręcznie w folderze projektu Elastic Beanstalk:

Ważne

W przypadku hostingu poza Azure ustaw wartość messagingEndpoint na adres URL Elastic Beanstalk ze ścieżką /api/messages.

Plik a365.config.json powinien wyglądać podobnie do następujących:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

Poniższa tabela podsumowuje ważne pola konfiguracyjne i ich przeznaczenie.

Pole Znaczenie
messagingEndpoint Twój link URL Elastic Beanstalk + /api/messages
deploymentProjectPath Miejsce, gdzie następuje .env stemplowanie

Budowanie agenta Agent 365

Po uruchomieniu kodu agenta na punkcie końcowym AWS, postępuj zgodnie z pozostałymi krokami z Rozpocznij pracę z Agent 365, aby skonfigurować agenta Agent 365.

Sprawdź działanie agenta od początku do końca

Użyj tych kontroli, aby potwierdzić, że Twój agent hostowany na AWS jest osiągalny, odbiera aktywności Bot Framework i poprawnie odpowiada na różnych platformach Agent 365.

Sprawdź łączność Elastic Beanstalk

Wyślij żądanie GET do swojego endpointu Elastic Beanstalk.

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

Żądanie powinno zwrócić następujący komunikat:

AWS Agent is running.

Sprawdź logi Elastic Beanstalk pod kątem przychodzących aktywności Bot Framework

Użyj logów Elastic Beanstalk, aby zweryfikować, czy Twój agent odbiera aktywności Bot Framework i odpowiada poprawnie.

eb logs

Lub monitoruj logi w czasie rzeczywistym:

eb logs --stream

Gdy agent otrzyma wiadomość, zobaczysz:

POST 200 /api/messages
Received activity: { ... }

Agent testowy z powierzchni Agent 365

W zależności od środowiska możesz testować swojego agenta na różnych platformach:

  • Środowisko testowe agentów
  • Teams (jeśli zostały opublikowane)
  • Agent Shell
  • Powierzchnie federowane

Możesz wysyłać wiadomości i weryfikować swoje logi Elastic Beanstalk. Dowiedz się, jak testować agentów za pomocą Microsoft Agent 365 SDK oraz jak weryfikować funkcjonalność swojego agenta przy użyciu narzędzia Agents Playground.

Przebieg pracy dewelopera

Po zakończeniu konfiguracji postępuj zgodnie z tym przepływem pracy dla iteracyjnego rozwoju:

Rozwijaj i testuj lokalnie

Użyj watch mode do szybkiego tworzenia z automatycznym przeładowaniem:

# Automatically rebuild and restart on file changes
dotnet watch run

Wprowadź zmiany w kodzie, zapisz i testuj lokalnie przed wdrożeniem.

Zbuduj i ponownie wdroż na AWS Elastic Beanstalk

Gdy jesteś gotowy do wdrożenia zmian:

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

Testowanie i monitorowanie

Testuj za pomocą powierzchni Agent 365 i monitoruj logi Elastic Beanstalk:

# Stream logs in real-time
eb logs --stream

Nie musisz ponownie tworzyć swojej tożsamości, blueprintu, punktu końcowego bota ani uprawnień.

Rozwiązywanie problemów

Użyj tej sekcji, aby zdiagnozować i rozwiązać typowe problemy podczas wdrażania i uruchamiania agenta Agent 365 na AWS Elastic Beanstalk. Obejmuje łączność i kontrole zdrowotne. Rozwiązuje także wiązania portów, błędy kompilacji oraz problemy licencyjne.

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.

Punkt końcowy wiadomości nie otrzymuje żądań

Sprawdź poniższe informacje:

  • Adres punktu końcowego to dokładnie:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Twoje środowisko Elastic Beanstalk jest zdrowe. Użyj sprawdzania, używając eb health.
  • Grupa bezpieczeństwa pozwala na ruch przychodzący HTTP lub HTTPS.
  • Nie ma reguł zapory ani ograniczeń VPC.

Problemy ze zdrowiem aplikacji

Sprawdź zdrowie środowiska:

eb health --refresh

Wyświetl szczegółowe dzienniki:

eb logs

Problemy z bindowaniem portów

Upewnij się, że aplikacja nasłuchuje na porcie określonym przez zmienną środowiskową PORT. Elastic Beanstalk ustawia tę wartość automatycznie.

Problemy z kompilacją lub uruchomieniem .NET

Sprawdź błędy kompilacji, używając następujących poleceń:

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

Sprawdź wersję .NET:

dotnet --version
dotnet --list-sdks

Sprawdź problemy z pakietami:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Przypisanie licencji kończy się niepowodzeniem

Ręcznie przypisz prawidłową licencję Microsoft 365 lub użyj ścieżki dla użytkownika bez licencji, jeśli jest to obsługiwane.

  • Last updated on