Δοκιμάστε παράγοντες με χρήση του Microsoft Agent 365 SDK

Πριν από την ανάπτυξη, δοκιμάστε τον παράγοντας σας τοπικά χρησιμοποιώντας το Agents Playground. Αυτός ο οδηγός καλύπτει τη ρύθμιση του περιβάλλοντος ανάπτυξης, τη διαμόρφωση του ελέγχου ταυτότητας και την επικύρωση της λειτουργικότητας του παράγοντα σας χρησιμοποιώντας το εργαλείο δοκιμής Agents Playground.

Αφού ο παράγοντας σας λειτουργεί τοπικά, ακολουθήστε το Agent 365 Development Lifecycle για να δοκιμάσετε σε εφαρμογές Microsoft 365 όπως Teams, Word και Outlook.

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

Προτού αρχίσετε να δοκιμάζετε τον παράγοντά σας, βεβαιωθείτε ότι είναι εγκατεστημένες οι εξής προϋποθέσεις:

Κοινά προαπαιτούμενα

Προαπαιτούμενα ανά γλώσσα προγραμματισμού

Διαμόρφωση περιβάλλοντος δοκιμής παράγοντα

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

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

  1. Διαμορφώστε το περιβάλλον σας: - Δημιουργήστε ή ενημερώστε το αρχείο διαμόρφωσης του περιβάλλοντός σας.

  2. Διαμόρφωση LLM - Λάβετε κλειδιά API και διαμορφώστε τις ρυθμίσεις OpenAI ή Azure OpenAI.

  3. Διαμόρφωση ελέγχου ταυτότητας - Ρύθμιση παραγοντικής ταυτοποίησης.

  4. Αναφορά μεταβλητών περιβάλλοντος - Ρύθμιση απαιτούμενων μεταβλητών περιβάλλοντος:

    1. Μεταβλητές ελέγχου ταυτότητας
    2. Διαμόρφωση τελικού σημείου MCP
    3. Μεταβλητές παρατηρησιμότητας
    4. Διαμόρφωση διακομιστή εφαρμογών φορέα

Αφού ολοκληρώσετε αυτά τα βήματα, είστε έτοιμοι να ξεκινήσετε τη δοκιμή του παράγοντα σας στο Agents Playground.

Βήμα 1: Ρύθμιση παραμέτρων του περιβάλλοντός σας

Ρυθμίστε το αρχείο διαμόρφωσης:

cp .env.template .env

Σημείωμα

Για πρότυπα διαμόρφωσης που εμφανίζουν τα απαιτούμενα πεδία, ανατρέξτε στα δείγματα Microsoft Agent 365 SDK.

Βήμα 2: Ρύθμιση παραμέτρων του LLM

Διαμορφώστε τις ρυθμίσεις OpenAI ή Azure OpenAI για τοπικές δοκιμές. Προσθέστε τα κλειδιά API και τα τελικά σημεία υπηρεσίας από τα προαπαιτούμενα στο αρχείο διαμόρφωσης μαζί με τυχόν παραμέτρους μοντέλου.

Προσθήκη στο δικό σας αρχείο .env:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Μεταβλητές περιβάλλοντος LLM Python

Μεταβλητή Περιγραφή Υποχρεωτικό Παράδειγμα
OPENAI_API_KEY Κλειδί API για την υπηρεσία OpenAI Για OpenAI sk-proj-...
AZURE_OPENAI_API_KEY API key για υπηρεσία Azure OpenAI Για Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Διεύθυνση URL τελικού σημείου υπηρεσίας Azure OpenAI Για Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Όνομα ανάπτυξης στο Azure OpenAI Για Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Έκδοση API για Azure OpenAI Για Azure OpenAI 2024-02-15-preview

Βήμα 3: Ρύθμιση παραμέτρων ελέγχου ταυτότητας για τον παράγοντά σας

Επιλέξτε μία από τις ακόλουθες μεθόδους ελέγχου ταυτότητας για τον παράγοντά σας:

Έλεγχος ταυτότητας Agentic

Ανοίξτε a365.generated.config.json τον κατάλογο εργασίας σας για να ανακτήσετε τα διαπιστευτήρια της δομής προγράμματος του παράγοντά σας. Αντιγράψτε τις ακόλουθες τιμές:

Τιμή Περιγραφή
agentBlueprintId Το client ID του παράγοντα σας
agentBlueprintClientSecret Ο μυστικός κωδικός προγράμματος-πελάτη του παράγοντά σας
tenantId Το αναγνωριστικό μισθωτή Microsoft Entra

Χρησιμοποιήστε αυτές τις τιμές για να διαμορφώσετε το agentic authentication στον παράγοντά σας:

Προσθέστε τις ακόλουθες ρυθμίσεις στο αρχείο .env, αντικαθιστώντας τις τιμές υποκατάστασης με τα πραγματικά σας διαπιστευτήρια:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Μεταβλητή Περιγραφή Υποχρεωτικό Παράδειγμα
USE_AGENTIC_AUTH Ενεργοποιήστε τη λειτουργία ελέγχου ταυτότητας παράγοντα Όχι true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Αναγνωριστικό προγράμματος-πελάτη δομής προγράμματος παράγοντα από a365.generated.config.json Όχι 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Μυστικός κωδικός προγράμματος-πελάτη δομής προγράμματος παράγοντα από a365.generated.config.json Όχι abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Αναγνωριστικό μισθωτή Microsoft Entra από a365.generated.config.json Όχι 22223333-cccc-4444-dddd-5555eeee6666

