פריסת הסוכן בסביבת Azure

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

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

כדי לעדכן את נקודת הקצה של ההודעות, עיינו במשאבים הבאים. הם מראים כיצד ניתן לעדכן את נקודת קצה ההודעות אם תפרסם את הסוכן לספקי ענן אחרים, כגון Amazon Web Services או Google Cloud Platform:

• השתמש בקוד סוכן שמופעל ב-Amazon Web Services
• השתמש בקוד סוכן שמופעל בפלטפורמת Google Cloud

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

לפני שתתחיל, ודא שברשותך הפריטים הבאים:

חשבונות והרשאות נדרשים

• מינוי Azure עם גישה של תורם.
• קוד סוכן עובד עם נקודת קצה תקפה ונגישה לצורכי העברת הודעות. עליך לוודא שבדקת את הסוכן ברמה מקומית ובמידת הצורך, בדקת אותו גם ב-Microsoft 365, באמצעות מנהרות פיתוח כדי לוודא שניתן לפתח את קוד הסוכן והוא פועל כמצופה.
• תכנית סוכן תקינה על ידי השלמת שלב הגדרת תוכנית הסוכן.
• קובצי תצורה עדכניים a365.config.json, a365.generated.config.json וקובץ תצורה בקוד (כגון קובץ env.).

כלים נדרשים

• Azure CLI שהותקן ואומת (התקנת Azure CLI)

פרוס ב- Azure

פרוס את קוד יישום הסוכן ל-Azure באמצעות כלים רגילים של Azure, כגון Azure CLI, פורטל Azure או GitHub Actions.

פריסת יישום הסוכן

השתמש בפקודת az webapp deploy של Azure CLI כדי לפרוס את היישום:

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

עבור GitHub Actions, השתמש בפעולת לפריסת אפליקציות Azure לאינטרנט.

אזהרה

ניהול סודות: אחסנו משתני סביבה, כולל מפתחות API וסודות, כהגדרות אפליקציה של Azure במקום בקוד או בקבצי תצורה. לסביבות ייצור, השתמשו בפתרון Azure Key Vault עבור סודות רגישים. קבלו מידע נוסף אודות אחסון בטוח של סודות אפליקציה בעת פיתוח בליבת ASP.NET וכן בספק תצורה של Azure Key Vault. לעולם אל תבצע התחייבות של .envקבצים שמכילים מידע רגיש לבקרת המקור.

אימות פריסה

לאחר סיום הפריסה, השתמש ברשימה זו ובהוראות בחלקים הבאים כדי לאמת את הפריסה.

✅ פקודת הפריסה הושלמה ללא שגיאות
✅ האפליקציה לאינטרנט פועלת
✅ יומני היישום מצביעים על הפעלה תקינה
✅ משתני הסביבה הוגדרו
✅ נקודת הקצה של העברת ההודעות מגיבה

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

בסיום הפריסה, אמת את ההצלחה ביומני הפריסה:

1. עבור אל האפליקציה לאינטרנט בפורטל Azure.
2. עבור אל הגדרות>תצורה כדי לאמת את הגדרות האפליקציה.
3. בדוק את יומני הפריסה במרכז הפריסה.

לצפייה בהיסטוריית פריסות מפורטת:

1. עבור אל האפליקציה לאינטרנט > בפורטל Azure
2. פריסה>מרכז פריסה
3. הצג יומנים עבור הפריסה האחרונה

אם תהליך ה-Build נכשל:

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

אם האפליקציה קורסת לאחר הפריסה:

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

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

השתמש בפקודה az webapp show כדי לוודא שהאפליקציה לאינטרנט פועלת.

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

הפלט הצפוי של פקודה זו הוא Running.

ודא שיומני היישום מראים הפעלה מוצלחת

כדי לצפות ביומני האפליקציה לאינטרנט בפורטל Azure:

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

לחלופין, ניתן להשתמש בפקודת PowerShell az webapp log tail כדי לקרוא את יומני האפליקציה לאינטרנט:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

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

ודא שמשתני הסביבה הוגדרו

בפורטל Azure:

