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.

Ici, vous pouvez apprendre à construire, héberger, enregistrer et publier un agent Agent 365 fonctionnant sur AWS Elastic Beanstalk, en utilisant la CLI d’Agent 365. Microsoft Entra & Graph fournit l’identité de l’agent, les permissions et le blueprint, tandis qu’AWS Elastic Beanstalk fournit l’exécution.

Si tout ce que vous voulez faire est de diriger votre agent vers votre code situé derrière un terminau AWS, il suffit de cette étape : configurez pour un hébergement non-Azure , puis suivez toutes les autres étapes du cycle 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, nous utilisons un échantillon déjà préparé. Clonez le dépôt d’échantillons Agent365 et naviguez vers 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

Naviguez vers dotnet\semantic-kernel\sample-agent et vérifiez que les constructions du projet sont réussies :

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 la boîte à outils AWS pour Visual Studio afin de publier l’application sur Elastic Beanstalk avec un assistant guidé.

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

  2. Sélectionner Publier sur AWS Elastic Beanstalk

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

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

  4. Sélectionner Déploiement

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 commande Elastic Beanstalk pour empaqueter et déployer l’agent .NET dans un environnement Amazon Linux 2 64 bits ; assurez-vous que la ligne de contrôle AWS/EB est configurée et que 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éer un fichier de procédure avec le contenu ci-dessous

    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

    Cela va :

    • Créer une application Elastic Beanstalk
    • Créez un environnement avec un équilibreur de charge
    • Déployer votre application
    • Fournir 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

    C’est l’utilisation messagingEndpoint de la CLI des outils de développement Agent 365.

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 un hébergement non-Azure, vous devez :

  • Définir messagingEndpoint sur votre URL Elastic Beanstalk (avec /api/messages chemin)
  • Définir sur needDeploymentfalse

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

Une fois que votre code d’agent s’exécute sur un terminal 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 ait été envoyé à votre agent, vous verrez :

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

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

Selon votre environnement :

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

Vous pouvez désormais 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

Tester via les surfaces Agent 365 et surveiller les logs de haricots élastiques :

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

Votre identité, votre blueprint, votre point de terminaison du bot et vos permissions N’ONT PAS BESOIN d’être recréés.

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.

Terminaison de messagerie qui ne reçoit pas les 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 le chèque avec eb health
  • Votre groupe de sécurité permet le trafic HTTP/HTTPS entrant
  • Il n’y a pas de règles de pare-feu ni de restrictions VPC

Problèmes de santé de l’application

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 règle cela automatiquement).

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

Vérifiez les erreurs de compilation avec 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 liés au colis :

# 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é.

Obtenir de l’aide

Plus d’options d’aide

Considérez les points suivants pour obtenir de l’aide :

  • Last updated on