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

هام

يجب أن تكون جزءا من برنامج معاينة الحدود للحصول على وصول مبكر إلى Microsoft Agent 365. Frontier تربطك مباشرة بأحدث ابتكارات الذكاء الاصطناعي من Microsoft. تخضع المعاينات الحدودية لشروط المعاينة الحالية لاتفاقيات العملاء. نظرًا لأن هذه الميزات لا تزال قيد التطوير، فقد يتغير توفرها وقدراتها بمرور الوقت.

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

إذا كان كل ما تريد فعله هو توجيه وكيل الكود الموجود خلف نقطة نهاية AWS، فأنت تحتاج فقط إلى هذه الخطوة الإضافية: التكوين لاستضافة غير Azure ثم اتباع جميع الخطوات الأخرى من دورة حياة تطوير Agent 365.

الاهداف

تعلم كيفية استخدام Agent 365 وMicrosoft 365 ك 'مستوى التحكم' و:

نشر وقت تشغيل الوكيل على Google Cloud Run
Configure a365.config.json for non-Azure hosting
إنشاء مخطط وكيل في Entra ID
تكوين OAuth2 + الأذونات القابلة للوراثة
إطار عمل تسجيل البوتات لنقطة نهاية الرسائل تشير إلى GCP
إنشاء هوية الوكيل + مستخدم الوكيل
النشر على أسطح تطبيقات Microsoft 365
تفاعلات الاختبار من طرف إلى طرف

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

قبل أن تبدأ، تأكد من استيفاء المتطلبات التالية ل Azure / Microsoft 365، ومنصة Google Cloud (GCP)، والبيئة المحلية.

Azure / Microsoft 365 prerequisites

تأكد من وصول مستأجر 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 Code
(اختياري) Node.js. يمكنك استخدام أي لغة لوكيلك. تستخدم هذه المقالة العقدة 18+ في الخطوات التالية.
الوصول إلى واجهة برمجة تطبيقات النماذج الكبيرة (LLM): اختر الخدمة المناسبة بناء على تكوين وكيلك أو مزود النموذج المفضل لديك:
- OpenAI API Key: احصل على مفتاح OpenAI API
- Azure OpenAI: إنشاء مورد Azure OpenAI ونشره للحصول على مفتاح واجهة برمجة التطبيقات ونقطة النهاية

إنشاء ونشر وكيل 365 إلى تشغيل السحابة

يستخدم هذا المثال وكيلا مثاليا أدنى:

يرد على GET /
قبول أنشطة إطار عمل الروبوتات على POST /api/messages

إنشاء مشروع

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

إنشاء دليل المشاريع
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

تهيئة مشروع العقدة

npm init -y
npm install express body-parser

خلق index.js

const express = require("express");
const bodyParser = require("body-parser");

const app = express();
app.use(bodyParser.json());

app.get("/", (req, res) => {
res.status(200).send("GCP Agent is running.");
});

// Bot Framework Activity Handler
app.post("/api/messages", (req, res) => {
console.log("Received activity:", JSON.stringify(req.body, null, 2));

// Echo activity
const reply = {
   type: "message",
   text: `You said: ${req.body?.text}`
};

res.status(200).send(reply);
});

const port = process.env.PORT || 8080;
app.listen(port, () => console.log("Server listening on port " + port));

النشر على Google Cloud Run

استخدم gcloud run deploy لبناء وتشغيل الخدمة على Cloud Run، ثم قم بملاحظة عنوان URL العام ل .messagingEndpoint

استخدم الأوامر التالية لنشر مشروعك على Google Cloud Run:

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

عند الانتهاء، لاحظ نقطة النهاية الخاصة بك:
```
https://gcp-a365-agent-XXXX-uc.run.app
```
هذا الرابط هو المستخدم messagingEndpoint من قبل واجهة أدوات التطوير Agent 365 في الخطوة التالية.

Configure for Non-Azure Hosting

أنشئ a365.config.json في مجلد مشروع Cloud Run الخاص بك عن طريق تشغيل a365 config init:

{
  "tenantId": "YOUR_TENANT_ID",
  "subscriptionId": "YOUR_AZURE_SUBSCRIPTION_ID",
  "resourceGroup": "a365-gcp-demo",
  "location": "westus",
  "environment": "prod",

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

  "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`
`"needDeployment"=false`	يقول لي "أنا أستضيف خادمي الخاص؛ لا تنشر إلى أزور'
`deploymentProjectPath`	أين `.env` يحدث الختم

وكيل Build Agent 365

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

تحقق من الوكيل من البداية إلى الطرف

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

بعد وصول رسالة إلى وكيلك، يجب أن ترى:

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

وكيل الاختبار من أسطح العامل 365

اعتمادا على بيئتك:

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

يمكنك الآن إرسال رسائل والتحقق من سجلات Cloud Run الخاصة بك. ويمكنك أيضا تعلم كيفية اختبار الوكلاء باستخدام Microsoft Agent 365 SDK والتحقق من وظائف وكيلك باستخدام أداة اختبار Agents Playground.

سير عمل المطور

بمجرد اكتمال الإعداد، اتبع هذا السير للتطوير التكراري:

غير رمز وكيلك

قم بإجراء تغييرات الكود، واحفظ الجهاز، واختبر محليا قبل النشر.

إعادة النشر إلى Google Cloud Run

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

الاختبار والمراقبة

اختبر عبر Agent 365 Surface وراقب سجلات Google Cloud Run.

إشعار

هويتك، مخططك، نقطة نهاية البوت، والصلاحيات لا تحتاج إلى إعادة إنشائها.

Troubleshooting

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

نقطة نهاية الرسائل لم يتم إصابتها

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

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

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

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

الحصول على المساعدة

إذا واجهت مشاكل في واجهة Agent 365 غير مغطاة في قسم استكشاف الأخطاء هذا، راجع المشاكل المفتوحة على GitHub أو أنشئ مشكلة جديدة.

خيارات مساعدة إضافية

فكر في ما يلي للعثور على المساعدة:

مراجعة كود العينة والتوثيق في العينات
راجع أو قدم مشاكل أخرى في GitHub في مستودع SDK ذي الصلة:

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-01-10