Créer un assistant Agent 365 déployé sur Amazon Web Services (AWS)

Apprenez à créer, héberger, enregistrer et publier un assistant Agent 365 qui s’exécute sur AWS Elastic Beanstalk, en utilisant la CLI de l’Agent 365. Microsoft Entra et Graph fournissent l’identité, les permissions et le Blueprint de l’assistant, tandis qu’AWS Elastic Beanstalk fournit l’environnement d’exécution.

Si vous souhaitez orienter votre assistant vers votre code qui se trouve derrière un point de terminaison AWS, il vous suffit de suivre l’étape suivante : Configurer pour un hébergement hors Azure. Ensuite, suivez toutes les autres étapes à partir du Guide de démarrage du développement Agent 365.

Buts

Apprenez à utiliser Agent 365 et Microsoft 365 comme plan de contrôle et :

  • Déployez l’environnement d’exécution de l’assistant sur AWS Elastic Beanstalk
  • Configurez a365.config.json pour un hébergement hors Azure
  • Créez un Blueprint d’assistant dans Entra ID
  • Configurer OAuth2 + autorisations héritables
  • Enregistrez le point de terminaison de communication du Bot Framework lié à AWS
  • Créez une identité d’assistant + utilisateur d’assistant
  • (Facultatif) Publiez sur les surfaces applicatives Microsoft 365
  • Tester les interactions de bout en bout

Configuration requise

Avant de commencer, assurez-vous que les prérequis suivants pour Azure/Microsoft 365, AWS et l’environnement local sont respectés.

Conditions préalables Azure/Microsoft 365

Vérifiez votre accès au client Microsoft Entra et installez les outils suivants pour créer des identités, des plans d’architecture et inscrire votre assistant.

Prérequis Amazon Web Services (AWS)

Assurez-vous que les services et outils AWS suivants sont configurés pour déployer et gérer votre environnement Elastic Beanstalk.

Prérequis pour l’environnement de développement local

Installez et configurez localement les outils suivants pour créer, exécuter et déployer l’assistant.

Créer et déployer un assistant .NET

Les instructions suivantes décrivent comment créer un assistant minimal pour :

  • Répond à GET /
  • Accepte les activités Bot Framework sur POST /api/messages

Créer un répertoire de projet

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

Initialiser le projet .NET

Pour simplifier votre expérience, cet article utilise un exemple déjà préparé. Clonez le référentiel d’exemples Agent365 et accédez à l’exemple dotnet\semantic-kernel\sample-agent.

L’exemple d’assistant Noyau sémantique - C#/.NET inclut :

Accédez à dotnet\semantic-kernel\sample-agent et vérifiez que le projet se génère correctement :

dotnet restore
dotnet build

Configurer le modèle

Suivez les instructions à l’étape 2 : Configuration du LLM pour configurer le projet en utilisant votre clé API OpenAI.

Tester localement (facultatif)

  1. Avant de déployer sur AWS, testez votre assistant localement :

    # Run the application
dotnet run

  2. Testez les points de terminaison dans un autre terminal :

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

  3. Appuyez sur Ctrl+C pour arrêter le serveur local.

Créer et déployer

Choisissez l’option que vous préférez pour créer et déployer cet exemple d’application :

Option A : créer et déployer depuis Visual Studio

Utilisez la boîte à outils AWS pour Visual Studio pour publier l’application sur Elastic Beanstalk en utilisant un assistant guidé.

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur votre projet.

  2. Sélectionnez Publier sur AWS Elastic Beanstalk.

  3. Suivez l’assistant de déploiement Beanstalk :

    • Choisissez votre profil de connexion AWS.
    • Sélectionnez Région (p. ex., us-east-1).
    • Sélectionnez Plateforme (.NET Core on Linux).
    • Configurez les paramètres de l’environnement.

  4. Sélectionnez Déployer.

L’assistant construit, empaquette et déploie votre application sur AWS.

Option B : créer et déployer sur AWS Elastic Beanstalk via la CLI

Utilisez la CLI Elastic Beanstalk pour empaqueter et déployer l’assistant .NET dans un environnement Amazon Linux 2 64 bits. Assurez-vous que la CLI AWS et la CLI EB sont configurées. L’application est liée à la variable d’environnement PORT définie par Beanstalk.

  1. Créez et publiez votre application .NET :

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

    Créez un Profil avec le contenu suivant.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Initialisez Elastic Beanstalk pour .NET. Choisissez la région et la plateforme :

    eb init

  3. Sélectionnez :

    • Plateforme : 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Région : votre région AWS préférée (p. ex. : us-east-1)

  4. Créez un package de déploiement et déployez :

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

    Cette commande :

    • Crée une application Elastic Beanstalk.
    • Crée un environnement avec un équilibreur de charge.
    • Déployez votre application.
    • Approvisionne les ressources AWS nécessaires.

  5. Une fois terminé, récupérez votre point de terminaison Elastic Beanstalk :

    eb status

    Notez votre point de terminaison. Il doit se présenter comme suit :

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

    Ce point de terminaison est le messagingEndpoint utilisé par l’interface de ligne de commande (CLI) d’Agent 365 Dev Tools.

