Επέκταση του παράγοντα με εργαλεία από ένα REST API (προεπισκόπηση)

Σημείωμα

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

[Αυτό το άρθρο αποτελεί τεκμηρίωση προέκδοσης και ενδέχεται να αλλάξει.]

Μπορείτε να χρησιμοποιήσετε τα REST API (συμπεριλαμβανομένου του OpenAI API) για να συνδέσετε έναν παράγοντα που δημιουργείτε με εξωτερικά συστήματα και να αποκτήσετε πρόσβαση σε διαθέσιμα δεδομένα για χρήση εντός του παράγοντα σας. Μπορείτε να συνδέσετε τον πράκτορά σας σε ένα API REST, παρέχοντας στο Copilot Studio τρία πράγματα:

• Μια OpenAPI προδιαγραφή που καθορίζει τις λειτουργίες και τις διαθέσιμες ενέργειες του API
• Λεπτομέρειες σχετικά με τον τύπο ελέγχου ταυτότητας που απαιτείται και τα στοιχεία ελέγχου ταυτότητας για τη σύνδεση των χρηστών στο API για πρόσβαση στο εξωτερικό σύστημα
• Περιγραφές που βοηθούν το μοντέλο γλώσσας να καθορίσει πότε πρέπει να καλέσει το API για να χρησιμοποιήσει τα δεδομένα

Μπορείτε να προσθέσετε API REST σε Copilot πράκτορες και προσαρμοσμένους πράκτορες μέσω Copilot Studio.

Σημαντικό

Αυτό το άρθρο περιέχει τεκμηρίωση προεπισκόπησης του Microsoft Copilot Studio και υπόκειται σε αλλαγές.

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

Εάν δημιουργείτε έναν agent έτοιμο για παραγωγή, ανατρέξτε στο Microsoft Copilot Studio Overview.

Copilot agents επιτρέπουν σε έναν κατασκευαστή να συνδυάζει πολλές πηγές δεδομένων, όπως connectors, APIs, εντολές και πηγές γνώσης, σε έναν μόνο agent. Χρησιμοποιήστε αυτόν τον παράγοντα για να επεκτείνετε εμπειρίες αντιπροσώπων με Microsoft επωνυμία, όπως Microsoft 365 Copilot.

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

Σημείωμα

Πρέπει να δημιουργήσετε εργαλεία REST API από μια προδιαγραφή OpenAPI v2. Αυτή η απαίτηση οφείλεται στη συμπεριφορά του Power Platform στην επεξεργασία προδιαγραφών API. Εάν υποβάλετε μια προδιαγραφή v3, η διαδικασία δημιουργίας την μεταφράζει αυτόματα σε προδιαγραφή v2.

Προϋποθέσεις

• Διαπιστευτήρια σε επίπεδο δημιουργού και άδεια χρήσης του Copilot Studio.
• Ένα αντίγραφο της προδιαγραφής OpenAPI για το REST API στο οποίο θέλετε να συνδεθείτε
• Γνώση του τύπου ελέγχου ταυτότητας που απαιτείται για τη σύνδεση στο API και των λεπτομερειών ελέγχου ταυτότητας.

Προσθέστε ένα εργαλείο API REST στον πράκτορά σας

Για να προσθέσετε ένα εργαλείο REST API στον πράκτορά σας, ακολουθήστε τα παρακάτω βήματα:

1. Προσθέστε ένα νέο εργαλείο παράγοντα και επιλέξτε REST API
2. Παρέχετε προδιαγραφές, περιγραφή και λύση API
3. Παροχή στοιχείων ελέγχου ταυτότητας
4. Επιλέξτε εργαλεία από το API
5. Έλεγχος και δημοσίευση

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

Η διαδικασία προσθήκης ενός REST API είναι ίδια τόσο για τους προσαρμοσμένους παράγοντες όσο και για τους Microsoft 365 Copilot παράγοντες.

Προσθέστε νέο εργαλείο παράγοντα και επιλέξτε REST API

1. Μεταβείτε στη σελίδα Επισκόπηση του εκπροσώπου σας.

2. Στην ενότητα Εργαλεία , επιλέξτε Προσθήκη εργαλείου. Μπορείτε επίσης να μεταβείτε στην καρτέλα Εργαλεία και να επιλέξετε Προσθήκη εργαλείου.

   Εμφανίζεται η σελίδα Προσθήκη εργαλείου .

3. Επιλέξτε Νέο εργαλείο>REST API.

Παρέχετε προδιαγραφές, περιγραφή και λύση API

