בדיקת סוכנים תוך שימוש ב-Dev Tunnels

Dev Tunnels מאפשר לבצע בדיקה של סוכן Agent 365 עם אפליקציות Microsoft 365 (כגון Teams, ‏Outlook או Word) כשהסוכן פועל מקומית במחשב שמפעיל את סביבת הפיתוח. גישה זו מגשרת בין פיתוח מקומי לבדיקות מהעולם האמתי, כך שאפשר לאמת את התנהגות הסוכנים בסביבות Microsoft 365 אמתיות לפני פריסה בענן.

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

לפני שימוש במנהרות פיתוח, עליכם לוודא התקנה של כלי שורת הפקודה של Dev Tunnels.

• Windows: winget install Microsoft.devtunnel
• macOS/Linux: הורדה מ-aka.ms/devtunnels/download

הקמת מנהרת הפיתוח

הגדירו מנהרת פיתוח כדי לחשוף את נקודת הקצה של הסוכן המקומי לשירותי Microsoft 365.

יצירה והפעלה של מנהרה

1. כניסה למנהרת פיתוח:

   devtunnel user login
   

2. יצירת מנהרה רצופה:

   devtunnel create --allow-anonymous
   

   פקודה זו מחזירה את מזהה המנהרה. עליכם לשמור את המזהה הזה לשימוש עתידי.

3. הגדרת יציאה עבור המנהרה:

   הקצה את היצירה ששרת הסוכן משתמש בו (ברוב המקרים, 3978):

   devtunnel port create <tunnel-id> -p <port-number>
   

