בנה סוכן Agent 365 המופעל ב-Amazon Web Services (AWS)

למד כיצד לבנות, לאחסן, לרשום ולפרסם סוכן Agent 365 שרץ על AWS Elastic Beanstalk, באמצעות Agent 365 CLI. Microsoft Entra ו-Graph מספקים את זהות הסוכן, הרשאות ותכנית, בעוד ש-AWS Elastic Beanstalk מספק את זמן הריצה.

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

יעדים

למד כיצד להשתמש ב-Agent 365 וב-Microsoft 365 כשכבת הבקרה ו:

• פריסת זמן ריצה לסוכן ב- AWS Elastic Beanstalk
• הגדר a365.config.json לאירוח שאינו Azure
• צור תבנית סוכן ב-Entra ID
• הגדר OAuth2 + הרשאות תורשתיות
• רשום נקודת קצה להעברת הודעות של Bot Framework המצביעה על AWS
• צור זהות סוכן + משתמש סוכן
• (אופציונלי) פרסם במשטחי אפליקציות Microsoft 365
• בדוק אינטראקציות מקצה לקצה

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

לפני שתתחיל, ודא שהדרישות הבאות ל-Azure / Microsoft 365, AWS וסביבה מקומית מתקיימות.

דרישות מוקדמות עבור Azure / Microsoft 365

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

• דייר Microsoft Entra ‏עם:

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

• Azure CLI הותקן ומחובר אל .

• Agent 365 CLI מותקן

דרישות מוקדמות של Amazon Web Services (AWS)

ודא שהשירותים והכלים הבאים של AWS מותקנים ומוגדרים כדי לפרוס ולנהל את סביבת Elastic Beanstalk שלך.

• חשבון AWS עם הרשאות מתאימות
• גישה ל-AWS Elastic Beanstalk מופעלת
• AWS CLI הותקן והוגדר
• Elastic Beanstalk CLI הותקן

דרישות מוקדמות לסביבת פיתוח מקומית

התקן והגדר את הכלים הבאים באופן מקומי כדי לבנות, להריץ ולפרוס את הסוכן.

• עורך קוד: השתמש בVisual Studio Code או Visual Studio

• .NET SDK: השתמש ב.NET 8.0 SDK או מאוחר יותר

• AWS Toolkit: התקן את ההרחבה הזו מתוך Visual Studio או Visual Studio Code. התחבר באמצעות פרטי ה-AWS Identity ו- Access Management (IAM) שלך.

• גישת LLM API: בחר את השירות המתאים בהתבסס על תצורת הסוכן שלך או על ספק המודלים המועדף עליך:

  • מפתח OpenAI API: קבל את מפתח ה-API של OpenAI
  • Azure OpenAI: צור ופרוס משאב Azure OpenAI כדי לקבל את מפתח ה-API ונקודת הקצה שלך

צור ופרוס סוכן .NET

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

• מגיב ל-GET /
• מקבל פעילויות Bot Framework ב-POST /api/messages

צור ספריית פרויקטים

mkdir aws-a365-agent
cd aws-a365-agent

אתחול פרויקט .NET

כדי לייעל את חוויית השימוש, מאמר זה משתמש בדוגמה מוכנה מראש. שכפל את מאגר דוגמאות Agent 365 ועבור לדוגמה dotnet\semantic-kernel\sample-agent .

דוגמה לסוכן הליבה הסמנטית - דוגמה C#/.NET כוללת:

• ממשק API ליבת ASP.NET מינימלי
• מטפל הודעות Bot Framework ב- /api/messages
• נקודת סיום לבדיקת תקינות ב- /
• אינטגרציה עם Semantic Kernel ליכולות AI

עבור אל dotnet\semantic-kernel\sample-agent וודא שהפרויקט נבנה בהצלחה:

dotnet restore
dotnet build

הגדרת דגם

פעל לפי ההוראות בשלב 2: הגדרת LLM כדי להגדיר את הפרויקט באמצעות מפתח Open API שלך.

בדוק מקומית (אופציונלי)

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

   # Run the application
   dotnet run
   

2. בדוק את נקודות הקצה בטרמינל אחר:

   # Test agent endpoint locally
   curl http://localhost:3978
   

3. לחץ על Ctrl+C כדי לעצור את השרת המקומי.

בנייה ופריסה

בחר את האפשרות שאתה מעדיף כדי לבנות ולפרוס את היישום לדוגמה הזה:

• אפשרות א': בנייה ופריסה מ-Visual Studio
• אפשרות ב': בנייה ופריסה אל AWS Elastic Beanstalk באמצעות CLI

אפשרות א': בנייה ופריסה מ-Visual Studio

השתמש בערכת הכלים של AWS עבור Visual Studio כדי לפרסם את האפליקציה ב-Elastic Beanstalk באמצעות אשף מודרך.

1. בתוך סייר הפתרונות, לחץ לחיצה ימנית על הפרויקט שלך.

2. בחר פרסם ב-AWS Elastic Beanstalk.

3. עקוב אחרי אשף פריסת Beanstalk:

   • בחר את פרופיל האישורים של AWS.
   • בחר אזור (לדוגמה, us-east-1).
   • בחר פלטפורמה (.NET Core on Linux).
   • קבע את הגדרות הסביבה

4. בחר פריסה.

האשף בונה, אורז ופורס את האפליקציה שלך ב-AWS.

