בניית סוכן ב- Agent 365 בפלטפורמת Google Cloud ‏(GCP)

למד כיצד לבנות, לארח, להירשם ולפרסם סוכן Agent 365 שפועל על Google Cloud Run, באמצעות Agent 365 CLI. Microsoft Entra & Graph מספק את זהות הסוכן, ההרשאות והשרטוט, בעוד Google Cloud Run מספק את זמן הריצה.

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

יעדים

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

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

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

לפני שתתחיל, ודא שהתנאים המוקדמים הבאים של Azure / Microsoft 365, Google Cloud Platform (GCP) וסביבה מקומית מתקיימים.

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

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

• דייר Microsoft Entra ‏עם:

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

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

• Agent 365 CLI מותקן

הדרישות המוקדמות של GCP

• פרויקט GCP נוצר

• ממשק API להפעלת ענן מופעל

• gcloud SDK מותקן ומאומת

  gcloud auth login
  gcloud config set project <GCP_PROJECT_ID>
  gcloud config set run/region us-central1   # or your preferred region
  

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

• עורך קוד: כל עורך קוד לפי בחירתך. מומלץ להשתמש Visual Studio Code.

• (אופציונלי) Node.js. באפשרותך להשתמש בכל שפה עבור סוכן שלך. מאמר זה משתמש בצומת 18+ בשלבים הבאים.

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

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

צור ופרוס סוכן של Agent 365 להפעלת ענן

בדוגמה זו נעשה שימוש בסוכן Agent 365 מינימלי שמבצע את הפעולות הבאות:

• מגיב ל-GET /
• מקבל פעילויות Bot Framework ב-POST /api/messages
• משתמש באימות JWT באמצעות SDK Agent 365
• מכיל את כל הקוד בקובץ אחד של index.js לשם פשטות

יצירת פרויקט

עקבו אחר השלבים האלה כדי לחזק סוכן Node.js מינימלי שרץ על Cloud Run ומקבל פעילויות Bot Framework.

1. צור את ספריית הפרויקט

   mkdir gcp-a365-agent
   cd gcp-a365-agent
   

2. אתחל את פרויקט הצומת

   npm init -y
   npm install express @microsoft/agents-hosting dotenv
   

3. יצירה index.js

      // Load environment variables from .env file (for local development)
   require('dotenv').config();
   
   const { 
   CloudAdapter, 
   Application, 
   authorizeJWT, 
   loadAuthConfigFromEnv 
   } = require('@microsoft/agents-hosting');
   const express = require('express');
   
   // Loads clientId, clientSecret, tenantId from environment variables
   // These map to your Agent Blueprint App Registration in Entra ID:
   //   clientId     = Blueprint Application (client) ID
   //   clientSecret = Blueprint client secret value  
   //   tenantId     = Your Microsoft Entra tenant ID
   const authConfig = loadAuthConfigFromEnv();
   
   // Pass authConfig to adapter so outbound replies can authenticate
   const adapter = new CloudAdapter(authConfig);
   
   const agentApplication = new Application({ adapter });
   
   // Handle incoming messages
   agentApplication.onMessage(async (context, next) => {
   await context.sendActivity(`You said: ${context.activity.text}`);
   await next();
   });
   
   // Handle conversation updates
   agentApplication.onConversationUpdate(async (context, next) => {
   if (context.activity.membersAdded) {
      for (const member of context.activity.membersAdded) {
         if (member.id !== context.activity.recipient.id) {
         await context.sendActivity('Welcome! This agent is running on GCP.');
         }
      }
   }
   await next();
   });
   
   // Required: handle agentLifecycle events sent by Agent 365 platform
   // Without this handler, the SDK throws on first conversation initiation
   agentApplication.on('agentLifecycle', async (context, next) => {
   await next(); // acknowledge silently — do NOT call sendActivity here
   });
   
   const server = express();
   server.use(express.json());
   
   // Health check — no auth required
   server.get('/', (req, res) => res.status(200).send('GCP Agent is running.'));
   
   // JWT validation applied only to /api/messages
   // Bot Framework Service sends a Bearer token signed by botframework.com
   // This is required even on GCP — the control plane is still Microsoft
   server.post('/api/messages', authorizeJWT(authConfig), (req, res) => {
   adapter.process(req, res, async (context) => {
      await agentApplication.run(context);
   });
   });
   
   const port = process.env.PORT || 8080;
   server.listen(port, () => console.log(`Agent listening on port ${port}`));
   