Έλεγχος ταυτότητας OBO

Χρησιμοποιώντας έλεγχο ταυτότητας On-Behalf-Of (OBO), ο παράγοντας σας μπορεί να έχει πρόσβαση στα εργαλεία διακομιστή MCP χρησιμοποιώντας δικαιώματα χρήστη με ανάθεση, χωρίς να απαιτείται ταυτότητα χρήστη παράγοντα. Σε αυτή τη ροή, ο παράγοντας λαμβάνει το διακριτικό ανάθεσης του χρήστη και το ανταλλάσσει για να πραγματοποιήσει ενέργειες εκ μέρους του χρήστη.

Η ταυτοποίηση OBO είναι κατάλληλη για σενάρια παραγωγής όπου:

  • Ο παράγοντας σας δεν διαθέτει ταυτότητα χρήστη παράγοντα.
  • Χρειάζεστε πρόσβαση σε πόρους με δικαιώματα ειδικά για τον χρήστη.
  • Θέλετε ο παράγοντας να ενεργεί εκ μέρους του επαληθευμένου χρήστη.

Για λεπτομέρειες σχετικά με τον τρόπο λειτουργίας της ροής OBO, ανατρέξτε στις Ροές ελέγχου ταυτότητας. Για ένα πλήρες παράδειγμα υλοποίησης, ανατρέξτε στο δείγμα εξουσιοδότησης OBO στο SDK παραγόντων Microsoft 365.

Έλεγχος ταυτότητας διακριτικού φορέα

Για σενάρια πρώιμης ανάπτυξης και δοκιμών, όταν δεν έχει ρυθμιστεί ο έλεγχος ταυτότητας παραγωγής, χρησιμοποιήστε τον έλεγχο ταυτότητας διακριτικού φορέα για να δοκιμάσετε τον παράγοντα σας. Αυτή η μέθοδος χρησιμοποιεί αλληλεπιδραστικό έλεγχο ταυτότητας προγράμματος περιήγησης για τη λήψη διακριτικού πρόσβασης με ανάθεση. Χρησιμοποιώντας αυτό το διακριτικό, ο παράγοντας σας μπορεί να καλέσει τα εργαλεία διακομιστή MCP χρησιμοποιώντας τα δικαιώματα χρήστη σας. Αυτή η προσέγγιση προσομοιώνει τον τρόπο με τον οποίο ένας χρήστης παράγοντα αποκτά πρόσβαση σε πόρους στην παραγωγή χωρίς να απαιτείται πραγματική παρουσία παράγοντα.

Πρώτα, χρησιμοποιήστε a365 develop add-permissions για να προσθέσετε τα απαιτούμενα δικαιώματα διακομιστή MCP στην εφαρμογή σας:

a365 develop add-permissions

Έπειτα, χρησιμοποιήστε το a365 develop get-token για να αποκτήσετε και να ρυθμίσετε διακριτικά φορέα:

a365 develop get-token

Η εντολή get-token εκτελεί αυτόματα:

  • Διαβάζει ToolingManifest.json για να ανακαλύψει όλους τους διαμορφωμένους διακομιστές MCP.
  • Αποκτά ένα token για κάθε audience – οι MCP διακομιστές (ανά διακομιστή) λαμβάνουν ένα token που περιορίζεται στο δικό τους αναγνωριστικό εφαρμογής, ενώ οι shared ATG servers λαμβάνουν ένα token που περιορίζεται στο κοινό αναγνωριστικό εφαρμογής του Gateway εργαλείων παράγοντα (Agent Tools Gateway) ea9ffc3e-8a23-4a7d-836d-234d7c7565c1.
  • Γράφει διακριτικά στα αρχεία ρύθμισης του έργου σας:
    • Διακριτικά ανά διακομιστή: BEARER_TOKEN_<SERVER_NAME> (για παράδειγμα, BEARER_TOKEN_MCP_MAILTOOLS)
    • Κοινόχρηστο διακριτικό ATG: BEARER_TOKEN

Πριν από την εκτέλεση get-token, προσθέστε καταχωρήσεις κράτησης θέσης στο αρχείο διαμόρφωσης του έργου σας:

  • .NET: Προσθέστε "BEARER_TOKEN": "" και/ή "BEARER_TOKEN_<SERVER_NAME>": "" σε environmentVariables σε κάθε προφίλ στο Properties/launchSettings.json. Η εντολή ενημερώνει μόνο τα προφίλ που έχουν ήδη τα συγκεκριμένα κλειδιά.
  • Python/Node.js: Δημιουργήστε ένα αρχείο .env με BEARER_TOKEN= και/ή BEARER_TOKEN_<SERVER_NAME>= πριν την εκτέλεση. Εάν το αρχείο λείπει, η εντολή παραλείπει την αποθήκευση και εμφανίζει οδηγίες.

