בדיקת סוכנים באמצעות Microsoft Agent 365 SDK

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

לאחר שהסוכן עובד באופן מקומי, עקוב אחרי מחזור החיים של פיתוח Agent 365 כדי לבדוק באפליקציות Microsoft 365 כמו Teams, Word ו-Outlook.

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

לפני שתתחיל לבדוק את הסוכן שלך, ודא שהתקנת את הדרישות המקדימות הבאות:

דרישות מקדימות כלליות

דרישות מקדימות ספציפיות לשפה

  • Python 3.11 או מאוחר יותר: הורדה מ-python.org או מ-Microsoft Store
  • מנהל חבילות UV: התקן UV באמצעות pip install uv
  • אמת את ההתקנה: python --version

הגדרת סביבת בדיקת סוכנים

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

משתני סביבה של Python LLM

משתנה Description נדרש דוגמה
OPENAI_API_KEY מפתח API לשירות OpenAI עבור OpenAI sk-proj-...
AZURE_OPENAI_API_KEY מפתח API לשירות 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: הגדר אימות עבור הסוכן שלך

בחר באחת משיטות האימות הבאות עבור הסוכן שלך:

אימות סוכני

פתח את a365.generated.config.json בתיקיית העבודה שלך כדי לאסוף את אישורי ה- blueprint של הסוכן. העתק את הערכים הבאים:

ערך Description
agentBlueprintId מזהה הלקוח של הסוכן
agentBlueprintClientSecret סוד הלקוח של הסוכן
tenantId מזהה הדייר שלך ב-Microsoft Entra

השתמש בערכים האלה כדי להגדיר אימות אג'נטי בסוכן שלך:

הוסף את ההגדרות הבאות לקובץ .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>
משתנה Description נדרש דוגמה
USE_AGENTIC_AUTH הפעל מצב אימות אג'נטי ‏‏כן‬ true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID מזהה לקוח של Blueprint של סוכן מתוך a365.generated.config.json ‏‏כן‬ 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET סוד לקוח של Blueprint של סוכן מתוך a365.generated.config.json ‏‏כן‬ abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID מזהה דייר ב-Microsoft Entra מ- a365.generated.config.json ‏‏כן‬ 22223333-cccc-4444-dddd-5555eeee6666

אימות OBO

באמצעות אימות בשמו של מישהו (OBO), הסוכן יכול לגשת לכלי שרת MCP באמצעות הרשאות משתמש שהועברו ללא צורך בזהות משתמש של סוכן. בתהליך זה, הסוכן מקבל אסימון מוסמך של המשתמש וממיר אותו כדי לבצע פעולות בשם המשתמש.

אימות OBO מתאים לתרחישי ייצור שבהם:

  • לסוכן שלך אין זהות משתמש של סוכן.
  • צריך לגשת למשאבים עם הרשאות ייחודיות למשתמש.
  • אתה רוצה שהסוכן יפעל בשם המשתמש המאומת.

לפרטים על אופן פעולת זרימת ה-OBO, ראה זרימות אימות. לדוגמה מלאה של מימוש, ראה את OBO authorization sample ב-Microsoft 365 Agents SDK.

אימות אסימון נושא

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

ראשית, השתמש בפקודה a365 develop add-permissions כדי להוסיף את הרשאות שרת MCP הנדרשות לאפליקציה שלך:

a365 develop add-permissions

לאחר מכן, השתמש ב-a365 develop get-token כדי לשלוף ולהגדיר אסימוני נושא:

a365 develop get-token

הפקודה get-token מבצעת אוטומטית:

  • קריאה ל-ToolingManifest.json כדי לגלות את כל שרתי MCP המוגדרים.
  • רוכשת אסימון אחד לכל קהל - שרתי MCP לכל שרת מקבלים אסימון המותאם למזהה האפליקציה הספציפי שלהם; שרתי ATG משותפים מקבלים אסימון שמותאם למזהה האפליקציה של Agents 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).

התוקף של אסימוני נושא פג לאחר כשעה. השתמש ב-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
משתנה Description נדרש
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE סוג מטפל אימות ‏‏כן‬
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES טווחי אימות עבור Microsoft Graph ‏‏כן‬
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME שם חיבור חלופי לשרטוט ‏‏כן‬
CONNECTIONSMAP_0_SERVICEURL תבנית כתובת השירות למיפוי חיבור ‏‏כן‬
CONNECTIONSMAP_0_CONNECTION שם חיבור למיפוי ‏‏כן‬

משתני אסימון נושא (פיתוח מקומי בלבד)

