Δημιουργήστε έναν Agent 365 παράγοντα που έχει αναπτυχθεί στις Υπηρεσίες Web της Amazon (AWS)

Μάθετε πώς να δημιουργείτε, να φιλοξενείτε, να καταχωρείτε και να δημοσιεύετε έναν παράγοντα Agent 365 που εκτελείται στο AWS Elastic Beanstalk, με τη χρήση του Agent 365 CLI. Το Microsoft Entra και το Graph παρέχουν την ταυτότητα του παράγοντα, τα δικαιώματα και το πρότυπο, ενώ το AWS Elastic Beanstalk παρέχει το περιβάλλον εκτέλεσης.

Αν θέλετε να δρομολογήσετε τον παράγοντα σας στον κώδικα που βρίσκεται πίσω από ένα τελικό σημείο AWS, απαιτείται μόνο το εξής βήμα: Ρύθμιση παραμέτρων για φιλοξενία εκτός Azure. Στη συνέχεια, ακολουθήστε όλα τα υπόλοιπα βήματα από Ξεκινήστε με την ανάπτυξη του Agent 365.

Στόχοι

Μάθετε πώς να αξιοποιείτε το Agent 365 και το Microsoft 365 ως επίπεδο ελέγχου και:

  • Αναπτύξτε το περιβάλλον εκτέλεσης του παράγοντα στο AWS Elastic Beanstalk
  • Διαμορφώστε το a365.config.json για φιλοξενία εκτός Azure
  • Δημιουργία δομής προγράμματος παράγοντα στο Entra ID
  • Ρύθμιση παραμέτρων OAuth2 + κληρονομικά δικαιώματα
  • Καταχώριση του τελικού σημείου ανταλλαγής μηνυμάτων του Bot Framework που παραπέμπει στο AWS
  • Δημιουργία ταυτότητας παράγοντα και χρήστη παράγοντα
  • (Προαιρετικά) Δημοσίευση σε επιφάνειες εφαρμογών Microsoft 365
  • Δοκιμή ολοκληρωμένων αλληλεπιδράσεων

Προαπαιτούμενα στοιχεία

Πριν ξεκινήσετε, βεβαιωθείτε ότι πληρούνται οι ακόλουθες προϋποθέσεις Azure / Microsoft 365, AWS και τοπικού περιβάλλοντος.

Προαπαιτούμενα για το Azure / Microsoft 365

Βεβαιωθείτε ότι έχετε πρόσβαση στον μισθωτή Microsoft Entra και εγκαταστήστε τα ακόλουθα εργαλεία για να δημιουργήσετε ταυτότητες, δομές προγράμματος και να καταχωρίσετε τον παράγοντα σας.

Προαπαιτούμενα για Υπηρεσίες Web της Amazon (AWS)

Βεβαιωθείτε ότι έχουν ρυθμιστεί οι ακόλουθες υπηρεσίες και εργαλεία του AWS για την ανάπτυξη και τη διαχείριση του περιβάλλοντος Elastic Beanstalk.

Προαπαιτούμενα για τοπικό περιβάλλον ανάπτυξης

Εγκαταστήστε και ρυθμίστε τις παραμέτρους των παρακάτω εργαλείων τοπικά για να δημιουργήσετε, να εκτελέσετε και να αναπτύξετε τον παράγοντα.

Δημιουργία και ανάπτυξη ενός παράγοντα .NET

Οι παρακάτω οδηγίες περιγράφουν πώς να δημιουργήσετε έναν ελάχιστο παράγοντα που:

  • Απαντά στο GET /
  • Δέχεται δραστηριότητες Bot Framework στο POST /api/messages

Δημιουργήστε κατάλογο έργου

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

Αρχικοποιήστε το έργο .NET

Για να διευκολύνουμε την εμπειρία σας, αυτό το άρθρο χρησιμοποιεί ένα δείγμα που είναι ήδη έτοιμο. Κλωνοποιήστε το αποθετήριο δειγμάτων Agent365 και μεταβείτε στο δείγμα dotnet\semantic-kernel\sample-agent.