1. Ανεβάστε ένα OpenAPI αρχείο προδιαγραφών για το REST API στο οποίο θέλετε να συνδεθείτε. Μπορείτε είτε να σύρετε και να αποθέσετε το αρχείο προδιαγραφών στην οθόνη Αποστολή REST API είτε να περιηγηθείτε στο σύστημά σας για να εντοπίσετε το αρχείο που θέλετε να χρησιμοποιήσετε.

   

   Σημείωμα

   Η OpenAPI προδιαγραφή πρέπει να είναι ένα αρχείο JSON σε μορφή v2. Εάν υποβάλετε μια προδιαγραφή v3, η διαδικασία δημιουργίας την μεταφράζει αυτόματα σε προδιαγραφή v2.

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

   

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

2. Επαληθεύστε τις λεπτομέρειες και, στη συνέχεια, επιλέξτε Επόμενο.

   Εμφανίζεται μια σελίδα λεπτομερειών πρόσθετου API όπου μπορείτε να παρέχετε πρόσθετες πληροφορίες σχετικά με το API.

   

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

   Για παράδειγμα, η αρχική περιγραφή που παρέχεται είναι: "Μια απλή υπηρεσία για τη διαχείριση εισιτηρίων".

   Μια καλύτερη περιγραφή είναι: "Ένα σύστημα που χρησιμοποιείται για τη λήψη, ανάκτηση, εύρεση και εμφάνιση υπαρχόντων εισιτηρίων από το SunnyADO." Επιτρέπει στους χρήστες να ενημερώνουν, να αλλάζουν και να διαχειρίζονται εισιτήρια για να παρέχουν περισσότερα δεδομένα για τη βελτίωση των αρχείων.

3. Εισαγάγετε μια βελτιωμένη περιγραφή στο πεδίο Περιγραφή.

4. Στην περιοχή Λύση, ένα αναπτυσσόμενο μενού απαριθμεί όλες τις λύσεις που είναι διαθέσιμες στο τρέχον περιβάλλον. Επιλέξτε τη λύση που θέλετε να χρησιμοποιήσετε. Μάθετε περισσότερα σχετικά με τις λύσεις στις έννοιες λύσης.

   

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

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

   Σημείωμα

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

5. Με επιλεγμένη λύση, επιλέξτε Επόμενο για να συνεχίσετε.

Παροχή στοιχείων ελέγχου ταυτότητας

Εμφανίζεται η σελίδα Έλεγχος ταυτότητας . Επιλέξτε τον τύπο ελέγχου ταυτότητας που θα χρησιμοποιηθεί για το API.

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

   • Κανένας: Δεν απαιτείται έλεγχος ταυτότητας για την πρόσβαση στο API.
   • Κλειδί API: Ενεργοποιήστε αυτήν την επιλογή εάν το API σας απαιτεί κλειδί API για έλεγχο ταυτότητας. Κατά τον χρόνο εκτέλεσης, όταν ο εκπρόσωπος θέλει να χρησιμοποιήσει το εργαλείο API, ο εκπρόσωπος ζητά από τον χρήστη να πραγματοποιήσει έλεγχο ταυτότητας. Ο χρήστης παρέχει ένα κλειδί API και ο πράκτορας συνδέεται στο API χρησιμοποιώντας αυτό το κλειδί.
   • Auth 2.0: Ενεργοποιήστε αυτήν την επιλογή εάν ο διακομιστής MCP χρησιμοποιεί OAuth 2.0 για έλεγχο ταυτότητας. Το OAuth 2.0 επιτρέπει σε μεμονωμένους χρήστες να πραγματοποιούν έλεγχο ταυτότητας στο API μέσω ενός παρόχου ταυτότητας. Αυτή η μέθοδος ελέγχου ταυτότητας επιτρέπει στον χρήστη να εκχωρήσει δικαιώματα στην εφαρμογή σας (παράγοντας) χωρίς να κοινοποιήσει τα διαπιστευτήριά του στον παράγοντα.

