Vytvořte agenta Agent 365 nasazeného v Amazon Web Services (AWS)

Naučte se, jak vytvořit, hostovat, registrovat a publikovat agenta Agent 365, který běží na AWS Elastic Beanstalk, pomocí rozhraní příkazového řádku Agent 365. Microsoft Entra a Microsoft Graph poskytují identitu agenta, oprávnění a podrobný plán, zatímco AWS Elastic Beanstalk poskytuje runtime.

Pokud chcete nasměrovat svého agenta na kód, který je umístěný za koncovým bodem AWS, stačí provést následující krok: Nastavit pro hosting mimo Azure. Poté postupujte podle všech ostatních kroků z Začněte s vývojem Agent 365.

Cíle

Naučte se používat Agent 365 a Microsoft 365 jako řídicí rovinu a:

  • Nasazení modulu runtime agenta na AWS Elastic Beanstalk
  • Konfigurace a365.config.json pro hostování mimo Azure
  • Vytvořit podrobného plánu agenta v Entra ID
  • Konfigurovat OAuth2 a dědičná oprávnění
  • Zaregistrujte koncový bod zpráv Bot Framework směřující na AWS
  • Vytvořte identitu agenta a uživatele agenta
  • (Volitelné) Publikovat do prostředí aplikací Microsoft 365
  • Testování interakcí od začátku do konce

Předpoklady

Než začnete, ujistěte se, že jsou splněny následující požadavky na Azure / Microsoft 365, AWS a lokální prostředí.

Předpoklady Azure / Microsoft 365

Potvrďte přístup ke svému klientovi Microsoft Entra a nainstalujte následující nástroje pro vytváření identit, podrobných plánů a registraci svého agenta.

Předpoklady Amazon Web Services (AWS)

Ujistěte se, že následující AWS služby a nástroje jsou připraveny pro nasazení a správu vašeho prostředí Elastic Beanstalk.

Předpoklady místního vývojového prostředí

Nainstalujte a nakonfigurujte následující nástroje lokálně pro sestavení, spuštění a nasazení agenta.

Vytváření a nasazení agenta .NET

Následující pokyny popisují, jak vytvořit minimálního agenta:

  • Reaguje na GET /
  • Přijímá aktivity Bot Framework na POST /api/messages

Vytvořte adresář projektu

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

Inicializujte projekt .NET

Aby byl postup jednodušší, tento článek používá předpřipravený příklad. Klonujte úložiště vzorků Agent365 a přejděte na vzorek DotNet\semantic-kernel\sample-agent.

Vzorový agent Sémantické jádro - C#/.NET obsahuje:

  • Minimální ASP.NET Core Web API
  • Obslužná rutina zpráv Bot Framework na /api/messages
  • Koncový bod kontroly stavu na /
  • Integrace Sémantické jádro pro funkce AI

Přejděte na dotnet\semantic-kernel\sample-agent a ověřte, že sestavení projektu proběhlo úspěšně:

dotnet restore
dotnet build

Konfigurace modelu

Postupujte podle pokynů v kroku 2: konfigurace LLM a nakonfigurujte projekt s použitím vašeho klíče OpenAPI.

Testujte lokálně (volitelně)

  1. Před nasazením na AWS otestujte svého agenta lokálně:

    # Run the application
dotnet run

  2. Otestujte koncové body v dalším terminálu:

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

  3. Stiskněte Ctrl+C pro zastavení místního serveru.

Sestavení a nasazení

Vyberte možnost, kterou preferujete pro sestavení a nasazení této ukázkové aplikace:

Možnost A: Sestavení a nasazení z Visual Studio

Použijte AWS Toolkit pro Visual Studio k publikování aplikace na Elastic Beanstalk pomocí průvodce.

  1. V Průzkumníku řešení klikněte pravým tlačítkem myši na svůj projekt.

  2. Vyberte Publikovat do AWS Elastic Beanstalk.

  3. Postupujte podle průvodce nasazením Beanstalk:

    • Vyberte svůj profil přihlašovacích údajů AWS.
    • Vyberte oblast (například us-east-1).
    • Vyberte platformu (.NET Core on Linux).
    • Nakonfigurujte nastavení prostředí.

  4. Vyberte Nasadit.

Průvodce sestaví, zabalí a nasadí vaši aplikaci na AWS.

Varianta B: Sestavení a nasazení do AWS Elastic Beanstalk pomocí CLI

Použijte Elastic Beanstalk CLI k zabalení a nasazení agenta .NET do 64-bitového prostředí Amazon Linux 2. Ujistěte se, že jsou AWS CLI a EB CLI správně nakonfigurované. Aplikace používá proměnnou prostředí PORT nastavenou Beanstalkem.

  1. Sestavte a publikujte svou .NET aplikaci:

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

    Vytvořte soubor Procfile s následujícím obsahem.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Inicializujte Elastic Beanstalk pro .NET. Zobrazí se výzva k výběru oblasti a platformy:

    eb init

  3. Vyberte:

    • Platforma: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Oblast: Preferovaná oblast AWS (například: us-east-1)

  4. Vytvořte nasazovací balíček a nasaďte aplikaci:

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

    Tento příkaz:

    • Vytváří aplikaci Elastic Beanstalk.
    • Vytváří prostředí s load balancerem.
    • Nasazuje vaši aplikaci.
    • Zajišťuje nezbytné zdroje AWS.

  5. Po dokončení získejte svůj koncový bod Elastic Beanstalk:

    eb status

    Poznamenejte si svůj koncový bod. Měl by vypadat nějak takto:

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

    Tento koncový bod je messagingEndpoint používaný nástrojem Agent 365 Dev Tools CLI.

