שתף דרך

סוכני בדיקה המשתמשים ב- SDK של Microsoft Agent 365

חשוב

עליך להיות חלק מתוכנית התצוגה המקדימה של Frontier כדי לקבל גישה מוקדמת ל - Microsoft Agent 365. Frontier מחברת אתכם ישירות עם החידושים האחרונים של Microsoft בתחום הבינה המלאכותית. קבל תכונות פורצות דרך מעשיות, שתף את התובנות שלך עם צוותי מוצרים ועזור לעצב את עתיד הבינה המלאכותית. תצוגות מקדימות של Frontier כפופות לתנאי התצוגה המקדימה הקיימים של הסכמי הלקוחות שלך. כאשר תכונות אלה עדיין בפיתוח, הזמינות והיכולות שלהן עשויות להשתנות עם הזמן.'

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

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

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

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

דרישות מוקדמות נפוצות

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

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

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

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

  1. קביעת התצורה של הסביבה שלך - צור או עדכן את קובץ התצורה של הסביבה שלך

  2. תצורת LLM - קבלת מפתחות API וקביעת תצורה של הגדרות OpenAI או Azure OpenAI

  3. קביעת אימות - הגדרת אימות סוכני

  4. הפניה למשתנה סביבה - קביעת תצורה של משתני סביבה נדרשים:

    1. משתני אימות
    2. תצורת נקודת קצה של MCP
    3. משתני יכולת התבוננות
    4. תצורת שרת יישום סוכן

לאחר השלמת שלבים אלה, אתה מוכן להתחיל לבדוק את הסוכן שלך ב- Agents Playground.

שלב 1: קביעת התצורה של הסביבה שלך

הגדר את קובץ התצורה שלך:

cp .env.template .env

הערה

עיין בדוגמאות SDK של Microsoft Agent 365 כדי למצוא תבניות תצורה המציגות שדות נדרשים.

שלב 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

משתנה תיאור נדרש Example
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: קביעת תצורה של ערכי אימות עבור אימות זהות סוכן

השתמש בפקודה CLI a365 config display של A365 כדי לאחזר את אישורי השרטוט של הסוכן שלך.

a365 config display -g

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

ערך: תיאור
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>
משתנה תיאור נדרש Example
USE_AGENTIC_AUTH אפשר מצב אימות סוכני כן true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID מזהה לקוח של שרטוט סוכן מתוך a365 config display -g כן 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET סוד הלקוח של תבנית סוכן מתוך a365 config display -g כן abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID מזהה לקוח Microsoft Entra מ- a365 config display -g כן adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

הערה

עבור .NET, ודא גם שההגדרה USE_AGENTIC_AUTH=true מוגדרת ב launchSettings.json - (ראה שלב 4: הפניה למשתנה סביבה)

שלב 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 שם חיבור שרטוט חלופי כן
CONNECTIONSMAP_0_SERVICEURL תבנית כתובת URL של שירות עבור מיפוי חיבור כן
CONNECTIONSMAP_0_CONNECTION שם חיבור למיפוי כן

תצורת נקודת קצה של MCP

תצורת נקודת הקצה של MCP (פרוטוקול הקשר מודל) נדרשת כדי לציין לאיזה נקודת קצה של פלטפורמת סוכן 365 אמור הסוכן להתחבר. בעת יצירת מניפסט כלי המגדיר את שרתי כלי עבור הסוכן שלך, עליך לציין את נקודת הקצה של פלטפורמת MCP. נקודת קצה זו קובעת באיזו סביבה (preprod, test או production) שרתי הכלים של MCP מתחברים עבור יכולות שילוב של Microsoft 365.

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

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

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

משתני יכולת התבוננות

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

הערה

תצורת התצפית זהה בכל השפות.

משתנה תיאור ברירת מחדל Example
ENABLE_A365_OBSERVABILITY הפיכת יכולת התבוננות לזמינה/ללא זמינה false true
ENABLE_A365_OBSERVABILITY_EXPORTER ייצוא מעקבים לשירות התבוננות false true
OBSERVABILITY_SERVICE_NAME שם שירות עבור מעקב שם הסוכן my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE מרחב שמות של שירות agent365-samples my-company-agents

תצורת שרת יישום סוכן

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

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

# Server Configuration
PORT=3978
משתנה תיאור נדרש ברירת מחדל Example
PORT מספר יציאה שבו פועל שרת הסוכן לא 3978 3978