משתנה Description נדרש
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. נקודת קצה זו קובעת לאיזו סביבה (preprod, test, או production) שרתי הכלים MCP מתחברים ליכולות האינטגרציה של Microsoft 365.

הוסף לקובץ .env:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
משתנה Description חובה ברירת מחדל דוגמה
MCP_PLATFORM_ENDPOINT כתובת URL של נקודת קצה בפלטפורמת MCP ‏(preprod, test, או prod) לא נקודת קצה היצור

חשוב: אם לא תציין MCP_PLATFORM_ENDPOINT, האפליקציה משתמשת בנקודת הקצה של הייצור.

הערה

אם אתה משתמש בשרת הכלים המדומה מ-CLI, הגדר את נקודת הקצה שתהיה http://localhost:<port> באמצעות מספר היציאה שבו השתמשת. יציאת ברירת המחדל היא 5309.

משתני תצפיתיות

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

הערה

תצורת הניטור זהה בכל השפות. ראה תצורה לקבלת פרטים נוספים.

משתנה Description ברירת מחדל דוגמה
ENABLE_A365_OBSERVABILITY_EXPORTER ייצוא עקבות לשירות הניטור. כאשר false, ייצוא מתפשט לקונסולה במקום זאת. false true
A365_OBSERVABILITY_LOG_LEVEL רמת רישום פנימית עבור SDK של ניטור. מועיל לניפוי בעיות ייצוא במהלך הבדיקות. none info, warn, error, debug

קונפיגורציית שרת היישום של הסוכן

הגדר את היציאה שבה פועל שרת היישומים של הסוכן שלך. הגדרה זו אופציונלית וחלה על סוכני Python ו-JavaScript.

הוסף לקובץ .env:

# Server Configuration
PORT=3978
משתנה Description חובה ברירת מחדל דוגמה
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 הוא כלי בדיקה מקומי המדמה את סביבת Microsoft 365 מבלי לדרוש הגדרה מלאה של דייר. זו הדרך המהירה ביותר לאמת את הלוגיקה של הסוכן והפעלות הכלים שלו. למידע נוסף, ראה בדיקה עם Agents Playground.

הגדר את Agents Playground עבור אימות מסוג אג'נטי

הערה

הגדרה זו נדרשת רק בעת שימוש באימות אג'נטי. אם אתה משתמש באימות אסימון נושא, תוכל לדלג על סעיף זה ולהמשיך ישירות לבדיקה בסיסית.

כשאתה משתמש באימות אג'נטי, הגדר את קובץ ה-YAML של Agents Playground עם פרטי הסוכן שלך:

  1. הגדר את קובץ התצורה: צור או עדכן את הקובץ .m365agentsplayground.yml בתיקייה שבה אתה מריץ את Agents Playground. להוראות הגדרה מפורטות, ראה התאמה אישית להקשר של Teams.

  2. עדכן את תצורת הבוט: הוסף את פרטי הבוט הבאים לקובץ .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"

תגובה צפויה: הסוכן שולח אימייל באמצעות שרת Mail MCP ומאשר שההודעה נשלחה.

כלי לוח שנה

List my calendar events for today

תגובה צפויה: הסוכן אוסף ומציג את אירועי לוח השנה שלך ליום הנוכחי.

כלי SharePoint

List all SharePoint sites I have access to

תגובה צפויה: הסוכן שואל את SharePoint ומחזיר רשימה של אתרים שיש לך גישה אליהם.

ניתן לצפות בקריאות הכלים ב:

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

בדיקה עם פעילויות הודעה

במהלך פיתוח מקומי, בדוק תרחישי התראה באמצעות הפעלת ההתראה המובנית ב-Agents Playground.

צילום מסך שמראה את הממשק של Agents Playground עם תפריט Mock and Activity מורחב, ומציג אפשרויות פעילות של התראות טריגר כולל שליחת דואר אלקטרוני ואזכור ב-Word.

לפני בדיקת פעילויות התראה, ודא שאתה:

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

כדי לבדוק טיפול בהתראות דוא"ל:

  1. התחל את הסוכן ואת Agents Playground.
  2. ב-Agents Playground, עבור אל פעילות לדוגמה>הפעל פעילות של התראה.
  3. בחר שלח דוא"ל.
  4. בתיבת הדו-שיח, עדכן את פרטי ההודעה המדומה, כגון שם השולח ותוכן גוף ההודעה, לפי הצורך.
  5. בחר שלח פעילות.
  6. צפה בתוצאה הן בשיחה בצ'אט והן בלוח היומן.

הסוכן מקבל התראת דוא"ל מדומה ומעבד אותה בהתאם ללוגיקת טיפול ההתראות שלך. לפרטים על המבנה של ההתראה בדוא"ל, ראה תוכן מנה של ההתראה בדוא"ל.