Note

Pour les environnements de production, configurez HTTPS en ajoutant un certificat SSL/TLS dans Elastic Beanstalk. Le Bot Framework requiert HTTPS pour les points de terminaison de production.

Configuration pour un hébergement hors Azure

Créez a365.config.json manuellement dans le dossier de votre projet Elastic Beanstalk :

Important

Pour un hébergement hors Azure, définissez la valeur messagingEndpoint sur votre URL Elastic Beanstalk avec le chemin d’accès /api/messages.

Le fichier a365.config.json doit ressembler à ce qui suit :

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

Le tableau suivant résume les champs de configuration importants et leur objectif.

Champ Signifie
messagingEndpoint Votre URL Elastic Beanstalk + /api/messages
deploymentProjectPath Où l’affranchissement .env a lieu

Assistant Build Agent 365

Après que le code de votre assistant a été exécuté sur un point de terminaison AWS, suivez les étapes restantes de Commencer le développement de l’Agent 365 pour configurer votre assistant Agent 365.

Vérifiez l’assistant de bout en bout

Utilisez ces vérifications pour confirmer que votre assistant hébergé sur AWS est accessible, reçoit les activités du Bot Framework et répond correctement sur les différentes surfaces d’Agent 365.

Vérifiez la connectivité d’Elastic Beanstalk

Envoyez une requête GET à votre point de terminaison Elastic Beanstalk.

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

La requête doit retourner ce message :

AWS Agent is running.

Vérifier les journaux Elastic Beanstalk pour les messages Bot Framework entrants

Utilisez la journalisation Elastic Beanstalk pour vérifier que votre assistant reçoit des activités Bot Framework et y répond correctement.

eb logs

Ou diffusez les journaux en temps réel :

eb logs --stream

Après qu’un message parvient à votre assistant, vous voyez :

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

Testez l’assistant depuis les surfaces Agent 365

Selon votre environnement, vous pouvez tester votre assistant sur différentes surfaces :

  • Terrain de jeu des agents
  • Teams (si publié)
  • Interpréteur de commandes de l’assistant
  • Surfaces fédérées

Vous pouvez envoyer des messages et vérifier vos journaux Elastic Beanstalk. Découvrez comment tester des assistants en utilisant le kit de développement logiciel (SDK) Microsoft Agent 365 et comment valider le fonctionnement de votre assistant avec l’outil de test Agents Playground.

Workflow du développeur

Une fois la configuration terminée, suivez ce workflow pour un développement itératif :

Développer et tester localement

Utilisez le mode de surveillance pour un développement rapide avec rechargement automatique :

# Automatically rebuild and restart on file changes
dotnet watch run

Faites vos modifications de code, enregistrez et testez localement avant de déployer.

Créer et redéployer sur AWS Elastic Beanstalk

Lorsque vous êtes prêt à déployer vos modifications :

# 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

Tester et surveiller

Testez en utilisant des surfaces Agent 365 et surveillez les journaux Elastic Beanstalk :

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

Vous n’avez pas besoin de recréer votre identité, votre blueprint, votre point de terminaison du bot ou vos autorisations.

Résolution des problèmes

Utilisez cette section pour diagnostiquer et résoudre les problèmes courants lors du déploiement et de l’exécution d’un assistant Agent 365 sur AWS Elastic Beanstalk. Elle couvre la connectivité et les contrôles de santé. Elle traite également de la liaison de ports, des erreurs de compilation et des problèmes de licence.

Astuce

Le Guide de dépannage Agent 365 contient des recommandations générales de dépannage, les meilleures pratiques et des liens vers du contenu de dépannage pour chaque étape du cycle de développement de l’Agent 365.

Le point de terminaison de messagerie ne reçoit pas de requêtes

Vérifiez les informations suivantes :

  • Votre point de terminaison est exactement :
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Votre environnement Elastic Beanstalk est sain. Utilisez la vérification en utilisant eb health.
  • Votre groupe de sécurité autorise le trafic HTTP ou HTTPS entrant.
  • Il n’y a pas de règles de pare-feu ni de restrictions de VPC.

Problèmes de fonctionnement de l’application

Vérifiez la santé de l’environnement :

eb health --refresh

Affichez les journaux détaillés :

eb logs

Problèmes de liaison de port

Assurez-vous que votre application écoute sur le port spécifié par la variable d’environnement PORT. Elastic Beanstalk définit cette valeur automatiquement.

Problèmes de création ou d’exécution .NET

Vérifiez les erreurs de création en utilisant les commandes suivantes :

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

Vérifiez la version de .NET :

dotnet --version
dotnet --list-sdks

Vérifiez les problèmes de packages :

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

L’attribution de licences échoue

Attribuez manuellement une licence Microsoft 365 valide, ou utilisez un utilisateur sans licence si cela est pris en charge.

  • Last updated on