Partager via

Construire un agent Agent 365 déployé dans Amazon Web Services (AWS)

Important

Vous devez faire partie du programme Frontier en version préliminaire pour obtenir un accès anticipé à Microsoft Agent 365. Frontier vous connecte directement aux dernières innovations d’IA de Microsoft. Les versions préliminaires Frontier sont soumises aux conditions existantes de vos contrats clients qui régissent les versions préliminaires. Comme ces fonctionnalités sont encore en cours de développement, leur disponibilité et leurs capacités peuvent évoluer au fil du temps.

Apprenez à construire, héberger, enregistrer et publier un agent Agent 365 qui fonctionne sur AWS Elastic Beanstalk, en utilisant la CLI de l’Agent 365. Microsoft Entra et Graph fournissent l’identité de l’agent, les permissions et le blueprint, tandis qu’AWS Elastic Beanstalk fournit l’exécution.

Si vous souhaitez orienter votre agent vers votre code situé derrière un terminal AWS, il vous suffit de l’étape suivante : configurez pour un hébergement non-Azure. Ensuite, suivez toutes les autres étapes du cycle de vie de développement de l’Agent 365.

Objectifs

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

  • Déploiement de l’exécution de l’agent sur AWS Elastic Beanstalk
  • Configure a365.config.json for non-Azure hosting
  • Créer un plan d’agent dans Entra ID
  • Configurer OAuth2 + permissions héréditaires
  • Enregistrer le point de messagerie du Bot Framework pointant vers AWS
  • Créer une identité d’agent + Utilisateur d’agent
  • (Optionnel) Publier sur Microsoft 365 App Surfaces
  • Interactions de test de bout en bout

Prerequisites

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

Azure / Microsoft 365 prerequisites

Confirmez l’accès à votre locataire Microsoft Entra et installez les outils suivants pour créer des identités, des plans et enregistrer votre agent.

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 environnementaux de développement local

Installez et configurez localement les outils suivants pour construire, exécuter et déployer l’agent.

Créer et déployer un agent .NET

Les instructions suivantes décrivent comment créer un agent minimal qui :

  • Répond à GET /
  • Accepte les activités du cadre Bot 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 dépôt d’échantillons Agent365 et allez dans l’échantillon dotnet\semantic-kernel\sample-agent .

L’Agent d’exemple du noyau sémantique - exemple C#/.NET comprend :

  • Une API Web de base minimale ASP.NET
  • Gestionnaire de messages du Bot Framework à /api/messages
  • Endpoint de vérification de santé à /
  • Intégration du noyau sémantique pour les capacités de l’IA

Allez sur dotnet\semantic-kernel\sample-agent et vérifiez que le projet se construit avec succès :

dotnet restore
dotnet build

Configurer le modèle

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

Tester localement (optionnel)

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

    # Run the application
dotnet run

  2. Testez les points d’extrémité dans un autre terminal :

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

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

Générer et déployer

Choisissez l’option que vous préférez pour construire et déployez cette application exemple :

Option A : Construire et déployer depuis Visual Studio

Utilisez le AWS Toolkit for Visual Studio pour publier l’application sur Elastic Beanstalk en utilisant un assistant guidé.

  1. Dans l’Explorateur de solutions, faites un clic droit sur votre projet.

  2. Sélectionnez Publier sur AWS Elastic Beanstalk.

  3. Suivez l’assistant de déploiement des haricots magnétiques :

    • Choisissez votre profil d’identifiants AWS.
    • Sélectionnez la région (par exemple, us-east-1).
    • Sélectionner la plateforme (.NET Core on Linux).
    • Configurez les paramètres de l’environnement.

  4. Sélectionnez Déployer.

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

Option B : Construire et déployer sur AWS Elastic Beanstalk avec CLI

Utilisez la ligne de ligne Elastic Beanstalk pour empaqueter et déployer l’agent .NET dans un environnement Amazon Linux 2 64 bits. Assurez-vous que la CLI AWS et la ligne de commande EB sont configurées. L’application se lie à la variable d’environnement PORT définie par Beanstalk.

  1. Développez 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 fichier de procédure avec le contenu suivant.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Initialiser Elastic Beanstalk pour .NET. Il vous est demandé de choisir Région et 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 (par exemple : us-east-1)

  4. Créer un package de déploiement et déployer :

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

    Cette commande :

    • Crée une application Elastic Beansham.
    • Crée un environnement avec un équilibreur de charge.
    • Déploie votre application.
    • Fournit les ressources AWS nécessaires.

  5. Une fois terminé, obtenez votre point d’extrémité Elastic Beanstalk :

    eb status

    Note ton point final. Il doit se présenter comme suit :

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

    Ce point de terminaison est utilisé messagingEndpoint par la interface de l’interface de l’Agent 365 Dev Tools.