Poznámka:

Pro produkční prostředí nakonfigurujte HTTPS přidáním SSL/TLS certifikátu v Elastic Beanstalk. Bot Framework vyžaduje HTTPS pro produkční koncové body.

Konfigurace pro hostování mimo Azure

Vytvořte a365.config.json ručně ve své složce projektu Elastic Beanstalk:

Důležité

Pro hostování mimo Azure nastavte hodnotu messagingEndpoint na URL Elastic Beanstalk s cestou /api/messages.

Soubor a365.config.json by měl vypadat přibližně takto:

{
  "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"
}

Následující tabulka shrnuje důležitá konfigurační pole a jejich účel.

Pole Význam
messagingEndpoint Vaše Elastic Beanstalk URL + /api/messages
deploymentProjectPath Kde dochází k označování .env

Vytvoření agenta Agent 365

Jakmile váš agentní kód běží proti koncovému bodu AWS, postupujte podle zbývajících kroků z Začínáme s vývojem Agent 365 a nastavte svého agenta Agent 365.

Ověření agenta v celém procesu

Pomocí těchto kontrol ověříte, že váš agent hostovaný na AWS je dosažitelný, přijímá aktivity Bot Framework a správně reaguje napříč kanály Agent 365.

Ověřte konektivitu Elastic Beanstalk

Pošlete GET požadavek na koncový bod Elastic Beanstalk.

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

Požadavek by měl vrátit tuto zprávu:

AWS Agent is running.

Zkontrolujte protokoly Elastic Beanstalk na příchozí zprávy Bot Framework

Použijte protokolování Elastic Beanstalk k ověření, zda váš agent přijímá aktivity Bot Framework a správně na ně reaguje.

eb logs

Nebo streamujte protokoly v reálném čase:

eb logs --stream

Jakmile zpráva dorazí k vašemu agentovi, uvidíte:

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

Testování agenta z prostředí Agentu 365

V závislosti na vašem prostředí můžete svého agenta testovat z různých rozhraní:

  • Agents Playground
  • Teams (je-li agent publikován)
  • Agent Shell
  • Federovaná rozhraní

Můžete posílat zprávy a kontrolovat protokoly Elastic Beanstalk. Naučte se, jak testovat agenty pomocí Microsoft Agent 365 SDK a ověřovat funkčnost svého agenta pomocí testovacího nástroje Agents Playground.

Pracovní postup vývojáře

Po dokončení nastavení postupujte podle tohoto postupu pro iterativní vývoj:

Vývoj a testování lokálně

Použijte režim sledování pro rychlý vývoj s automatickým obnovováním:

# Automatically rebuild and restart on file changes
dotnet watch run

Proveďte změny v kódu, uložte je a před nasazením je otestujte v místním prostředí.

Vytvoření a opětovné nasazení do AWS Elastic Beanstalk

Až budete připraveni nasadit své změny:

# 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

Testování a monitorování

Otestujte pomocí rozhraní Agent 365 a sledujte protokoly Elastic Beanstalk:

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

Není třeba znovu vytvářet identitu, podrobný plán, koncový bod bota ani oprávnění.

Řešení problému

Použijte tuto sekci k diagnostice a vyřešení běžných problémů při nasazení a provozu agenta Agent 365 na AWS Elastic Beanstalk. Zahrnuje konektivitu a kontroly stavu. Zabývá se také port bindingem, chybami při sestavení a licenčními problémy.

Zpropitné

Průvodce odstraňováním problémů Agent 365 obsahuje doporučení k odstraňování problémů na vysoké úrovni, osvědčené postupy a odkazy na obsah o řešení problémů pro každou část životního cyklu vývoje Agent 365.

Koncový bod pro zasílání zpráv nepřijímá požadavky

Zkontrolujte následující údaje:

  • Váš koncový bod je přesně:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Vaše prostředí Elastic Beanstalk je v pořádku. Použijte kontrolu pomocí eb health.
  • Skupina zabezpečení povoluje příchozí provoz HTTP nebo HTTPS.
  • Firewall neobsahuje žádná pravidla ani omezení VPC.

Problémy se stavem aplikace

Zkontrolujte stav prostředí:

eb health --refresh

Zobrazit podrobné protokoly

eb logs

Problémy s vázáním portů

Ujistěte se, že vaše aplikace naslouchá na portu, který je určen proměnnou prostředí PORT. Elastic Beanstalk nastavuje tuto hodnotu automaticky.

Problémy s vytvořením nebo modulem runtime .NET

Zkontrolujte chyby sestavení pomocí těchto příkazů:

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

Ověřte verzi .NET:

dotnet --version
dotnet --list-sdks

Zkontrolujte problémy s balíčky:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Přiřazení licence selže

Platnou licenci Microsoft 365 přiřaďte manuálně, nebo použijte cestu pro nelicencované uživatele, pokud je podporována.

  • Last updated on