הרחב את הסוכן שלך באמצעות כלים מ- REST API (תצוגה מקדימה)

‏‫[מאמר זה הוא תיעוד קדם-הפצה והוא עשוי להשתנות.]‬

באפשרותך להשתמש בממשקי REST API (כולל API של OpenAI) כדי לחבר סוכן שאתה יוצר עם מערכות חיצוניות ולגשת לנתונים זמינים לשימוש בתוך הסוכן שלך. באפשרותך לחבר את הסוכן שלך לממשק REST API על-ידי Copilot Studio עם שלושה דברים:

• מפרט OpenAPI שמציין את הפונקציות של ה- API ואת הפעולות הזמינות
• פרטים על סוג האימות הדרוש ופרטי האימות עבור משתמשים כדי להתחבר ל- API כדי לגשת למערכת החיצונית
• תיאורים שיעזרו למודל השפה לקבוע מתי להפעיל את ה- API כדי להשתמש בנתונים

באפשרותך להוסיף ממשקי API של REST לסוכני Copilot ולסוכנים מותאמים אישית דרך Copilot Studio.

חשוב

מאמר זה מכיל תיעוד תצוגה מקדימה עבור Microsoft Copilot Studio והוא כפוף לשינויים.

תכונות Preview אינן מיועדות לשימוש בסביבת ייצור והפונקציונליות שלהן עשויה להיות מוגבלת. תכונות אלה זמינות לפני ההפצה הרשמית, כך שתוכל לקבל גישה מוקדמת ולספק משוב.

אם אתה בונה סוכן המוכן לייצור, ראה Microsoft Copilot Studio Overview.

סוכני Copilot מאפשרים ליוצר לשלב מקורות נתונים מרובים, כגון מחברים, ממשקי API, פקודות ומקורות ידע לסוכן יחיד. השתמש בסוכן זה כדי להרחיב Microsoft חוויות סוכן ממותגים כמו Microsoft 365 Copilot.

סוכנים מותאמים אישית הם סוכנים עצמאיים המכילים מחברים, ממשקי API, בקשות ומקורות ידע. באפשרותך להשתמש בסוכנים מותאמים אישית ישירות על-ידי שילובם באתרי אינטרנט או בערוצים אחרים.

הערה

עליך ליצור כלי REST API ממפרט OpenAPI v2. דרישה זו נובעת מהתנהגותה של Power Platform בעיבוד מפרטי API. אם אתה שולח מפרט v3, תהליך היצירה מתרגם אותו באופן אוטומטי למפרט v2.

‏‫דרישות מוקדמות‬

• אישורים ברמת יוצר, ורשיון Copilot Studio.
• עותק של מפרט OpenAPI עבור REST API שאליו ברצונך להתחבר
• ידע לגבי סוג האימות הדרוש כדי להתחבר ל- API ולפרטי האימות.

הוספת כלי REST API לסוכן שלך

כדי להוסיף כלי REST API לסוכן שלך, בצע את השלבים הבאים:

1. הוסף כלי סוכן חדש ובחר REST API
2. ספק מפרט, תיאור ופתרון של API
3. ספק פרטי אימות
4. בחירת כלים מה- API
5. סקירה ופרסום

הסעיפים הבאים מסבירים לך את התהליך, שלב אחר שלב.

התהליך להוספת REST API זהה עבור סוכנים מותאמים אישית וסוכני Microsoft 365 Copilot.

הוסף כלי סוכן חדש ובחר REST API

1. עבור לדף מבט כולל של הסוכן שלך.

2. במקטע כלים , בחר הוסף כלי. באפשרותך גם לעבור אל הכרטיסיה כלים ולבחור הוסף כלי.

   דף הוספת הכלי מוצג.

3. בחר ממשק RESTAPI של >כלי חדש.

ספק מפרט, תיאור ופתרון של API

1. העלה קובץ מפרט OpenAPI עבור ממשק ה- REST API שאליו ברצונך להתחבר. באפשרותך לגרור ולשחרר את קובץ המפרט במסך העלה ממשק API של REST או לעיין במערכת שלך כדי לאתר את הקובץ שבו ברצונך להשתמש.

   

   הערה

   מפרט 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 באמצעות מפתח זה.
   • אימות 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 כדי להוסיף אותם לנציג שלך. בדרך כלל, ממשק 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 זמינים כעת לשימוש בסוכן שלך.

עצה

כדי למצוא את הכלי שלך ביתר קלות, השתמש בסרגל החיפוש כדי לאתר אותו.