2. Εισαγάγετε τα απαιτούμενα πεδία για την επιλεγμένη μέθοδο πιστοποίησης. Τα πεδία ποικίλλουν ανάλογα με τη μέθοδο ελέγχου ταυτότητας.

   • Καμία: Δεν υπάρχουν πληροφορίες για παροχή.
   • Κλειδί API:
     • Ετικέτα παραμέτρου: Μια ετικέτα κειμένου για την εμφάνιση της παραμέτρου API στους χρήστες.
     • Όνομα παραμέτρου: Το πραγματικό όνομα για την παράμετρο κλειδιού API που θα χρησιμοποιηθεί είτε στην κεφαλίδα είτε στη συμβολοσειρά ερωτήματος.
     • Θέση παραμέτρου: Πώς στέλνετε το κλειδί για το API. Επιλέξτε Κεφαλίδα ή Ερώτημα.
   • Έλεγχος ταυτότητας 2.0:
     • Αναγνωριστικό προγράμματος-πελάτη: Το αναγνωριστικό προγράμματος-πελάτη που εκδίδει η υπηρεσία παροχής ταυτότητας κατά την καταχώρηση της εφαρμογής σας. Το αναγνωριστικό προγράμματος-πελάτη επιτρέπει στην υπηρεσία παροχής ταυτότητας να γνωρίζει ποια εφαρμογή πραγματοποιεί την αίτηση.
     • Μυστικός κωδικός προγράμματος-πελάτη: Ο μυστικός κωδικός προγράμματος-πελάτη που εκδίδει η υπηρεσία παροχής ταυτότητας κατά την καταχώρηση της εφαρμογής σας. Ο πράκτοράς σας στέλνει τον μυστικό κωδικό προγράμματος-πελάτη μαζί με το αναγνωριστικό προγράμματος-πελάτη για να αποδείξει ότι ο πράκτοράς σας έχει εξουσιοδοτηθεί να ζητήσει διακριτικά πρόσβασης για τον διακομιστή MCP.
     • Διεύθυνση URL εξουσιοδότησης: Το τελικό σημείο υπηρεσίας παροχής ταυτότητας όπου ο πράκτοράς σας ανακατευθύνει τον χρήστη για να εισέλθει και να εκχωρήσει δικαιώματα στον πράκτορά σας (κάρτα συγκατάθεσης που παρουσιάζεται στη συνομιλία του παράγοντα). Ο έλεγχος ταυτότητας του χρήστη πραγματοποιείται εδώ και, στη συνέχεια, η υπηρεσία παροχής ταυτότητας αποκρίνεται στον πράκτορα στη διεύθυνση URL επιστροφής κλήσης με έναν κωδικό εξουσιοδότησης.
     • Διεύθυνση URL διακριτικού: Το τελικό σημείο όπου ο αντιπρόσωπός σας ανταλλάσσει τον κωδικό εξουσιοδότησης (ή το διακριτικό ανανέωσης) με ένα διακριτικό πρόσβασης και ένα διακριτικό ανανέωσης. Το διακριτικό πρόσβασης επιτρέπει στον πράκτορά σας να χρησιμοποιεί τον διακομιστή MCP εκ μέρους του χρήστη. Τα διακριτικά ανανέωσης επιτρέπουν στον πράκτορά σας να αποκτά νέα διακριτικά πρόσβασης και ανανέωσης από το τελικό σημείο ανανέωσης, όταν λήγει το προηγούμενο διακριτικό πρόσβασης.
     • Διεύθυνση URL ανανέωσης: Το τελικό σημείο για την αίτηση νέου διακριτικού πρόσβασης με χρήση διακριτικού ανανέωσης (έτσι ώστε ο χρήστης να μην χρειάζεται να εισέλθει ξανά όταν λήξει το διακριτικό).
     • Εύρος: (Προαιρετικό): Τα δικαιώματα που ζητά η εφαρμογή σας, ως λίστα διαχωρισμένη με διαστήματα.
     • Τις Microsoft 365 οργανισμός έχει πρόσβαση στα τελικά σημεία: Αυτή η ρύθμιση περιορίζει την πρόσβαση στην προέλευση είτε στον οργανισμό του δημιουργού, είτε σε όλους τους οργανισμούς. Επιλέξτε ένα από τα εξής:
       • Μόνο ο οργανισμός μου
       • Ανοί Microsoft 365 οργανισμοί
     • Ποια εφαρμογή (πρόγραμμα-πελάτης) μπορεί να χρησιμοποιήσει τα τελικά σημεία: GUID που καθορίζει το σύστημα προγράμματος-πελάτη που μπορεί να χρησιμοποιηθεί για την πρόσβαση σε αυτά τα δεδομένα. Οι εφαρμογές μπορεί να περιλαμβάνουν Microsoft 365, Power Automate και άλλες επιλογές.

3. Όταν ολοκληρώσετε όλα τα πεδία, επιλέξτε Επόμενο.

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

   

Επιλέξτε εργαλεία από το API

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