Το δείγμα Semantic Kernel Sample Agent - C#/.NET περιλαμβάνει:

  • Ένα minimal ASP.NET Core Web API
  • Χειριστής μηνυμάτων Bot Framework στο /api/messages
  • Σημείο ελέγχου λειτουργίας στο /
  • Ενσωμάτωση του Semantic Kernel για δυνατότητες τεχνητής νοημοσύνης

Μεταβείτε στο dotnet\semantic-kernel\sample-agent και επαληθεύστε ότι το έργο έχει δομηθεί με επιτυχία:

dotnet restore
dotnet build

Ρύθμιση παραμέτρων μοντέλου

Ακολουθήστε τις οδηγίες στο Βήμα 2: Διαμόρφωση LLM για να ρυθμίσετε το έργο χρησιμοποιώντας το κλειδί Open API σας.

Δοκιμάστε τοπικά (προαιρετικά)

  1. Πριν από την ανάπτυξη στο AWS, δοκιμάστε τον παράγοντα σας τοπικά:

    # Run the application
dotnet run

  2. Δοκιμάστε τα τελικά σημεία σε άλλο τερματικό:

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

  3. Πατήστε Ctrl+C για να διακόψετε τον τοπικό διακομιστή.

Δημιουργία και ανάπτυξη

Επιλέξτε την επιλογή που προτιμάτε για τη δημιουργία και την ανάπτυξη αυτού του δείγματος εφαρμογής:

Επιλογή Α: Κατασκευή και ανάπτυξη από το Visual Studio

Χρησιμοποιήστε το AWS Toolkit για το Visual Studio για να δημοσιεύσετε την εφαρμογή στο Elastic Beanstalk μέσω ενός καθοδηγούμενου οδηγού.

  1. Στην Εξερεύνηση λύσεων, κάντε δεξί κλικ στο έργο σας.

  2. Επιλέξτε Δημοσίευση στο AWS Elastic Beanstalk.

  3. Ακολουθήστε τον Οδηγό ανάπτυξης Beanstalk:

    • Επιλέξτε το προφίλ διαπιστευτηρίων AWS.
    • Επιλέξτε περιοχή (για παράδειγμα, us-east-1).
    • Επιλέξτε Πλατφόρμα (.NET Core on Linux).
    • Ρυθμίστε τις παραμέτρους του περιβάλλοντος.

  4. Επιλέξτε Ανάπτυξη.

Ο οδηγός δημιουργεί, συσκευάζει και αναπτύσσει την εφαρμογή σας στο AWS.

Επιλογή Β: Δημιουργία και ανάπτυξη σε AWS Elastic Beanstalk με CLI

Χρησιμοποιήστε το Elastic Beanstalk CLI για να συσκευάσετε και να αναπτύξετε τον παράγοντα .NET σε περιβάλλον Amazon Linux 2 64-bit. Βεβαιωθείτε ότι το AWS CLI και το EB CLI είναι ρυθμισμένα. Η εφαρμογή δεσμεύεται από τη μεταβλητή περιβάλλοντος PORT που ορίζεται από το Beanstalk.

  1. Κατασκευάστε και δημοσιεύστε την εφαρμογή .NET σας:

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

    Δημιουργήστε το αρχείο Procfile με το ακόλουθο περιεχόμενο.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Αρχικοποιήστε το Elastic Beanstalk για .NET. Θα σας ζητηθεί να επιλέξετε Περιοχή και Πλατφόρμα:

    eb init

  3. Επιλογή:

    • Πλατφόρμα: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Περιοχή: Η προτιμώμενη περιοχή AWS (για παράδειγμα: us-east-1)

  4. Δημιουργήστε ένα πακέτο εγκατάστασης και αναπτύξτε:

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

    Αυτή η εντολή:

    • Δημιουργεί μια εφαρμογή Elastic Beanstalk.
    • Δημιουργεί ένα περιβάλλον με εξισορροπητή φορτίου.
    • Αναπτύσσει την εφαρμογή σας.
    • Προετοιμάζει τους απαραίτητους πόρους AWS.

  5. Όταν τελειώσετε, λάβετε το τελικό σημείο του Elastic Beanstalk:

    eb status

    Σημειώστε το τελικό σας σημείο. Θα πρέπει να μοιάζει περίπου έτσι:

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

    Αυτό το τελικό σημείο είναι το messagingEndpoint που χρησιμοποιείται από το Agent 365 Dev Tools CLI.