Σημείωμα

Εάν εκτελείτε a365 develop get-token --app-id <id> χωρίς a365.config.json αρχείο, τα διακριτικά δεν αποθηκεύονται αυτόματα. Αντιγράψτε και επικολλήστε τα χειροκίνητα στο Properties/launchSettings.json (για .NET) ή στο αρχείο .env (για Python/Node.js).

Τα διακριτικά Bearer λήγουν μετά από περίπου μία ώρα. Χρησιμοποιήστε το a365 develop get-token για να ανανεώσετε τα διακριτικά που έχουν λήξει.

Βήμα 4: Αναφορά μεταβλητών περιβάλλοντος

Ολοκληρώστε τη ρύθμιση του περιβάλλοντός σας ρυθμίζοντας τις παραμέτρους των ακόλουθων απαιτούμενων μεταβλητών περιβάλλοντος:

Μεταβλητές ελέγχου ταυτότητας

Διαμορφώστε τις ρυθμίσεις του χειριστή ελέγχου ταυτότητας που απαιτούνται για να λειτουργεί σωστά ο παραγοντικός έλεγχος ταυτότητας.

Προσθήκη στο δικό σας αρχείο .env:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Μεταβλητή Περιγραφή Υποχρεωτικό
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Τύπος χειριστή ελέγχου ταυτότητας Όχι
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Δικαιώματα ελέγχου ταυτότητας για το Microsoft Graph Όχι
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Εναλλακτικό όνομα σύνδεσης blueprint Όχι
CONNECTIONSMAP_0_SERVICEURL Πρότυπο διεύθυνσης URL υπηρεσίας για αντιστοίχιση σύνδεσης Όχι
CONNECTIONSMAP_0_CONNECTION Όνομα σύνδεσης για αντιστοίχιση Όχι

Μεταβλητές διακριτικού φορέα (μόνο τοπική ανάπτυξη)

Μεταβλητή Περιγραφή Υποχρεωτικό
BEARER_TOKEN Κοινόχρηστο διακριτικό φορέα για κοινόχρηστους διακομιστές ATG MCP. Η εντολή a365 develop get-token γράφει αυτόματα αυτό το διακριτικό. Για κοινόχρηστο τοπικό προγραμματιστή ATG
BEARER_TOKEN_<SERVER_NAME> Διακριτικό φορέα ανά διακομιστή. Το SDK παράγει το όνομα με κεφαλαία mcpServerName από ToolingManifest.json (για παράδειγμα, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). Η εντολή a365 develop get-token γράφει αυτόματα αυτό το διακριτικό. Για τοπική ανάπτυξη ανά διακομιστή
SKIP_TOOLING_ON_ERRORS Ρυθμίστε το σε true ώστε να χρησιμοποιηθεί το απλό LLM εάν τα εργαλεία MCP αποτύχουν να φορτωθούν. Ισχύει μόνο όταν ASPNETCORE_ENVIRONMENT ή ENVIRONMENT είναι Development. Όχι

Σημαντικό

Τα διακριτικά φορέα προορίζονται μόνο για τοπική ανάπτυξη. Ποτέ μην ορίζετε BEARER_TOKEN ή BEARER_TOKEN_<SERVER_NAME> σε αναπτύξεις παραγωγής.

Διαμόρφωση τελικού σημείου MCP

Καθορίστε το τελικό σημείο της πλατφόρμας Agent 365 με το οποίο συνδέεται ο παράγοντας σας. Όταν δημιουργείτε τη διακήρυξη εργαλείων που ορίζει τους διακομιστές εργαλείων για τον παράγοντά σας, καθορίστε το τελικό σημείο πλατφόρμας MCP. Αυτό το τελικό σημείο καθορίζει σε ποιο περιβάλλον (προπαραγωγής, δοκιμών ή παραγωγής) συνδέονται οι διακομιστές εργαλείων MCP για δυνατότητες ενοποίησης του Microsoft 365.

Προσθήκη στο δικό σας αρχείο .env:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Μεταβλητή Περιγραφή Απαραίτητο Προεπιλογή Παράδειγμα
MCP_PLATFORM_ENDPOINT Διεύθυνση URL τελικού σημείου πλατφόρμας MCP (preprod, test ή prod) Όχι Τελικό σημείο παραγωγής

Σημαντικό: Εάν δεν καθορίσετε MCP_PLATFORM_ENDPOINT, η εφαρμογή χρησιμοποιεί το τελικό σημείο παραγωγής.

Σημείωμα

Εάν χρησιμοποιείτε τον προσομοιωμένο διακομιστή εργαλείων από το CLI, ορίστε το τελικό σημείο σε http://localhost:<port> χρησιμοποιώντας τον αριθμό θύρας που χρησιμοποιήσατε. Η προεπιλεγμένη θύρα είναι 5309.

Μεταβλητές παρατηρησιμότητας

