Erstellen Sie einen Agent 365-Agenten, der auf Amazon Web Services (AWS) bereitgestellt wird

Lernen Sie, wie Sie einen Agent 365-Agenten erstellen, hosten, registrieren und veröffentlichen, der auf AWS Elastic Beanstalk läuft, mit der Agent 365 CLI. Microsoft Entra und Graph stellen die Agentenidentität, Berechtigungen und den Blueprint bereit, während AWS Elastic Beanstalk die Laufzeit bereitstellt.

Wenn Sie Ihren Agenten auf Ihren Code ausrichten möchten, der sich hinter einem AWS-Endpunkt befindet, reicht folgender Schritt aus: Konfigurieren Sie für Hosting außerhalb von Azure. Folgen Sie dann allen weiteren Schritten aus Erste Schritte bei der Agent 365-Entwicklung.

Ziele

Erfahren Sie, wie Sie Agent 365 und Microsoft 365 als Steuerebene nutzen und:

  • Agent-Runtime auf AWS Elastic Beanstalk bereitstellen
  • Konfigurieren Sie a365.config.json für nicht-Azure-Hosting
  • Agent Blueprint in Entra ID erstellen
  • Konfigurieren Sie OAuth2 + vererbbare Berechtigungen
  • Bot Framework-Messaging-Endpunkt, der auf AWS verweist, registrieren
  • Erstellen Sie die Agenten-Identität und den Agenten-Benutzer
  • (Optional) Auf Microsoft 365 App-Oberflächen veröffentlichen
  • End-to-End-Interaktionen testen

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass die folgenden Voraussetzungen für Azure / Microsoft 365, AWS und die lokale Umgebung erfüllt sind.

Azure / Microsoft 365-Voraussetzungen

Bestätigen Sie Ihren Microsoft Entra-Mandant-Zugriff und installieren Sie die folgenden Tools, um Identitäten, Baupläne zu erstellen und Ihren Agenten zu registrieren.

Voraussetzungen für Amazon Web Services (AWS)

Stellen Sie sicher, dass die folgenden AWS-Dienste und -Tools eingerichtet sind, um Ihre Elastic Beanstalk-Umgebung bereitzustellen und zu verwalten.

Voraussetzungen für das lokale Entwicklungsumfeld

Installieren und konfigurieren Sie die folgenden Tools lokal, um den Agenten zu erstellen, zu starten und bereitzustellen.

Einen benutzerdefinierten .NET Agenten erstellen und bereitstellen

Die folgenden Anweisungen beschreiben, wie man einen minimalen Agenten erstellt, der:

  • Antwortet auf GET /
  • Akzeptiert Bot Framework-Aktivitäten bei POST /api/messages

Projektverzeichnis erstellen

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

Das .NET-Projekt initialisieren

Um Ihre Erfahrung zu vereinfachen, verwendet dieser Artikel ein bereits vorbereitetes Beispiel. Klonen Sie das Agent365 Beispiel-Repository und gehen Sie zum dotnet\semantic-kernel\sample-agent Beispiel.

Die Semantischer Kernel Beispiel-Agent - C#/.NET enthält:

  • Eine minimale ASP.NET Core-Web-API
  • Bot Framework-Nachrichtenhandler bei /api/messages
  • Endpunkt der Integritätsprüfung bei /
  • Integration des semantischen Kernel für KI-Fähigkeiten

Gehen Sie zu dotnet\semantic-kernel\sample-agent und überprüfen Sie, ob das Projekt erfolgreich erstellt wird:

dotnet restore
dotnet build

Modell konfigurieren

Befolgen Sie die Anweisungen in Schritt 2: LLM-Konfiguration, um das Projekt mit Ihrem OpenAI-API-Schlüssel zu konfigurieren.

Lokal testen (optional)

  1. Testen Sie Ihren Agenten vor der Bereitstellung auf AWS lokal:

    # Run the application
dotnet run

  2. Testen Sie die Endpunkte in einem anderen Terminal:

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

  3. Drücken Sie Ctrl+C, um den lokalen Server zu stoppen.

Erstellen und Bereitstellen