4. הפעלת המנהרה:

   devtunnel host <tunnel-id>
   

   הפקודה מציגה את כתובת המנהרה (כגון https://abc123xyz.devtunnels.ms:3978). העתיקו את כתובת ה-URL הזאת לשלב הבא.

עצה

השתמשו ב-devtunnel list כדי לצפות בכל המנהרות devtunnel delete <tunnel-id> ולהסיר מנהרות שאינן נחוצות עוד.

הגדרת נקודת קצה עבור הודעות לסוכן

רשמו את כתובת ה-URL של מנהרת הפיתוח (כגון https://abc123xyz.devtunnels.ms:3978/api/messages) כנקודת קצה של הסוכן כדי ש-Microsoft 365 ידע לאן לנתב הודעות. אל תשכחו להוסיף את הסיומת /api/messages לנקודת הקצה.

עיינו במקטע הגדרת נקודת קצה עבור הודעות סוכן

בדיקה עם Microsoft 365

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

בדיקה ב- Microsoft Teams

1. הפעלת הסוכן המקומי באמצעות ההוראות במקטע התקנת תלויות והפעלת שרת יישום סוכן.

2. אימות קישוריות המנהרה:

   devtunnel list
   

   בדקו שהמנהרה מציגה חיבורים פעילים של המארח. על העמודה 'חיבורי מארח' להציג מספר גדול מ-0.

3. אינטראקציה עם הסוכן ב-Teams:

   • פתחו את Microsoft Teams (גרסה אינטרנטית או גרסת שולחן עבודה)
   • בשורת החיפוש של Teams, חפשו את הסוכן לפי שם או כתובת דוא"ל
   • התחלת שיחה עם הסוכן
   • שליחה הודעה ובחינת התגובה
   • ביקור בקונסולה המקומית כדי לבדוק נוכחות של בקשות נכנסות ופעילות של סוכנים

בדיקת הודעות בדואר אלקטרוני

אם הסוכן כולל הגדרה עבור הודעות בדוא"ל:

1. שלחו הודעת דוא"ל אל הכתובת של הסוכן
2. כתבו את הסוכן בשרשור הדוא"ל
3. נטרו את הקונסולה המקומית כדי לעיין בהודעות webhook
4. אמתו את עיבוד הדוא"ל על ידי הסוכן ומתן תגובה על ידו

בדיקת אינטגרציה עם Word

עבור סוכנים שמגיבים לתגובות ב-Word:

1. פתחו מסמך Word שאליו יש לסוכן הרשאת גישה.
2. הוסיפו תגובה שמזכירה את הסוכן.
3. עיינו בקונסולה המקומית כדי לאתר את ההודעה.
4. אשרו שהתגובה של הסוכן מופיעה ב-Word.

ניטור פעילות מנהרה

Dev Tunnels מספק בדיקת תעבורה כדי לעזור לנתר בעיות חיבור ולהבין את אופי זרימת הבקשות:

devtunnel show <tunnel-id>

פקודה הזאת מציגה:

• חיבורים פעילים ופרטי ההפעלה.
• מידע על בקשה ותגובה.
• נתונים סטטיסטיים לגבי נפח התעבורה.
• שגיאות חיבור ואזהרות.

אפשר גם לנטר את פעילות המנהרה בזמן אמת על ידי צפייה בפלט מהפקודה devtunnel host.

שמירה על חיבורי מנהרות

Dev Tunnels מחייבות המשך ההפעלה של תהליך devtunnel host. במקרה של חוסר פעילות, בעיות רשת או אם המחשב נכנס למצב שינה, החיבור ינותק ויהיה צורך לבצע הפעלה מחדש.

בדיקת מצב המנהרה

בדיקה אם המנהרה פעילה:

devtunnel list

הפלט מציג:

• מזהה מנהרה: מזהה המנהרה
• חיבורי המארח: מספר החיבורים הפעילים (על הערך להיות אחד ומעלה כש-devtunnel host מופעל)
• יציאות: יציאות מוגדרות
• פקיעה תוקף: המועד שבו תוקפה של המנהרה יפוג

אם ערכי חיבורי המארח מציגים 0, המנהרה קיימת אך בשלב זה אינה מאוחסנת.

יש לבצע הפעלה מחדש של המנהרה המנותקת

אם החיבור למנהרה נפל, יש לבצע הפעלה מחדש תוך שימוש באותו מזהה מנהרה:

devtunnel host <tunnel-id>

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

שמירה על פעילות המנהרות במהלך הפיתוח

כדי לשמור על חיבורים יציבים:

• השאירו את חלון המסוף פתוח – אל תסגרו את המסוף כש-devtunnel host מופעל.
• מניעת כניסה של המחשב למצב שינה – שנו את הגדרות המערכת כדי שהמחשב יישאר ער במהלך הפעלות הבדיקה.
• שימו לב לשגיאות חיבור – עקבו אחר פלט המסוף devtunnel host כדי לזהות הודעות ניתוק.
• אתחלו מחדש לאחר שינויים ברשת – במקרה של החלפת רשת או חיבור מחדש דרך VPN, הפעילו מחדש את המנהרה.

עצה

אם המנהרה מתנתקת לעתים קרובות, בדקו את הגדרות הרשת ואת כללי חומת האש כדי לוודא שהם אינם חוסמים את החיבור.

ניקוי

בסיום הבדיקה עם Dev Tunnels:

עצירת פעולת המנהרה

לחצו על Ctrl+C במסוף שמפעיל את devtunnel host כדי להפסיק את פעולת המנהרה.

פקודה זו מסירה את כתובת ה-URL של Dev Tunnels מנקודת הקצה של הודעות הסוכן. בעת פריסה בסביבת ייצור, הגדירו את כתובת ה-URL של נקודת קצה שמתארחת בענן.

הערה

המנהרה נותרת זמינה לשימוש עתידי עד למחיקה מפורשת באמצעות devtunnel delete <tunnel-id>.

הגבלות

יש להתחשב במגבלות הללו בעת ביצוע בדיקות עם Dev Tunnels:

• פיתוח בלבד: השתמשו ב-Dev Tunnels לצורכי פיתוח ובדיקה, לא לצורכי ייצור.
• ביצועים: עליכם לצפות לערכי השהייה גבוהים יותר בהשוואה לסוכנים בענן בשל ניתוב הרשת.
• יציבות החיבור: לעתים, חיבורי המנהרה עשויים להיעלם ולחייב הפעלה ידנית.
• שיקולי אבטחה: הדגל --allow-anonymous נוח לבדיקה, אך אל אין להשתמש בו עם נתונים רגישים.
• ניהול הפעלה: ייתכן שיהיה עליכם לבצע אימות מחדש מדי פעם, בהתאם למשך ההפעלה.

‏‫השלבים הבאים‬

לאחר ביצוע בדיקה בהצלחה באמצעות Dev Tunnels:

• פריסת הסוכן בענן: פריסה ב-Azure, הגדרת נקודת קצה עבור הודעות סוכן ב-AWS או הגדרת נקודת קצה עבור הודעות סוכן ב-GCP.
• הגדרת נקודות קצה עבור הודעות סוכנים: נקודת קצה עבור הודעות סוכנים.
• עקבו אחר מחזור החיים המלא של הפיתוח: מחזור החיים של פיתוח Agent 365.

‏‫פתרון בעיות

במקרה של בעיות בעת ביצוע בדיקות באמצעות Dev Tunnels, התחילו כאן כדי לבצע תיקונים נפוצים עבור מנהרות, קישוריות ונקודות קצה. לפתרון תקלות רחב יותר עבור Agent 365 (הגדרה, אימות והודעות), עיינו במקטע פתרון תקלות.

חיבור המנהרה נכשל

תסמינים‏: Dev Tunnels לא מופעל או מתנתק מייד.

פתרונות:

• ודאו שאתם מחוברים: devtunnel user login
• בדקו אם תהליך אחר משתמש באותה יציאה
• ודאו שחומת האש מאפשרת חיבורים אל Dev Tunnel
• מחקו וצרו מחדש את המנהרה: devtunnel delete <tunnel-id> ולאחר מכן צרו מנהרה חדשה

הודעות אינן מגיעות אל הסוכן המקומי

תסמינים: Microsoft 365 מציין שההודעה נשלחה, אך הסוכן המקומי לא מקבל אותה.

פתרונות:

• ודאו שהסוכן פועל באופן מקומי
• אימות שהמנהרה פעילה: devtunnel list אמורה להציג את החיווי 'מחובר'
• בדקו את תצורת נקודת הקצה ב-a365.config.json וודאו שכתובת ה-URL של Dev Tunnel מוגדרת כנקודת קצה עבור הודעות
• בדקו את יומני הרישום של Dev Tunnel במסוף שמפעיל את devtunnel host כדי לאתר שגיאות חיבור
• ודאו שהיציאה המקומית תואמת ליציאת המנהרה (שתיהן צריכות להיות 3978 כברירת מחדל)

שגיאות אימות דרך Dev Tunnel

תסמינים: שגיאת 401 או 403 בעת בדיקות באמצעות Dev Tunnel.

פתרונות:

• ודאו שהוגדר אימות אוטונומי (אימות באמצעות אסימון נושא לא עובד עם Dev Tunnel עבור אינטגרציה עם Microsoft 365).
• בדקו את פרטי קישוריות ה-Blueprint של הסוכן ב-a365.generated.config.json.
• ודאו שלסוכן יש את כל ההרשאות הנדרשות לפעולות שאתם בודקים.
• ודאו שאסימוני האימות עדיין תקפים.

כתובת ה-URL של המנהרה שונתה או פקעה

תסמינים: כתובת ה-URL של מנהרה שפעלה בעבר כבר אינה לא מנתבת אל הסוכן.

פתרונות:

• בדקו את מצב המנהרה באמצעות devtunnel list.
• הפעילו מחדש את המנהרה באמצעות devtunnel host <tunnel-id>.
• עדכנו את נקודת הקצה עבור הודעות אם כתובת ה-URL השתנה באמצעות a365 setup blueprint --endpoint-only.