Διαμορφώστε αυτές τις απαιτούμενες μεταβλητές για να ενεργοποιήσετε την καταγραφή και την κατανεμημένη ανίχνευση για τον παράγοντά σας. Για την πλήρη λίστα των μεταβλητών περιβάλλοντος, των επιλογών ρύθμισης παραμέτρων και των παραδειγμάτων κώδικα, δείτε την ενότητα Παρατηρησιμότητα παράγοντα.

Σημείωμα

Η διαμόρφωση παρατηρησιμότητας είναι η ίδια σε όλες τις γλώσσες. Δείτε Ρύθμιση για λεπτομέρειες.

Μεταβλητή Περιγραφή Προεπιλογή Παράδειγμα
ENABLE_A365_OBSERVABILITY_EXPORTER Εξαγωγή ιχνών στην υπηρεσία παρατηρησιμότητας. Όταν false , η εξαγωγή εκτείνεται στην κονσόλα. false true
A365_OBSERVABILITY_LOG_LEVEL Επίπεδο εσωτερικής καταγραφής για το SDK παρατηρησιμότητας Χρήσιμο για τον εντοπισμό προβλημάτων εξαγωγής κατά τη διάρκεια της δοκιμής. none info, warn, error, debug

Διαμόρφωση διακομιστή εφαρμογών φορέα

Ρυθμίστε τη θύρα όπου εκτελείται ο διακομιστής εφαρμογών παράγοντα. Αυτή η ρύθμιση είναι προαιρετική και εφαρμόζεται σε παράγοντες Python και JavaScript.

Προσθήκη στο δικό σας αρχείο .env:

# Server Configuration
PORT=3978
Μεταβλητή Περιγραφή Απαραίτητο Προεπιλογή Παράδειγμα
PORT Αριθμός θύρας όπου εκτελείται ο διακομιστής παράγοντα Όχι 3978 3978

Εγκαταστήστε τις εξαρτήσεις και ξεκινήστε τον διακομιστή εφαρμογής παράγοντα

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

Εγκατάσταση εξαρτήσεων

uv pip install -e .

Αυτή η εντολή διαβάζει τις εξαρτήσεις των πακέτων που ορίζονται στο pyproject.toml και τις εγκαθιστά από το PyPI. Όταν δημιουργείτε μια εφαρμογή παράγοντα από το μηδέν, δημιουργήστε ένα αρχείο pyproject.toml για να ορίσετε τις εξαρτήσεις σας. Τα δείγματα παραγόντων από το αποθετήριο δειγμάτων έχουν ήδη ορίσει αυτά τα πακέτα. Μπορείτε να τα προσθέσετε ή να τα ενημερώσετε όπως απαιτείται.

Εκκινήστε τον διακομιστή εφαρμογής παράγοντα

python <main.py>

Αντικαταστήστε το <main.py> με το όνομα του κύριου αρχείου Python που περιέχει το σημείο εισόδου για την εφαρμογή του παράγοντα σας (για παράδειγμα, start_with_generic_host.py, app.py ή main.py).

Ή χρησιμοποιήστε uv:

uv run python <main.py>

Ο διακομιστής του παράγοντα σας εκτελείται τώρα και είναι έτοιμος να δεχτεί αιτήματα από το Agents Playground ή από εφαρμογές του Microsoft 365.

Δοκιμάστε τον παράγοντα στο Agents Playground

Το Agents Playground είναι ένα τοπικό εργαλείο δοκιμών που προσομοιώνει το περιβάλλον του Microsoft 365 χωρίς να απαιτείται πλήρης ρύθμιση tenant. Είναι ο ταχύτερος τρόπος να επαληθεύσετε τη λογική του παράγοντα σας και τις επικλήσεις εργαλείων. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Δοκιμή με Agents Playground.

Ρύθμιση παραμέτρων Agents Playground για έλεγχο ταυτότητας παράγοντα

Σημείωμα

Αυτή η ρύθμιση παραμέτρων απαιτείται μόνο όταν χρησιμοποιείτε παραγοντικό έλεγχο ταυτότητας. Εάν χρησιμοποιείτε έλεγχο ταυτότητας διακριτικού φορέα, μπορείτε να παραλείψετε αυτήν την ενότητα και να προχωρήσετε απευθείας στη Βασική δοκιμή.