1. Επιλέξτε ένα εργαλείο από τη λίστα για να ρυθμίσετε τις παραμέτρους.

   Εμφανίζεται η σελίδα Διαμόρφωση του εργαλείου σας .

   

2. Διαμορφώστε το όνομα και την περιγραφή για το επιλεγμένο εργαλείο. Παρόμοια με το συνολικό API, δώστε ένα Όνομα εργαλείου και Μια Περιγραφή εργαλείου. Οι περιγραφές αρχικά προσυμπληρώνονται από τις περιγραφές στην προδιαγραφή API. Το όνομα δεν χρειάζεται να είναι μοναδικό, αλλά θα πρέπει να αντιπροσωπεύει το ίδιο το εργαλείο. Η περιγραφή, όπως και η συνολική περιγραφή του API, θα πρέπει να είναι αρκετά συγκεκριμένη ώστε να παρέχει στο μοντέλο γλώσσας λεπτομέρειες για να προσδιορίσει καλύτερα εάν το ερώτημά σας ευθυγραμμίζεται με αυτό το συγκεκριμένο εργαλείο.

3. Μόλις συμπληρωθούν τα πεδία, επιλέξτε Επόμενο.

   Εμφανίζεται η σελίδα Εξέταση των παραμέτρων του εργαλείου σας .

   

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

4. Ενημερώστε τις περιγραφές όπως απαιτείται. Οι περιγραφές παρέχουν έναν ορισμό του σκοπού για τον οποίο χρησιμοποιούνται οι τιμές. Εάν οποιαδήποτε από τις περιγραφές είναι κενή, πρέπει να τις ολοκληρώσετε για να μπορέσετε να προχωρήσετε. Μπορείτε να επικολλήσετε το όνομα εάν δεν έχετε καλύτερη περιγραφή.

5. Αφού ολοκληρώσετε τις περιγραφές, επιλέξτε Επόμενο.

   Το πρώτο εργαλείο έχει ρυθμιστεί τώρα και εμφανίζεται στη λίστα επιλεγμένων εργαλείων στη σελίδα "Επιλογή και ρύθμιση παραμέτρων του εργαλείου προσθήκης ".

   

6. Προσθέστε οποιαδήποτε άλλα εργαλεία από το API που θέλετε να συμπεριλάβετε αυτήν τη στιγμή. Όταν ολοκληρώσετε την προσθήκη εργαλείων που θέλετε να υποστηρίζει ο πράκτοράς σας, επιλέξτε Επόμενο.

   Εμφανίζεται η σελίδα Έλεγχος του εργαλείου σας . Η σελίδα παρέχει τις λεπτομέρειες του ρυθμισμένου εργαλείου REST API.

   

Έλεγχος και δημοσίευση

1. Εάν θέλετε να κάνετε οποιεσδήποτε ενημερώσεις, επιλέξτε Επιστροφή και κάντε τις αλλαγές σας. Διαφορετικά, επιλέξτε Επόμενο.

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

2. Επιλέξτε Δημιουργία σύνδεσης για να συνεχίσετε. Επιστρέφετε στην οθόνη Προσθήκη εργαλείου .

3. Επιλέξτε REST API στον επιλογέα τύπου εργαλείου. Μπορείτε να δείτε τα εργαλεία που δημιουργήθηκαν πρόσφατα από το API σας. Θα πρέπει να υπάρχει μία καταχώρηση ανά εργαλείο που προσθέσατε από το API.

4. Για κάθε ένα από τα εργαλεία που μόλις ρυθμίσατε από το API, δημιουργήστε ή επιλέξτε μια σύνδεση στο API και προσθέστε το εργαλείο στον παράγοντα σας:

   1. Στην οθόνη Προσθήκη εργαλείου , επιλέξτε το εργαλείο.
   2. Στην περιοχή Σύνδεση, επιλέξτε μια υπάρχουσα σύνδεση ή επιλέξτε Δημιουργία νέας σύνδεσης.
   3. Εισαγάγετε τις πληροφορίες που απαιτούνται για τη σύνδεση και, στη συνέχεια, επιλέξτε Δημιουργία για να δημιουργήσετε τη σύνδεση με το εργαλείο.
   4. Επιλέξτε Προσθήκη και ρύθμιση παραμέτρων για να προσθέσετε το εργαλείο στον πράκτορά σας.

   

Τα εργαλεία από το REST API είναι πλέον διαθέσιμα για χρήση στον agent σας.

Συμβουλή

Για να βρείτε πιο εύκολα το εργαλείο σας, χρησιμοποιήστε τη γραμμή αναζήτησης για να το εντοπίσετε.