Wählen Sie die Option, die Sie bevorzugen, um diese Beispielanwendung zu erstellen und bereitzustellen:

Option A: Erstellen und Bereitstellen mit Visual Studio

Verwenden Sie das AWS Toolkit für Visual Studio, um die App mithilfe eines geführten Assistenten auf Elastic Beanstalk zu veröffentlichen.

  1. Klicken Sie im Lösungsexplorer mit der rechten Maustaste auf Ihr Projekt.

  2. Wählen Sie 'In AWS Elastic Beanstalk veröffentlichen'.

  3. Folgen Sie dem Assistent für Beanstalk-Bereitstellung:

    • Wählen Sie Ihr AWS-Anmeldeinformationsprofil aus.
    • Wählen Sie die Region (Beispielsweise us-east-1).
    • Wählen Sie Plattform (.NET Core on Linux).
    • Umgebungseinstellungen konfigurieren.

  4. Wählen Sie Bereitstellen aus.

Der Assistent erstellt, paketiert und stellt Ihre Anwendung auf AWS bereit.

Option B: Erstellen und Bereitstellen auf AWS Elastic Beanstalk mit CLI

Verwenden Sie die Elastic Beanstalk-CLI, um den .NET-Agenten in einer 64-Bit-Amazon Linux 2-Umgebung zu paketieren und bereitzustellen. Stellen Sie sicher, dass AWS CLI und EB CLI konfiguriert sind. Die App bindet an die von Beanstalk gesetzte PORT-Umgebungsvariable.

  1. Erstellen und veröffentlichen Sie Ihre .NET-Anwendung:

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

    Erstellen Sie Procfile mit dem folgenden Inhalt.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Initialisieren Sie Elastic Beanstalk für .NET. Sie werden aufgefordert, Region und Plattform auszuwählen:

    eb init

  3. Wählen Sie Folgendes aus:

    • Platform: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Region: Ihre bevorzugte AWS-Region (zum Beispiel: us-east-1)

  4. Wählen Sie ein Bereitstellungspaket und eine Bereitstellung aus:

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

    Dieser Befehl:

    • Erstellt eine Elastic Beanstalk-Anwendung.
    • Erstellt eine Umgebung mit einem Load Balancer.
    • Stellt Ihre Anwendung bereit.
    • Stellt notwendige AWS-Ressourcen bereit.

  5. Wenn Sie fertig sind, rufen Sie Ihren Elastic Beanstalk-Endpunkt ab.

    eb status

    Notieren Sie sich Ihren Endpunkt. Es sollte in etwa so aussehen:

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

    Dieser Endpunkt ist der messagingEndpoint, der von der Agent 365 Dev Tools CLI verwendet wird.

Anmerkung

In Produktionsumgebungen konfigurieren Sie HTTPS, indem Sie ein SSL/TLS-Zertifikat in Elastic Beanstalk bereitstellen. Das Bot Framework benötigt HTTPS für Produktionsendpunkte.

Konfiguration für Nicht-Azure-Hosting

Erstellen Sie a365.config.json manuell in Ihrem Elastic Beanstalk-Projektordner:

Wichtig

Für Nicht-Azure-Hosting setzen Sie den messagingEndpoint-Wert auf Ihre Elastic Beanstalk-URL mit dem /api/messages-Pfad.

Die vollständige a365.config.json-Datei sollte in etwa so aussehen:

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

Die folgende Tabelle fasst wichtige Konfigurationsfelder und deren Zweck zusammen.

Feld Bedeutung
messagingEndpoint Die Elastic Beanstalk-URL + /api/messages
deploymentProjectPath Wo .env das Stempeln stattfindet

Agent 365-Agent erstellen

Nachdem dein Agent-Code an einem AWS-Endpunkt läuft, folge den verbleibenden Schritten von Get Start with Agent 365 development , um deinen Agent 365 Agenten einzurichten.

Überprüfen Sie den End-to-End-Agent

Nutzen Sie diese Überprüfungen, um zu bestätigen, dass Ihr auf AWS gehosteter Agent erreichbar ist, Bot Framework-Aktivitäten empfängt und über alle Oberflächen von Agent 365 korrekt antwortet.