Όταν χρησιμοποιείτε παραγοντικό έλεγχο ταυτότητας, ρυθμίστε τις παραμέτρους του αρχείου YAML Playground Agents με τα στοιχεία του παράγοντά σας:

  1. Ρύθμιση του αρχείου ρύθμιση παραμέτρων: Δημιουργήστε ή ενημερώστε το .m365agentsplayground.ymlαρχείο στον φάκελο όπου εκτελείτε το Agents Playground. Για λεπτομερείς οδηγίες ρύθμισης, ανατρέξτε στο Προσαρμογή περιβάλλοντος Teams.

  2. Ενημερώστε τη ρύθμιση παραμέτρων του bot: Προσθέστε τις ακόλουθες λεπτομέρειες bot στο αρχείο .m365agentsplayground.yml, αντικαθιστώντας τις τιμές κράτησης θέσης με τα πραγματικά διαπιστευτήρια του παράγοντα σας:

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    Ιδιότητα Περιγραφή Υποχρεωτικό
    id Η διεύθυνση ηλεκτρονικού ταχυδρομείου του χρήστη παράγοντα σε μορφή agentusername@tenant.onmicrosoft.com Όχι
    name Εμφανιζόμενο όνομα για τον παράγοντας χρήστη σας Όχι
    role Πρέπει να οριστεί σε agenticUser για παραγοντικό έλεγχο ταυτότητας Όχι
    agenticUserId Το αναγνωριστικό αντικειμένου του χρήστη - παράγοντα. Βρείτε αυτήν την τιμή στο Κέντρο διαχείρισης Microsoft Entra στη σελίδα προφίλ του χρήστη παράγοντα. Όχι
    agenticAppId Το αναγνωριστικό παράγοντα του χρήστη-παράγοντα. Βρείτε αυτήν την τιμή στο Κέντρο διαχείρισης Microsoft Entra στη σελίδα προφίλ του χρήστη παράγοντα. Όχι

Ανοίξτε ένα νέο τερματικό (PowerShell στα Windows) και ξεκινήστε το Agents Playground:

agentsplayground

Αυτή η εντολή ανοίγει ένα πρόγραμμα περιήγησης ιστού με τη διεπαφή του Agents Playground. Το εργαλείο εμφανίζει μια διεπαφή συνομιλίας όπου μπορείτε να στείλετε μηνύματα στον παράγοντα σας.

Βασική δοκιμή

Ξεκινήστε επαληθεύοντας ότι ο παράγοντάς σας είναι σωστά ρυθμισμένος. Στείλτε ένα μήνυμα στον παράγοντα:

What can you do?

Ο παράγοντας απαντά με τις οδηγίες με τις οποίες έχει διαμορφωθεί, βάσει της προτροπής συστήματος και των δυνατοτήτων του παράγοντα σας. Αυτή η απάντηση επιβεβαιώνει ότι:

  • Ο παράγοντας σας εκτελείται σωστά.
  • Ο παράγοντας μπορεί να επεξεργαστεί μηνύματα και να απαντήσει.
  • Η επικοινωνία μεταξύ του Agents Playground και του παράγοντα σας λειτουργεί σωστά.

Δοκιμή επικλήσεων εργαλείων

Αφού διαμορφώσετε τους διακομιστές εργαλείων MCP στο toolingManifest.json (βλέπε Εργαλεία για οδηγίες εγκατάστασης), δοκιμάστε τις κλήσεις εργαλείων χρησιμοποιώντας παραδείγματα όπως αυτά τα παραδείγματα:

Αρχικά, επαληθεύστε ποια εργαλεία είναι διαθέσιμα:

List all tools I have access to

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

Κύρια εργαλεία

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Αναμενόμενη απάντηση: Ο παράγοντας στέλνει ένα email χρησιμοποιώντας τον διακομιστή MCP αλληλογραφίας και επιβεβαιώνει ότι το μήνυμα στάλθηκε.

Εργαλεία ημερολογίου

List my calendar events for today

Αναμενόμενη απάντηση: Ο παράγοντας ανακτά και εμφανίζει τα συμβάντα ημερολογίου για την τρέχουσα ημέρα.

Εργαλεία SharePoint

List all SharePoint sites I have access to

Αναμενόμενη απάντηση: Ο παράγοντας υποβάλλει ερώτημα στο SharePoint και επιστρέφει μια λίστα με ιστότοπους στους οποίους έχετε πρόσβαση.

Μπορείτε να δείτε τις ενεργοποιήσεις εργαλείων στα εξής:

  • Το παράθυρο συνομιλίας - δείτε την απάντηση του παράγοντα και οποιεσδήποτε εκτελέσεις εργαλείων.
  • Ο πίνακας καταγραφής - δείτε λεπτομερείς πληροφορίες δραστηριότητας, συμπεριλαμβανομένων των παραμέτρων και των αποκρίσεων του εργαλείου.

Δοκιμή με δραστηριότητες ειδοποίησης

Κατά τη διάρκεια της τοπικής ανάπτυξης, δοκιμάστε σενάρια ειδοποιήσεων χρησιμοποιώντας τους ενσωματωμένους μηχανισμούς ενεργοποίησης στο Agents Playground.

Στιγμιότυπο οθόνης που δείχνει τη διεπαφή του Agents Playground με το μενού Mock an Activity ανοιχτό, εμφανίζοντας τις επιλογές Trigger Notification Activity, μεταξύ των οποίων Send email και Mention in Word.

Πριν δοκιμάσετε τις δραστηριότητες ειδοποιήσεων, βεβαιωθείτε ότι:

Δοκιμή ειδοποιήσεων ηλεκτρονικού ταχυδρομείου