אפשרות ב': בנייה ופריסה אל AWS Elastic Beanstalk באמצעות CLI

השתמש ב-Elastic Beanstalk CLI כדי לארוז ולפרוס את סוכן .NET בסביבת Amazon Linux 2 של 64 סיביות. ודא ש-AWS CLI ו-EB CLI מוגדרים. האפליקציה מתחברת למשתנה הסביבה PORT שנקבע על ידי Beanstalk.

1. בנה ופרסם את אפליקציית .NET שלך:

   # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
   dotnet publish -c Release -o ./publish --runtime linux-x64
   

   צור קובץ Procfile עם התוכן הבא.

   web: dotnet ./SemanticKernelSampleAgent.dll
   

2. אתחול Elastic Beanstalk עבור .NET. אתה מתבקש לבחור אזור ופלטפורמה:

   eb init
   

3. בחר:

   • פלטפורמה: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
   • אזור: האזור המועדף עליך ב-AWS (לדוגמה: us-east-1)

4. צור חבילת פריסה ופרוס:

   cd publish
   zip -r ../deploy.zip .
   cd ..
   eb create aws-a365-agent-env
   eb deploy
   

   פקודה זו:

   • יוצר אפליקציית Elastic Beanstalk.
   • יוצר סביבה עם מאזן עומסים
   • פורס את היישום שלך.
   • מספק משאבי AWS נדרשים.

5. בסיום, קבל את נקודת הקצה של Elastic Beanstalk:

   eb status
   

   שים לב לנקודת הסיום שלך. היא אמורה להיראות כך:

   http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com
   

   נקודת קצה זו היא ה-messagingEndpoint שבה משתמש CLI של כלי הפיתוח של Agent 365.

הערה

לסביבות ייצור, הגדר את HTTPS על ידי הוספת תעודת SSL/TLS ב-Elastic Beanstalk. Bot Framework דורשת HTTPS לנקודות קצה של ייצור.

הגדרה לאירוח שאינו Azure

צור a365.config.json ידנית בתיקיית הפרויקט של Elastic Beanstalk:

חשוב

לאחסון שאינו Azure, הגדר את הערך messagingEndpoint לכתובת ה-URL של Elastic Beanstalk עם הנתיב /api/messages .

הקובץ a365.config.json אמור להיראות כך:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

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

שדה	משמעות
messagingEndpoint	כתובת ה-URL של Elastic Beanstalk שלך + /api/messages
deploymentProjectPath	המקום שבו מתבצע החתמת .env

בנה סוכן Agent 365

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

אמת את הסוכן מקצה לקצה

השתמש בבדיקות אלה כדי לאשר שהסוכן המתארח על ידי AWS נגיש, מקבל פעילויות Bot Framework ומגיב נכון במשטחי Agent 365.

אימות קישוריות Elastic Beanstalk

שלח בקשת GET לנקודת הקצה של Elastic Beanstalk.

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

הבקשה אמורה להחזיר את ההודעה הבאה:

AWS Agent is running.

בדוק יומני Elastic Beanstalk עבור הודעות Bot Framework נכנסות

השתמש ברישום Elastic Beanstalk כדי לוודא שהסוכן שלך מקבל פעילויות Bot Framework ומגיב כראוי.

eb logs

או שדר יומנים בזמן אמת:

eb logs --stream

לאחר שהודעה מגיעה לסוכן שלך, אתה רואה:

POST 200 /api/messages
Received activity: { ... }

בדוק סוכן במשטחי Agent 365

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

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

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

זרימת עבודה למפתחים

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

פתח ובדוק מקומית

השתמש במצב צפייה לפיתוח מהיר עם טעינה אוטומטית:

# Automatically rebuild and restart on file changes
dotnet watch run

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

בנה ופרוס מחדש ב-AWS Elastic Beanstalk

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

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

בדיקה וניטור

בדוק באמצעות משטחי Agent 365 ונטר את יומני Elastic Beanstalk:

# Stream logs in real-time
eb logs --stream

אין צורך ליצור מחדש את הזהות, התבנית, נקודת הקצה של תוכנית Bot או ההרשאות שלך.

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

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

עצה

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

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

‏‫בדוק את הפרטים הבאים:‬

• נקודת הקצה שלך היא בדיוק:
  http://<your-app>.elasticbeanstalk.com/api/messages
• הסביבה שלך ב-Elastic Beanstalk תקינה. השתמש בבדיקה באמצעות eb health.
• קבוצת האבטחה שלך מאפשרת תעבורת HTTP או HTTPS נכנסת.
• אין כללי חומת אש או הגבלות VPC.

בעיות בתקינות היישום

בדוק את תקינות הסביבה:

eb health --refresh

הצגת יומני רישום מפורטים:

eb logs

בעיות באיגוד יציאות

ודא שהאפליקציה שלך מאזינה ליציאה שצוינה במשתנה הסביבה PORT. Elastic Beanstalk מגדיר ערך זה אוטומטית.

בעיות בניית .NET או בעיות בזמן ריצה

בדוק שגיאות בנייה באמצעות הפקודות הבאות:

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

אמת את גרסת .NET:

dotnet --version
dotnet --list-sdks

בדוק בעיות חבילה:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

הקצאת רשיון נכשלת

הקצה ידנית רישיון Microsoft 365 תקף, או השתמש בנתיב משתמש ללא רישיון אם זה נתמך.