Überprüfen Sie die Verbindung zu Elastic Beanstalk

Senden Sie eine GET-Anfrage an Ihren Elastic Beanstalk-Endpunkt.

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

Die Anfrage sollte folgende Nachricht zurückgeben:

AWS Agent is running.

Überprüfen Sie die Elastic Beanstalk-Protokolle auf eingehende Bot Framework-Nachrichten

Nutzen Sie Elastic Beanstalk Protokollierung , um zu überprüfen, dass Ihr Agent Bot Framework-Aktivitäten empfängt und korrekt reagiert.

eb logs

Oder zeigen Sie Protokolle in Echtzeit an:

eb logs --stream

Nachdem eine Nachricht Ihren Agenten erreicht hat, sehen Sie Folgendes:

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

Agent von Agent 365-Oberflächen aus testen

Je nach Umgebung können Sie Ihren Agenten auf verschiedenen Oberflächen testen:

  • Agents Playground
  • Teams (falls veröffentlicht)
  • Agent Shell
  • Föderierte Oberflächen

Sie können Nachrichten senden und Ihre Elastic Beanstalk-Protokolle überprüfen. Erfahren Sie, wie Sie Agenten mit dem Microsoft Agent 365 SDK testen und die Funktionalität Ihres Agenten mit dem Agents Playground Testtool validieren.

Entwickler-Workflow

Sobald die Einrichtung abgeschlossen ist, folgen Sie diesem Workflow für die iterative Entwicklung.

Lokales Entwickeln und Testen

Verwenden Sie den Überwachungsmodus für schnelle Entwicklung mit automatischem Neuladen:

# Automatically rebuild and restart on file changes
dotnet watch run

Nehmen Sie Ihre Code-Änderungen vor, speichern Sie diese und testen Sie lokal, bevor Sie deployen.

Bauen und neu deployen auf AWS Elastic Beanstalk

Wenn Sie bereit sind, Ihre Änderungen bereitzustellen:

# 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

Testen und überwachen

Testen Sie mit Agent 365-Oberflächen und überwachen Sie die Elastic Beanstalk Protokolle:

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

Es ist nicht erforderlich, Ihre Identität, Blueprint, Bot-Endpunkt oder Berechtigungen erneut zu erstellen.

Problembehandlung

Verwenden Sie diesen Abschnitt, um häufige Probleme beim Bereitstellen und Ausführen eines Agent 365-Agenten auf AWS Elastic Beanstalk zu diagnostizieren und zu beheben. Es deckt Konnektivität und Zustandsprüfungen ab. Es behandelt außerdem Portbindung, Build-Fehler und Lizenzprobleme.

Trinkgeld

Die Agent 365 Troubleshooting-Anleitung enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Abschnitt des Entwicklungszyklus von Agent 365.

Der Messaging-Endpunkt empfängt keine Anfragen

Prüfen Sie die folgenden Details:

  • Ihr Endpunkt ist genau:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Ihre Elastic Beanstalk-Umgebung ist integer. Verwenden Sie die Überprüfung mit eb health.
  • Ihre Sicherheitsgruppe erlaubt eingehenden HTTP- oder HTTPS-Verkehr.
  • Es gibt keine Firewall-Regeln oder VPC-Einschränkungen.

Anwendungs-Integritätsprobleme

Umgebungsintegrität überprüfen:

eb health --refresh

Detaillierte Protokolle anzeigen:

eb logs

Portbindungsprobleme

Stellen Sie sicher, dass Ihre Anwendung auf dem von der Umgebungsvariable PORT angegebenen Port reagiert. Elastic Beanstalk setzt diesen Wert automatisch.

.NET-Build- oder Laufzeitprobleme

Überprüfen Sie Build-Fehler mit diesen Befehlen:

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

Überprüfen Sie die .NET-Version:

dotnet --version
dotnet --list-sdks

Überprüfen Sie, ob Paketprobleme vorliegen:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Lizenzzuweisung fehlgeschlagen

Ordnen Sie manuell eine gültige Microsoft 365-Lizenz zu oder verwenden Sie einen nicht lizenzierten Benutzerpfad, sofern unterstützt.

  • Last updated on