Για να δοκιμάσετε τον χειρισμό ειδοποιήσεων μέσω ηλεκτρονικού ταχυδρομείου:

  1. Εκκινήστε τον παράγοντα σας και το Agents Playground.
  2. Στο Agents Playground, μεταβείτε στο Απομίμηση δραστηριότητας>Ενεργοποίηση δραστηριότητα;ς ειδοποίησης.
  3. Επιλέξτε Αποστολή email.
  4. Στο παράθυρο διαλόγου ωφέλιμου φορτίου, ενημερώστε τα στοιχεία του δοκιμαστικού email, όπως το όνομα του αποστολέα και το περιεχόμενο του email, εφόσον χρειάζεται.
  5. Επιλέξτε Αποστολή δραστηριότητας.
  6. Δείτε το αποτέλεσμα τόσο στη συνομιλία όσο και στον πίνακα καταγραφής.

Ο παράγοντας λαμβάνει μια προσομοιωμένη ειδοποίηση email και τη διαχειρίζεται σύμφωνα με τον τρόπο διαχείρισης ειδοποιήσεων που έχετε ορίσει. Για λεπτομέρειες σχετικά με τη δομή ωφέλιμου φορτίου ειδοποίησης email, δείτε Ωφέλιμο φορτίο ειδοποίησης Email.

Δοκιμή ειδοποιήσεων αναφοράς σε Word

Για να δοκιμάσετε τις ειδοποιήσεις αναφοράς σε έγγραφα Word:

  1. Εκκινήστε τον παράγοντα σας και το Agents Playground.
  2. Στο Agents Playground, μεταβείτε στο Απομίμηση δραστηριότητας>Ενεργοποίηση δραστηριότητα;ς ειδοποίησης.
  3. Επιλέξτε Αναφορά στο Word.
  4. Στο παράθυρο διαλόγου payload, ενημερώστε τις λεπτομέρειες του εικονικού σχολίου, όπως το αναγνωριστικό του εγγράφου και το κείμενο του σχολίου, εφόσον χρειάζεται.
  5. Επιλέξτε Αποστολή δραστηριότητας.
  6. Δείτε το αποτέλεσμα τόσο στη συνομιλία όσο και στον πίνακα καταγραφής.

Ο παράγοντας λαμβάνει μια προσομοιωμένη ειδοποίηση αναφοράς Word και ανταποκρίνεται σύμφωνα με τη λογική χειρισμού ειδοποιήσεων σας. Για λεπτομέρειες σχετικά με τη δομή του payload ειδοποίησης σχολίου του Word, δείτε Document comment notification payload.

Δοκιμάστε τα συμβάντα εγκατάστασης και απεγκατάστασης του παράγοντα

Όταν το Agents Playground συνδέεται με τον παράγοντά σας, στέλνει αυτόματα μια InstallationUpdate δραστηριότητα με ενέργεια add. Εάν υλοποιήσετε έναν χειριστή εγκατάστασης, το μήνυμα καλωσορίσματος του παράγοντα σας εμφανίζεται στη συνομιλία αμέσως μετά τη δημιουργία της σύνδεσης.

Για να επαληθεύσετε τον χειρισμό συμβάντων εγκατάστασης:

  1. Ξεκινήστε τον διακομιστή παράγοντά σας.
  2. Ανοίξτε το Agents Playground. Το Agents Playground συνδέεται με τον παράγοντα σας και ενεργοποιεί αυτόματα το συμβάν εγκατάστασης.
  3. Επιβεβαιώστε ότι το μήνυμα καλωσορίσματος εμφανίζεται στη συνομιλία.

Στιγμιότυπο που παρουσιάζει τη διεπαφή του Agents Playground με το μήνυμα καλωσορίσματος του παράγοντα «Σας ευχαριστώ που με προσλάβατε! Ανυπομονώ να σας βοηθήσω στην επαγγελματική σας πορεία!» να εμφανίζεται στη συνομιλία και στον πίνακα καταγραφής, μετά την αυτόματη ενεργοποίηση του συμβάντος εγκατάστασης.

Για λεπτομέρειες σχετικά με την υλοποίηση του προγράμματος χειρισμού, ανατρέξτε στο Χειρισμός συμβάντων εγκατάστασης και απεγκατάστασης παράγοντα.

Προβολή αρχείων καταγραφής παρατηρησιμότητας

Για να δείτε τα αρχεία καταγραφής παρατηρησιμότητας κατά την τοπική ανάπτυξη, ενσωματώστε κώδικα παρατηρησιμότητας στον παράγοντα σας (δείτε Παρατηρησιμότητα για παραδείγματα κώδικα) και διαμορφώστε τις μεταβλητές περιβάλλοντος όπως περιγράφεται στο Μεταβλητές παρατηρησιμότητας. Για οδηγίες βήμα προς βήμα για την επικύρωση και την αναμενόμενη έξοδο των καταγραφών, δείτε Επικύρωση τοπικά. Μόλις ολοκληρωθεί η ρύθμιση, εμφανίζονται σε πραγματικό χρόνο ίχνη στην κονσόλα που δείχνουν:

  • Ίχνη ενεργοποίησης παράγοντα
  • Λεπτομέρειες εκτέλεσης εργαλείου
  • Κλήσεις συμπερασμάτων LLM
  • Μηνύματα εισόδου και εξόδου
  • Χρήση διακριτικού
  • Χρόνοι απάντησης
  • Πληροφορίες σφάλματος