Σημείωμα

Για περιβάλλοντα παραγωγής, ρυθμίστε το HTTPS προσθέτοντας ένα πιστοποιητικό SSL/TLS στο Elastic Beanstalk. Το Bot Framework απαιτεί HTTPS για τα τελικά σημεία παραγωγής.

Ρύθμιση παραμέτρων για φιλοξενία εκτός Azure

Δημιουργήστε το a365.config.json χειροκίνητα στον φάκελο του έργου Elastic Beanstalk σας:

Σημαντικό

Για φιλοξενία εκτός Azure, ορίστε την τιμή messagingEndpoint στη διεύθυνση URL του Elastic Beanstalk με τη διαδρομή /api/messages.

Το αρχείο a365.config.json θα πρέπει να μοιάζει κάπως έτσι:

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

Ο παρακάτω πίνακας συνοψίζει σημαντικά πεδία ρύθμισης παραμέτρων και τον σκοπό τους.

Πεδίο Νόημα
messagingEndpoint Η διεύθυνση URL του Elastic Beanstalk + /api/messages
deploymentProjectPath Πού .env γίνεται η σφράγιση

Κατασκευάστε τον παράγοντα Agent 365

Αφού εκτελεστεί ο κώδικας του παράγοντα σας σε ένα τελικό σημείο της AWS, ακολουθήστε τα υπόλοιπα βήματα από το Ξεκινήστε με την ανάπτυξη του Agent 365 για να ρυθμίσετε τον παράγοντα Agent 365.

Επαλήθευση του ολοκληρωμένου παράγοντα

Χρησιμοποιήστε αυτούς τους ελέγχους για να επιβεβαιώσετε ότι ο παράγοντας που φιλοξενείται στο AWS είναι προσβάσιμος, λαμβάνει δραστηριότητες Bot Framework και ανταποκρίνεται σωστά σε όλες τις επιφάνειες του Agent 365.

Επαληθεύστε τη συνδεσιμότητα Elastic Beanstalk

Στείλτε ένα αίτημα GET στο τελικό σημείο του Elastic Beanstalk.

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

Το αίτημα θα επιστρέψει το εξής μήνυμα:

AWS Agent is running.

Ελέγξτε τα αρχεία καταγραφής του Elastic Beanstalk για εισερχόμενα μηνύματα Bot Framework

Χρησιμοποιήστε τα αρχεία καταγραφής του Elastic Beanstalk για να επαληθεύσετε ότι ο παράγοντας λαμβάνει δραστηριότητες Bot Framework και ανταποκρίνεται σωστά.

eb logs

Ή παρακολουθήστε τα αρχεία καταγραφής σε πραγματικό χρόνο:

eb logs --stream

Αφού λάβει ο παράγοντας σας ένα μήνυμα, θα δείτε τα εξής:

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

Δοκιμάστε τον παράγοντα από τις επιφάνειες του Agent 365

Ανάλογα με το περιβάλλον σας, μπορείτε να δοκιμάσετε τον παράγοντα σας από διαφορετικές επιφάνειες:

  • Agents Playground
  • Teams (εάν έχει δημοσιευτεί)
  • Παράγοντας Shell
  • Ομοσπονδιακές επιφάνειες

Μπορείτε να στείλετε μηνύματα και να επαληθεύσετε τα αρχεία καταγραφής Elastic Beanstalk. Μάθετε πώς να δοκιμάζετε παράγοντες χρησιμοποιώντας το Microsoft Agent 365 SDK και να επαληθεύετε τη λειτουργικότητα του παράγοντα σας με το εργαλείο δοκιμών Agents Playground.