פרוס ל- Google Cloud Run

השתמש ב- gcloud run deploy כדי לבנות ולהפעיל את השירות ב- Cloud Run. בסיום הפריסה, יש לציין את כתובת ה- URL הציבורית של messagingEndpoint.

1. השתמש בפקודות הבאות כדי לפרוס את הפרויקט שלך ב- Google Cloud Run:

   gcloud run deploy gcp-a365-agent `
   --source . `
   --region us-central1 `
   --platform managed `
   --allow-unauthenticated
   

2. בסיום, שים לב לנקודת הקצה שלך:

   https://gcp-a365-agent-XXXX-uc.run.app
   

   כתובת URL זו נמצאת messagingEndpoint בשימוש על ידי ה- Agent 365 Dev Tools CLI בשלב הבא.

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

צור a365.config.json באופן ידני בתיקיית הפרויקט שלך ב- Cloud Run:

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

  "messagingEndpoint": "https://gcp-a365-agent-XXXX-uc.run.app/api/messages",

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

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

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

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

---

בנה סוכן Agent 365

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

• יצירת זהות סוכןב- Microsoft Entra ID
• רישום נקודת הקצה להעברת הודעות של Bot Framework
• יצירת משתמש הסוכן
• פרסום למשטחי Microsoft 365

Agent 365 CLI מטפל ברוב השלבים האלה באופן אוטומטי על סמך a365.config.json התצורה שלך.

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

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

אימות קישוריות של Cloud Run

שלח GET בקשה messagingEndpoint לערך מהכתובתa365.config.json:

curl https://gcp-a365-agent-XXXX.run.app/

גוף התגובה צריך לכלול:

GCP Agent is running.

בדוק יומני הפעלת ענן עבור הודעות Bot Framework נכנסות

באפשרותך לבדוק את יומן Google Cloud Log Explorer או להפעיל את:

gcloud run services logs read gcp-a365-agent --region <your region> --limit 50

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

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

בהתאם לסביבה שלך, השתמש ב:

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

עכשיו אפשר לשלוח הודעות ולאמת את היומנים שלכם ב- Cloud Run. לקבלת מידע נוסף, ראה מידע נוסף על בדיקת סוכנים באמצעות Microsoft Agent 365 SDK ואימות הפונקציונליות של סוכן שלך באמצעות כלי הבדיקות Agents Playground.

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

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

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

   כדי לבדוק את סוכן שלך באופן מקומי לפני הפריסה ב- Cloud Run, ודא .env שהקובץ שלך מכיל את האישורים הנכונים:

   # Start the agent locally
   node index.js
   

   הסוכן שלך זמין בכתובתhttp://localhost:8080. ניתן לבדוק את נקודת הסיום של התקינות:

   curl http://localhost:8080/
   

2. ביצוע שינויים בקוד

   לערוך index.js ולשמור את השינויים.

3. פריסה מחדש ל- Google Cloud Run

   gcloud run deploy gcp-a365-agent --source .
   

4. בדיקה וניטור

   בדוק באמצעות משטחי Agent 365 ועקוב אחר יומני Google Cloud Run.

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

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

עצה

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

לא ניתן להגיע לנקודת הקצה של ההודעות

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

• נקודת הסיום היא בדיוק:
  https://<cloud-run-url>/api/messages
• הפעלת ענן מאפשרת גישה לא מאומתת
• אין כללי חומת אש

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

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