Αυτά τα αρχεία καταγραφής σας βοηθούν να επιλύετε προβλήματα, να κατανοείτε τη συμπεριφορά των παραγόντων και να βελτιστοποιείτε την απόδοση. Πριν τη δημοσίευση, χρησιμοποιήστε το Επικύρωση για δημοσίευση αποθήκευσης για να επιβεβαιώσετε ότι όλα τα απαιτούμενα χαρακτηριστικά είναι παρόντα.

Επόμενα βήματα

Αφού δοκιμάσετε τον παράγοντα σας τοπικά, αναπτύξτε τον στο Azure και δημοσιεύστε τον στο Microsoft 365.

Για να δοκιμάσετε τον παράγοντά σας σε εφαρμογές του Microsoft 365, όπως το Teams, το Word και το Outlook, ανατρέξτε στον κύκλο ζωής ανάπτυξης του Agent 365.

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

Αυτή η ενότητα παρέχει λύσεις σε κοινά προβλήματα που ενδέχεται να αντιμετωπίσετε κατά τη δοκιμή του παράγοντά σας τοπικά.

Φιλοδώρημα

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

Προβλήματα συνδεσιμότητας και ρύθμισης περιβάλλοντος

Αυτά τα προβλήματα αφορούν τη συνδεσιμότητα δικτύου, τις συγκρούσεις θυρών και τα προβλήματα ρύθμισης περιβάλλοντος που εμποδίζουν τον παράγοντα σας να επικοινωνεί σωστά.

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

Σύμπτωμα: Το Agents Playground δεν μπορεί να συνδεθεί με τον παράγοντας σας.

Λύσεις:

  • Βεβαιωθείτε ότι ο διακομιστής παράγοντα σας εκτελείται.
  • Ελέγξτε ότι οι αριθμοί θυρών ταιριάζουν μεταξύ του παράγοντα σας και του Agents Playground.
  • Βεβαιωθείτε ότι δεν υπάρχουν κανόνες τείχους προστασίας που εμποδίζουν τις τοπικές συνδέσεις.
  • Δοκιμάστε να επανεκκινήσετε τόσο τον παράγοντα όσο και το Agents Playground.

Ξεπερασμένη έκδοση Agents Playground

Σύμπτωμα: Μη αναμενόμενα σφάλματα ή λειτουργίες που λείπουν στο Agents Playground.

Λύση: Απεγκαταστήστε και επανεγκαταστήστε το Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

Διενέξεις θύρας

Σύμπτωμα: Σφάλμα που υποδεικνύει ότι η θύρα χρησιμοποιείται ήδη.

Λύση:

  • Σταματήστε τυχόν άλλες εκτελέσεις του παράγοντα σας.
  • Αλλάξτε τη θύρα στη διαμόρφωσή σας.
  • Τερματίστε τυχόν διεργασίες που χρησιμοποιούν τη θύρα.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Δεν είναι δυνατή η προσθήκη του DeveloperMCPServer

Σύμπτωμα: Σφάλμα κατά την προσπάθεια προσθήκης του DeveloperMCPServer στην εφαρμογή Visual Studio Code.

Λύση: Κλείστε και ανοίξτε ξανά το Visual Studio Code και, στη συνέχεια, δοκιμάστε να προσθέσετε ξανά το διακομιστή.

Προβλήματα ελέγχου ταυτότητας και διακριτικών

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

Συμπτώματα:

  • 401 Μη εξουσιοδοτημένα σφάλματα
  • Μηνύματα "Bearer token expired"
  • Αποτυχίες παραγοντικού ελέγχου ταυτότητας

Ριζική αιτία:

  • Τα διακριτικά λήγουν μετά από περίπου μία ώρα
  • Λανθασμένη διαμόρφωση ελέγχου ταυτότητας
  • Διαπιστευτήρια που λείπουν ή δεν είναι έγκυρα