בדוק התראות אזכור של Word

כדי לבדוק התראות אזכור במסמך Word:

  1. התחל את הסוכן ואת Agents Playground.
  2. ב-Agents Playground, עבור אל פעילות לדוגמה>הפעל פעילות של התראה.
  3. בחר אזכור ב-Word.
  4. בתיבת הדו-שיח, עדכן את פרטי התגובה המדומה, כגון מזהה המסמך וטקסט התגובה, לפי הצורך.
  5. בחר שלח פעילות.
  6. צפה בתוצאה הן בשיחה בצ'אט והן בלוח היומן.

הסוכן מקבל התראה מדומה של אזכור ב-Word ומגיב בהתאם ללוגיקת הטיפול בהתראות. לפרטים על המבנה של הודעת התגובה ב-Word, ראה תוכן מנה של הודעת תגובה במסמך.

בדיקת אירועי התקנה והסרה של הסוכן

כאשר Agents Playground מתחבר לסוכן שלך, הוא שולח באופן אוטומטי פעילות InstallationUpdate עם פעולה add. אם אתה מיישם פונקציית התקנה, הודעת הברכה של הסוכן שלך תופיע בצ'אט מיד לאחר שהחיבור נוצר.

לאימות טיפול באירועי התקנה:

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

גורם שורש:

  • תוקף של אסימונים פג לאחר כשעה
  • תצורת אימות שגויה
  • אישורים חסרים או לא תקפים

פתרונות:

  • לגבי פקיעת תוקף של אסימון נושא

    רענן את האסימון ועדכן את משתני הסביבה שלך.

    # 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 גוזר את שם המשתנה על ידי שינוי האותיות הרישיות של mcpServerNameToolingManifest.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 וסודות
    • מזהה דייר
    • מזהה ‏לקוח
    • Blueprint ID (אם משתמשים באימות אג'נטי)

    אימות:

    בדוק עם בקשה פשוטה ב-Agents Playground. אתה אמור לקבל תגובה ללא שגיאות 401.

  • בעיות בכלים ובהתראות

    בעיות אלו כוללות בעיות בקריאות לכלים, אינטראקציות עם שרתי MCP והעברת התראות.

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

תסמין: הסוכן מציין שנשלח דואר אלקטרוני, אבל אתה לא מקבל אותו

פתרונות:

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

תגובות ב-Word לא עובדות

בעיה ידועה: שירות ההתראות כרגע לא יכול להגיב ישירות לתגובות ב-Word. הפונקציונליות נמצאת בפיתוח.

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

תסמין: אפליקציית הסוכן לא מקבלת הודעות שנשלחות לסוכן ב-Teams.

גורמים אפשרים:

  • פורטל המפתחים לא מוגדר עם Blueprint של הסוכן.
  • בעיות באפליקציית Azure Web App (כשלים בפריסה, אפליקציה לא רצה, שגיאות קונפיגורציה).
  • מופע של סוכן לא נוצר כראוי ב-Teams.

פתרונות:

  • אימות של תצורת פורטל המפתחים:

    ודא שאתה משלים את תצורת התכנית של הסוכן בפורטל המפתחים. למד כיצד להגדיר את תוכנית האב של הסוכן בפורטל המפתחים

  • בדוק את תקינות היישום Azure Web:

    אם תפרוס את הסוכן ב-Azure, וודא שהאפליקציה פועלת כראוי:

    1. עבור אל פורטל Azure.
    2. גש למשאב אפליקציית האינטרנט.
    3. בדוק את מבט כולל>סטטוס (צריך להופיע "פועל").
    4. בדוק את זרם יומן תחת ניטור עבור שגיאות בזמן ריצה.
    5. סקור את היומנים במרכז הפריסה כדי לוודא שהפריסה הצליחה.
    6. ודא שקונפיגורציה>הגדרות היישום כוללות את כל משתני הסביבה הנדרשים.

  • בדוק את יצירת מופע הסוכן:

    ודא שאתה יוצר את מופע הסוכן בצורה נכונה ב-Microsoft Teams:

    1. פתח את Microsoft Teams.
    2. גש אל אפליקציות וחפש את הסוכן.
    3. ודא שהסוכן מופיע בתוצאות החיפוש.
    4. אם לא נמצא, ודא שהוא פורסם במרכז הניהול של Microsoft 365 - סוכנים.
    5. צור מופע חדש על ידי לחיצה על הוסף בסוכן.
    6. להוראות מפורטות, ראה קליטת סוכנים.

פתרון תקלות ביומני ניטור

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

  • Last updated on