Ροή εργασίας προγραμματιστή

Μόλις ολοκληρωθεί η ρύθμιση, ακολουθήστε αυτήν τη ροή εργασίας για επαναληπτική ανάπτυξη:

Αναπτύξτε και δοκιμάστε τοπικά

Χρησιμοποιήστε τη λειτουργία παρακολούθησης για ταχεία ανάπτυξη με αυτόματη επαναφόρτωση:

# Automatically rebuild and restart on file changes
dotnet watch run

Κάντε αλλαγές στον κώδικά σας, αποθηκεύστε και δοκιμάστε τοπικά πριν από την ανάπτυξη.

Δημιουργία και εκ νέου ανάπτυξη στο AWS Elastic Beanstalk

Όταν είστε έτοιμοι να αναπτύξετε τις αλλαγές σας:

# 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

Έλεγχος και παρακολούθηση

Δοκιμάστε χρησιμοποιώντας τις επιφάνειες του Agent 365 και παρακολουθήστε τα αρχεία καταγραφής του Elastic Beanstalk:

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

Δεν χρειάζεται να δημιουργήσετε ξανά την ταυτότητα, τη δομή προγράμματος, το τελικό σημείο του bot ή τα δικαιώματά σας.

Αντιμετώπιση προβλημάτων

Χρησιμοποιήστε αυτήν την ενότητα για να διαγνώσετε και να επιλύσετε κοινά προβλήματα κατά την ανάπτυξη και την εκτέλεση ενός παράγοντα Agent 365 στο AWS Elastic Beanstalk. Καλύπτει τη συνδεσιμότητα και τους ελέγχους λειτουργίας. Αντιμετωπίζει επίσης τη δέσμευση θυρών, σφάλματα δομής και προβλήματα αδειοδότησης.

Φιλοδώρημα

Ο Οδηγός αντιμετώπισης προβλημάτων του Agent 365 περιλαμβάνει συστάσεις αντιμετώπισης προβλημάτων υψηλού επιπέδου, βέλτιστες πρακτικές και συνδέσμους για περιεχόμενο αντιμετώπισης προβλημάτων για κάθε μέρος του κύκλου ζωής ανάπτυξης του Agent 365.

Το τελικό σημείο ανταλλαγής μηνυμάτων δεν λαμβάνει αιτήματα

Ελέγξτε τα παρακάτω στοιχεία:

  • Το τελικό σας σημείο είναι ακριβώς:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Το περιβάλλον του Elastic Beanstalk είναι σε καλή κατάσταση. Χρησιμοποιήστε τον έλεγχο με eb health.
  • Η ομάδα ασφαλείας σας επιτρέπει την εισερχόμενη κίνηση HTTP ή HTTPS.
  • Δεν υπάρχουν κανόνες τείχους προστασίας ή περιορισμοί VPC.

Προβλήματα υγείας εφαρμογών

Ελέγξτε την υγεία του περιβάλλοντος:

eb health --refresh

Προβολή λεπτομερών αρχείων καταγραφής:

eb logs

Προβλήματα σύνδεσης θύρας

Βεβαιωθείτε ότι η εφαρμογή σας ακούει στη θύρα που καθορίζεται από τη μεταβλητή περιβάλλοντος PORT. Το Elastic Beanstalk ορίζει αυτόματα αυτήν την τιμή.

Προβλήματα κατασκευής ή χρόνου εκτέλεσης .NET

Ελέγξτε για σφάλματα δόμησης χρησιμοποιώντας τις παρακάτω εντολές:

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

Επαληθεύστε την έκδοση .NET:

dotnet --version
dotnet --list-sdks

Ελέγξτε για προβλήματα πακέτων:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Η ανάθεση άδειας χρήσης απέτυχε

Αναθέστε χειροκίνητα μια έγκυρη άδεια χρήσης Microsoft 365 ή επιλέξτε διαδρομή χωρίς άδεια χρήσης, εφόσον υποστηρίζεται.

  • Last updated on