بناء وكيل Agent 365 تم نشره في منصة Google Cloud (GCP)

تعلم كيفية بناء واستضافة وتسجيل ونشر وكيل Agent 365 يعمل على Google Cloud Run، باستخدام واجهة Agent 365. تقدم Microsoft Entra و Microsoft Graph هوية العامل والأذونات والنموذج، بينما يوفر Google Cloud Run بيئة التشغيل.

إذا كان كل ما تريد فعله هو توجيه الوكيل إلى التعليمات البرمجية الموجودة خلف نقطة نهاية GCP، فأنت تحتاج فقط إلى هذه الخطوة الإضافية: التكوين للاستضافة غير التابعة لـ 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 وتسجيل الدخول.

• تم تثبيت واجهة الأوامر CLI لعامل 365

المتطلبات الأساسية ل GCP

• مشروع GCP تم إنشاؤه

• تفعيل واجهة برمجة التطبيقات السحابية

• 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 برمجية.

• (اختياري) Node.js. يمكنك استخدام أي لغة لوكيلك. تستخدم هذه المقالة Node.js 18+ في الخطوات التالية.

• الوصول إلى واجهة برمجة تطبيقات النماذج الكبيرة (LLM): اختر الخدمة المناسبة بناء على تكوين وكيلك أو مزود النموذج المفضل لديك:

  • OpenAI API Key: احصل على مفتاح OpenAI API
  • Azure OpenAI: إنشاء مورد Azure OpenAI ونشره للحصول على مفتاح واجهة برمجة التطبيقات ونقطة النهاية

إنشاء عامل Agent 365 ونشره في Cloud Run

يستخدم هذا المثال الحد الأدنى من عامل Agent 365 الذي:

• يرد على GET /
• يقبل أنشطة إطار عمل الـ Bot على POST /api/messages
• يستخدم مصادقة JWT عبر Agent 365 SDK
• يحتوي على جميع التعليمات البرمجية في ملف واحد index.js للتبسيط

إنشاء مشروع

اتبع هذه الخطوات لبناء عامل Node.js الحد الأدنى الذي يعمل على Cloud Run ويقبل الأنشطة الخاصة بإطار عمل البوتات.

1. إنشاء دليل المشاريع

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

2. تهيئة مشروع Node.js

   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
   

   هذا الرابط هو المستخدم messagingEndpoint من قبل واجهة أدوات التطوير Agent 365 في الخطوة التالية.

تكوين استضافة خارج 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	رابط التشغيل السحابي الخاص بك + /api/messages
deploymentProjectPath	أين يتم الختم .env

---

إنشاء عامل Agent 365

بعد نشر التعليمات البرمجية للعامل الخاص بك إلى نقطة نهاية GCP، اتبع الخطوات المتبقية من "دورة حياة تطوير العامل 365" لإكمال إعداد عامل Agent 365 الخاص بك. تتضمن هذه العملية ما يلي:

• إنشاء هوية العامل في 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.

تحقق من سجلات Cloud Run للرسائل الواردة في إطار عمل البوت

يمكنك التحقق من Google Cloud Log Explorer أو تشغيل:

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

بعد أن تصل رسالة إلى العامل الخاص بك، سترى إدخالات السجل التي تشير إلى أن الخادم تلقى النشاط ومعالجته من خلال Agent 365 SDK.

ظهور وكيل الاختبار من Agent 365

اعتمادا على البيئة الخاصة بك، استخدم:

• ملعب الوكلاء
• الفرق (إذا نشرت)
• العميل شيل

يمكنك الآن إرسال رسائل والتحقق من سجلات 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 Surface وراقب سجلات Google Cloud Run.

استكشاف الأخطاء وإصلاحها

استخدم هذا القسم لتشخيص المشكلات الشائعة عند نشر عامل Agent 365 وتشغيله على Google Cloud Run. يساعدك على تطبيق إصلاحات لمشكلات الاتصال والتكوين والترخيص بسرعة.

نصيحة

يحتوي دليل استكشاف أخطاء العميل 365 على توصيات عالية المستوى لحل المشاكل، وأفضل الممارسات، وروابط لمحتوى استكشاف الأخطاء لكل جزء من دورة تطوير الوكيل 365.

لم يتم الوصول إلى نقطة نهاية المراسلة

تحقق من التفاصيل التالية:

• النهاية هي بالضبط:
  https://<cloud-run-url>/api/messages
• يتيح التشغيل السحابي الوصول غير المصادق
• لا توجد قواعد لجدار الحماية

فشل تعيين الترخيص

قم بتعيين ترخيص حدود Microsoft 365 صالح يدويا، أو استخدم مسار مستخدم غير مرخص إذا كان مدعوما.