1. עבור אל האפליקציה לאינטרנט.
2. עבור אל הגדרות>משתני סביבה.
3. ודא שההגדרות קיימות.

אם משתני הסביבה לא מוגדרים:

• בצע פריסה שוב כדי לסנכרן מהקובץ .env.
• או הגדר אותם באופן ידני בפורטל Azure.
• עיין במקטע משתני סביבה אינם מוגדרים או שגויים.

ודא שנקודת קצה להעברת הודעות מגיבה

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

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

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

פרסם את הסוכן

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

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

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

סעיף זה מתאר בעיות נפוצות בעת פריסת סוכנים ל-Azure.

עצה

מדריך פתרון הבעיות של Agent 365 כולל המלצות מתקדמות לפתרון תקלות, שיטות עבודה מומלצות וקישורים לתוכן פתרון תקלות לכל חלק במחזור החיים של פיתוח Agent 365.

כשל של פקודת פריסה

תסמין: הפריסה לסביבת Azure נכשלה.

סיבות ופתרונות נפוצים:

• שגיאות גרסת Build

  יצירה מחדש של הפרויקט באופן מקומי כדי לראות שגיאות קומפילציה מפורטות:

  # .NET
  dotnet clean
  dotnet build --verbosity detailed
  
  # Python
  uv build
  
  # Node.js
  npm install
  npm run build
  

• האימות של Azure פג תוקף

  היכנס שוב לפורטל Azure:

  az login
  az account show  # Verify correct subscription
  

• האפליקציה לאינטרנט לא נוצרה

  רשום האפליקציה לאינטרנט כדי לוודא שהיעד קיים:

  # List Web Apps in resource group
  az webapp list --resource-group <your-resource-group> --output table
  

• בדיקת יומני הפריסה

  השתמש בפקודה az webapp log tail כדי לצפות ביומני פריסה מפורטים:

  az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
  

• אימות:

  # Web App should be running
  az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
  # Expected: "Running"
  

האפליקציה לאינטרנט מפסיקה לפעול

תסמינים: הפריסה בוצעה בהצלחה, אבל האפליקציה לאינטרנט לא פועלת.

פתרון: השתמש ב-az webapp start וב-az webapp show כדי להפעיל את האפליקציה לאינטרנט וודא שהיא פועלת.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

קריסת אפליקציה בעת הפעלתה

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

סיבות נפוצות:

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

פתרון: השתמש בפקודות az webapp log tail, az webapp config appsettings list ו-az webapp config appsettings set כדי לצפות ביומני היישום, לבדוק משתני סביבה ולהגדיר משתנים חסרים.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

404 בנקודת הקצה להעברת הודעות

תסמין: האפליקציה לאינטרנט פועלת אבל נקודת הקצה /api/messages מחזירה שגיאה 404.

פתרון:

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

בדוק את נקודת הקצה על ידי שליחת בקשה GET לכתובת URL. השתמש בפקודה az webapp config show כדי לבדוק את הגדרות האפליקציה לאינטרנט.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

משתני סביבה אינם מוגדרים או שגויים

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

פתרון: ודא ועדכן את משתני הסביבה. השתמש בפקודות az webapp config appsettings list ו-az webapp config appsettings set כדי לבדוק משתני סביבה ולהגדיר את המשתנים החסרים. לאחר מכן פריסה מחדש.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

תהליך היצירה הצליח באופן מקומי אבל נכשל בסביבת Azure

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

פתרונות:

• בדוק תלויות ספציפיות לפלטפורמה

  • לחלק מהחבילות יש גרסאות ייעודיות לפלטפורמה.
  • ודא שהתלויות תומכות בסביבת Linux (האפליקציה לאינטרנט בסביבת Azure פועלות כברירת מחדל בסביבת Linux).

• ודא שגרסאות זמן הריצה תואמות

  הרץ את הפקודות הבאות:

  # Check your local version
  dotnet --version  # .NET
  node --version    # Node.js
  python --version  # Python
  

  השווה לזמן הריצה של Azure בפורטל: הגדרות>תצורה>הגדרות כלליות>הגדרות מערם.

לקבלת עזרה נוספת, עיינו במקטע: פתרון תקלות בנקודת קצה להעברת הודעות.