Λύσεις

  • Για τη λήξη διακριτικού φορέα

    Ανανεώστε το διακριτικό σας και ενημερώστε τις μεταβλητές περιβάλλοντος.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Για αποτυχίες διακριτικού φορέα ανά διακομιστή

    Βεβαιωθείτε ότι το αρχείο διαμόρφωσης έχει καταχωρήσεις κράτησης θέσης για κάθε διακομιστή (BEARER_TOKEN_<SERVER_NAME>) και, στη συνέχεια, εκτελέστε a365 develop get-token ξανά για να τις συμπληρώσετε. Το SDK δημιουργεί το όνομα της μεταβλητής μετατρέποντας το mcpServerName σε κεφαλαία μέσα στο ToolingManifest.json και αντικαθιστώντας τις παύλες με χαρακτήρες υπογράμμισης (για παράδειγμα, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • Για σφάλματα ελέγχου ταυτότητας (Python)

    Ελέγξτε το αρχείο .env:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • Για ελλιπή διαπιστευτήρια

    Επιβεβαιώστε ότι υπάρχουν τα απαιτούμενα διαπιστευτήρια πριν από τη δοκιμή.

    Βεβαιωθείτε ότι το .env ή το appsettings.json περιέχει:

    • Κλειδιά και μυστικοί κωδικοί API
    • Αναγνωριστικό μισθωτή
    • Αναγνωριστικό προγράμματος-πελάτη
    • Αναγνωριστικό δομής προγράμματος (εάν χρησιμοποιείτε agentic auth)

    Επαλήθευση:

    Δοκιμάστε με ένα απλό αίτημα στο Agents Playground. Θα πρέπει να λάβετε μια απάντηση χωρίς σφάλματα 401.

  • Προβλήματα εργαλείων και ειδοποιήσεων

    Αυτά τα προβλήματα περιλαμβάνουν ζητήματα με τις κλήσεις εργαλείων, τις αλληλεπιδράσεις με τον διακομιστή MCP και την παράδοση ειδοποιήσεων.

Το email δεν λήφθηκε

Σύμπτωμα: Ο παράγοντας υποδεικνύει ότι το μήνυμα ηλεκτρονικού ταχυδρομείου στάλθηκε, αλλά δεν το λάβατε

Λύσεις:

  • Ελέγξτε τον φάκελο ανεπιθύμητης αλληλογραφίας ή spam.
  • Η παράδοση του email μπορεί να καθυστερήσει μερικά λεπτά. Περιμένετε έως και πέντε λεπτά.
  • Βεβαιωθείτε ότι η διεύθυνση ηλεκτρονικού ταχυδρομείου του παραλήπτη είναι σωστή.
  • Ελέγξτε τα αρχεία καταγραφής του παράγοντα για τυχόν σφάλματα κατά την αποστολή email.

Οι απαντήσεις σε σχόλια του Word δεν λειτουργούν

Γνωστό πρόβλημα: Η υπηρεσία ειδοποιήσεων δεν μπορεί να απαντήσει απευθείας σε σχόλια του Word. Αυτή η λειτουργία βρίσκεται υπό ανάπτυξη.

Τα μηνύματα δεν φτάνουν στον παράγοντα

Σύμπτωμα: Η εφαρμογή παράγοντας σας δεν λαμβάνει μηνύματα που αποστέλλονται στον παράγοντας στο Teams.

Πιθανές αιτίες:

  • Η πύλη προγραμματιστών δεν έχει ρυθμιστεί με το πρότυπο παράγοντα.
  • Προβλήματα Azure Web App: (σφάλματα ανάπτυξης, η εφαρμογή δεν εκτελείται, σφάλματα διαμόρφωσης).
  • Η παρουσία του παράγοντα δεν δημιουργείται σωστά στο Teams.

Λύσεις:

  • Επαληθεύστε τη ρύθμιση παραμέτρων της πύλης προγραμματιστών:

    Βεβαιωθείτε ότι έχετε ολοκληρώσει τη ρύθμιση παραμέτρων δομής προγράμματος παράγοντα στην Πύλη προγραμματιστών. Μάθετε πώς να διαμορφώσετε τη δομή προγράμματος του παράγοντα στην Πύλη προγραμματιστών.

  • Ελέγξτε την κατάσταση του Azure Web App:

    Εάν αναπτύξετε τον παράγοντα σας στο Azure, ελέγξτε ότι η Web εφαρμογή εκτελείται σωστά:

    1. Μετάβαση στην πύλη Azure.
    2. Μεταβείτε στον πόρο της εφαρμογής Web.
    3. Ελέγξτε την ενότητα Επισκόπηση>Κατάσταση (θα πρέπει να εμφανίζεται η ένδειξη «Εκτέλεση»).
    4. Ελέγξτε Ροή καταγραφής υπό την ενότητα Παρακολούθηση για σφάλματα χρόνου εκτέλεσης.
    5. Ελέγξτε τα αρχεία καταγραφής του Κέντρου ανάπτυξης για να βεβαιωθείτε ότι η ανάπτυξη έχει ολοκληρωθεί με επιτυχία.
    6. Επιβεβαιώστε ότι οι Ρυθμίσεις διαμόρφωσης>Ρυθμίσεις εφαρμογής περιέχουν όλες τις απαιτούμενες μεταβλητές περιβάλλοντος.

  • Επαληθεύστε τη δημιουργία παρουσίας παράγοντα:

    Βεβαιωθείτε ότι δημιουργείτε σωστά την παρουσία του παράγοντα στο Microsoft Teams:

    1. Άνοιγμα Microsoft Teams.
    2. Μεταβείτε στις Εφαρμογές και αναζητήστε τον παράγοντα σας.
    3. Βεβαιωθείτε ότι ο παράγοντας εμφανίζεται στα αποτελέσματα αναζήτησης.
    4. Εάν δεν βρεθεί, βεβαιωθείτε ότι έχει δημοσιευτεί στο Κέντρο διαχείρισης Microsoft 365 - Παράγοντες.
    5. Δημιουργήστε μια νέα παρουσία επιλέγοντας Προσθήκη στον παράγοντά σας.
    6. Για λεπτομερείς οδηγίες, ανατρέξτε στην ενότητα Ενσωματωμένοι παράγοντες.

Αντιμετώπιση προβλημάτων στα αρχεία καταγραφής παρατηρησιμότητας

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

  • Last updated on