Note

Pour les environnements de production, configurez HTTPS en ajoutant un certificat SSL/TLS dans Elastic Beanstalk. Le Bot Framework nécessite HTTPS pour les terminaux de production.

Configure for non-Azure hosting

Créez a365.config.json dans votre dossier projet Elastic Beanstalk en exécutant a365 config init:

Important

Pour l’hébergement non-Azure, définissez ces valeurs :

  • messagingEndpoint: votre URL Elastic Beanstalk avec le /api/messages chemin
  • needDeployment: false

Le a365.config.json fichier devrait ressembler à ceci :

{
  "tenantId": "YOUR_TENANT_ID",
  "subscriptionId": "YOUR_AZURE_SUBSCRIPTION_ID",
  "resourceGroup": "a365-aws-demo",
  "location": "westus",
  "environment": "prod",

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

  "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.

Terrain Meaning
messagingEndpoint Votre URL de haricots élastiques + /api/messages
"needDeployment": false Dit à CLI : « J’héberge mon propre serveur ; ne pas déployer sur Azure'
deploymentProjectPath Là où .env le stamping a lieu

Build agent 365

Après que votre code d’agent soit exécuté sur un point de terminaison AWS, suivez les étapes restantes du cycle de développement de l’Agent 365 pour configurer votre agent Agent 365.

Vérifier l’agent de bout en bout

Utilisez ces vérifications pour confirmer que votre agent hébergé AWS est joignable, reçoit les activités du Bot Framework et répond correctement sur les surfaces de l’Agent 365.

Vérifier la connectivité de la tige élastique

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

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

La demande doit renvoyer ce message :

AWS Agent is running.

Vérifiez les journaux Elastic Beanstalk pour les messages entrants du Bot Framework

Utilisez la journalisation Elastic Beanstalk pour vérifier que votre agent reçoit les activités du Bot Framework et répond correctement.

eb logs

Ou diffusez les journaux en temps réel :

eb logs --stream

Après qu’un message parvienne à votre agent, vous voyez :

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

Agent de test à partir des surfaces de l’Agent 365

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

  • Terrain de jeu des agents
  • Équipes (si publiées)
  • Agent Shell
  • Surfaces fédérées

Vous pouvez envoyer des messages et vérifier vos journaux Elastic Beans. Apprenez à tester les agents en utilisant le Microsoft Agent 365 SDK et à valider les fonctionnalités de votre agent avec l’outil de test Agents Playground.

Flux de travail du développeur

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

Développer et tester localement

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

# Automatically rebuild and restart on file changes
dotnet watch run

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

Construire 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 logs Elastic Beanstalk :

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

Vous n’avez pas besoin de recréer votre identité, votre blueprint, votre point d’accès du bot ou vos permissions.

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 agent Agent 365 sur AWS Elastic Beanstalk. Il couvre la connectivité et les contrôles de santé. Il traite également la liaison de ports, les erreurs de compilation et les problèmes de licence.

Conseil / Astuce

Le Guide de dépannage de l’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

Consultez les détails suivants :

  • Votre point final est exactement :
    http://<your-app>.elasticbeanstalk.com/api/messages
  • L’environnement de votre haricot magique élastique 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 sur les VPC.

Problèmes de santé dans les applications

Vérifiez la santé de l’environnement :

eb health --refresh

Consultez les journaux détaillés :

eb logs

Problèmes de liaison de ports

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

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

Vérifiez les erreurs de compilation en utilisant ces commandes :

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

Vérifier la version .NET :

dotnet --version
dotnet --list-sdks

Vérifiez les problèmes de boîtier :

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Échec de la cession de licence

Attribuez manuellement une licence Microsoft 365 valide, ou utilisez un chemin utilisateur non licencié si cela est supporté.

  • Last updated on