התקנת יחסי תלות והפעלת שרת היישומים של הסוכן

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

התקנת יחסי תלות

uv pip install -e .

פקודה זו מקריאת את יחסי התלות של החבילה המוגדרים ב pyproject.toml - ומתקין אותם מ- PyPI. בעת יצירת יישום סוכן מאפס, עליך ליצור קובץ כדי להגדיר pyproject.toml את יחסי התלות שלך. סוכנים לדוגמה מתוך מאגר הדוגמאות כבר יש להם חבילות אלו מוגדרות. באפשרותך להוסיף או לעדכן אותם לפי הצורך.

הפעל את שרת היישומים של הסוכן

python <main.py>

החלף <main.py> בשם של קובץ Python הראשי המכיל את נקודת הכניסה עבור יישום הסוכן שלך (לדוגמה, , start_with_generic_host.pyapp.py, או main.py).

או באמצעות uv:

uv run python <main.py>

שרת הסוכן שלך אמור לפעול כעת ומוכן לקבל בקשות מ- Agents Playground או מיישומי Microsoft 365.

סוכן בדיקה במגרש המשחקים של הסוכנים

Agents Playground הוא כלי בדיקה מקומי המדמה את סביבת Microsoft 365 מבלי לדרוש הגדרת דייר מלא. זו הדרך המהירה ביותר לאמת את הלוגיקה ואת הפעלות הכלי של הסוכן שלך. לקבלת מידע נוסף, ראה Test with Agents Playground.

פתח מסוף חדש (PowerShell ב- Windows) והפעל את Agents Playground:

agentsplayground

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

בדיקה בסיסית

התחל על-ידי אימות שהסוכן שלך מוגדר כראוי. שלח הודעה לנציג:

What can you do?

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

  • הסוכן שלך פועל כראוי
  • הסוכן יכול לעבד הודעות ולהגיב
  • התקשורת בין Agents Playground והסוכן שלך פועלת

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

לאחר קביעת התצורה של שרתי כלי toolingManifest.json ה- MCP שלך ב- (ראה Tooling לקבלת הוראות התקנה), הפעלות כלי בדיקה עם דוגמאות כגון אלה:

תחילה, ודא אילו כלים זמינים:

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. הדבר מאפשר לך לאמת את הטיפול בהודעות של הסוכן שלך לפני פריסתו לייצור.

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

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

כדי לשלוח פעילויות מותאמות אישית:

  1. הפעל את הסוכן שלך ואת Agents Playground
  2. ב- Agents Playground, נווט אל חקה פעילות>פעילות מותאמת אישית
  3. העתק את conversationId מהפעילות (מזהה השיחה משתנה בכל פעם שמחדשים את Agents Playground)
  4. הדבק את ה- JSON של הפעילות המותאמת אישית personal-chat-id שלך ועדכן את השדה עם מזהה השיחה שהעתקת. עיין בדוגמה של הודעת דואר אלקטרוני
  5. בחר שלח פעילות
  6. הצגת התוצאה הן בשיחות הצ'אט והן בלוח הרישום

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

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

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

הצגת יומני יכולת התבוננות

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

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

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

פתרון בעיות

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

בעיות חיבור וסביבה

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

בעיות חיבור 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 ב- VS Code

הפתרון: סגור ופתח מחדש את Visual Studio Code ולאחר מכן נסה שוב להוסיף את השרת.

בעיות אימות

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

פג תוקפו של אסימון נושא

תסמין: שגיאות אימות או 401 תגובות לא מורשות

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

שגיאות אימות סוכן ב- Python

תסמין: שגיאה בהשגת אסימון מופע סוכן

הפתרון: אמת את ההגדרה ALT_BLUEPRINT_NAME ב:.env

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

בעיות בכלי ובהודעות

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

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

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

פתרונות:

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

תגובות הערה של Word אינן פועלות

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

קבלת עזרה

אם אתה נתקל בבעיות שלא נכללו בסעיף פתרון בעיות זה, עיין במשאבים הבאים:

מאגרי SDK של Microsoft Agent 365

תמיכה נוספת

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

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

  • פרוס ופרסם נציגים: למד כיצד לפרוס את הסוכן שלך ב- Azure Web App ולפרסם אותו במרכז הניהול של Microsoft, כך שהארגון שלך יהיה זמין לגילוי ושכירה ב- Microsoft 365.
  • Last updated on