Google Cloud Platform (GCP) पर तैनात Agent 365 एजेंट का निर्माण करें

सीखें कि कैसे Agent 365 CLI का उपयोग करके Microsoft Agent 365 SDK और .NET के साथ Google Cloud Run पर संचालित Agent 365 एजेंट को बनाएं, होस्ट करें, रजिस्टर करें और प्रकाशित करें। Microsoft Entra & ग्राफ एजेंट की पहचान, अनुमतियां और ब्लूप्रिंट प्रदान करता है, जबकि Google Cloud Run रनटाइम प्रदान करता है।

यदि आप केवल अपने एजेंट को उस कोड की ओर इंगित करना चाहते हैं जो AWS एंडपॉइंट के पीछे स्थित है, तो आपको केवल यह अतिरिक्त चरण करना होगा: गैर-Azure होस्टिंग के लिए कॉन्फ़िगर करें और फिर बाकी सभी चरणों का पालन करें Agent 365 डेवलपमेंट के साथ शुरुआत करें।

लक्ष्य

जानें कि Agent 365 और Microsoft 365 को 'कंट्रोल प्लेन' के रूप में कैसे उपयोग करें और:

• एजेंट रनटाइम को Google क्लाउड रन पर डिप्लॉय करें
• गैर-Azure होस्टिंग के लिए a365.config.json को कॉन्फ़िगर करें
• Entra ID में एजेंट ब्लूप्रिंट बनाएं
• OAuth2 और विरासत योग्य अनुमतियाँ कॉन्फ़िगर करें
• GCP को इंगित करने वाले Bot Framework संदेश एंडपॉइंट को पंजीकृत करें
• एजेंट पहचान + एजेंट उपयोगकर्ता बनाएं
• Microsoft 365 ऐप सरफेस पर प्रकाशित करें
• एंड-टू-एंड सहभागिता का परीक्षण करें

आवश्यकताएँ

शुरू करने से पहले, सुनिश्चित करें कि निम्नलिखित Azure/Microsoft 365, Google क्लाउड प्लेटफ़ॉर्म (GCP), और स्थानीय पर्यावरण संबंधी सभी आवश्यक पूर्वापेक्षाएँ पूरी की गई हों।

Azure / Microsoft 365 पूर्वापेक्षाएं

अपने Microsoft Entra टेनेंट एक्सेस की पुष्टि करें और पहचान, ब्लूप्रिंट बनाने, और अपने एजेंट को रजिस्टर करने के लिए ज़रूरी टूल्स इंस्टॉल करें।

• एक Microsoft Entra टेनेंट जिसमें:

  • अनुप्रयोग और एजेंट ब्लूप्रिंट बनाने की अनुमति या भूमिका (वैश्विक व्यवस्थापक या समकक्ष)
  • Microsoft Agent 365 तक प्रारंभिक पहुँच प्राप्त करने के लिए आपको Frontier पूर्वावलोकन कार्यक्रम में शामिल होना आवश्यक है।
  • एजेंट उपयोगकर्ता के लिए कम से कम एक Microsoft 365 लाइसेंस उपलब्ध होना आवश्यक है

• Azure CLI स्थापित और साइन इन किया गया है।

• Agent 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 API एक्सेस: अपने एजेंट के कॉन्फ़िगरेशन या अपने पसंदीदा मॉडल प्रदाता के आधार पर उपयुक्त सेवा चुनें:

  • OpenAI API कुंजी: अपनी OpenAI API कुंजी प्राप्त करें
  • Azure OpenAI: अपनी API की और एंडपॉइंट पाने के लिए Azure OpenAI रिसोर्स बनाएं और डिप्लॉय करें

Agent 365 एजेंट बनाएँ और क्लाउड रन में परिनियोजित करें

यह उदाहरण एक न्यूनतम Agent 365 एजेंट का उपयोग करता है जिसमें:

• GET अनुरोध का जवाब देता है /
• POST पर Bot Framework गतिविधियों को स्वीकार करता है /api/messages
• Agent 365 SDK के माध्यम से JWT प्रमाणीकरण का उपयोग करता है
• सरलता के लिए सभी कोड एक ही 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 का उपयोग करके सेवा को क्लाउड रन पर बनाएँ और चलाएँ। जब परिनियोजन समाप्त हो जाए, तो अपने messagingEndpoint के लिए सार्वजनिक URL ध्यान दें।

1. अपने प्रोजेक्ट को Google क्लाउड रन पर परिनियोजित करने के लिए निम्न आदेशों का उपयोग करें:

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

2. समाप्त होने पर, अपने एंडपॉइंट पर ध्यान दें:

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

   यह URL अगले चरण में Agent 365 Dev Tools CLI द्वारा उपयोग किया जाता है messagingEndpoint।

गैर-Azure होस्टिंग के लिए कॉन्फ़िगर करें

अपने Cloud Run प्रोजेक्ट फ़ोल्डर में a365.config.json को मैन्युअल रूप से बनाएं:

{
  "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	आपका Cloud Run URL + /api/messages
deploymentProjectPath	जहाँ स्टैम्पिंग .env होता है

---

Agent 365 एजेंट को बिल्ड करें

अपने एजेंट कोड को GCP एंडपॉइंट पर डिप्लॉय करने के बाद, Agent 365 Development Lifecycle में बताए गए शेष चरणों का पालन करें ताकि अपने Agent 365 एजेंट की सेटअप प्रक्रिया पूरी कर सकें। इस प्रक्रिया में निम्नलिखित चरण शामिल हैं:

• Microsoft Entra ID में एजेंट पहचान बनाना
• Bot Framework मैसेजिंग एंडपॉइंट को पंजीकृत करना
• एजेंट उपयोगकर्ता बनाना
• Microsoft 365 सतहों पर प्रकाशित करना

Agent 365 सीएलआई आपके a365.config.json कॉन्फ़िगरेशन के आधार पर इनमें से अधिकांश चरणों को स्वचालित रूप से संभालता है।

एजेंट का एंड-टू-एंड सत्यापन करें

इन जाँचों का उपयोग करें ताकि आप पुष्टि कर सकें कि आपका GCP-होस्टेड एजेंट पहुँच योग्य है, Bot Framework गतिविधियाँ प्राप्त करता है और Agent 365 प्लेटफार्मों पर सही ढंग से प्रतिक्रिया देता है।

क्लाउड रन कनेक्टिविटी सत्यापित करें

अपने a365.config.json से प्राप्त messagingEndpoint मूल्य पर GET अनुरोध भेजें:

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

उत्तर बॉडी में शामिल होना चाहिए:

GCP Agent is running.

Cloud Run में आने वाले Bot Framework संदेशों के लॉग देखें

आप Google क्लाउड लॉग एक्सप्लोरर की जांच कर सकते हैं या चला सकते हैं:

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

जब कोई संदेश आपके एजेंट तक पहुँचता है, तो लॉग प्रविष्टियाँ यह प्रॉम्प्ट देती हैं कि सर्वर ने उस गतिविधि को प्राप्त किया और Agent 365 SDK के माध्यम से संसाधित किया।

Agent 365 सतहों से एजेंट को टेस्ट करें

आपके परिवेश के आधार पर, उपयोग करें:

• एजेंट प्लेग्राउंड
• Teams (यदि प्रकाशित हो)
• एजेंट शेल

अब आप संदेश भेज सकते हैं और अपने Cloud Run लॉग्स की जांच कर सकते हैं। अधिक जानने के लिए देखें Microsoft Agent 365 SDK का उपयोग करके एजेंटों का परीक्षण करने और एजेंट Playground परीक्षण टूल के साथ अपने एजेंट की कार्यक्षमता को सत्यापित करने के तरीके के बारे में जानें।

डेवलपर कार्यप्रवाह

एक बार सेटअप पूरा हो जाने पर, पुनरावृत्त विकास के लिए इस कार्यप्रवाह का पालन करें:

1. स्थानीय रूप से परीक्षण करें (वैकल्पिक)

   क्लाउड रन में परिनियोजन से पहले अपने एजेंट का स्थानीय रूप से परीक्षण करने के लिए, सुनिश्चित करें कि आपकी .env फ़ाइल में सही साखपत्र हैं:

   # Start the agent locally
   node index.js
   

   आपका एजेंट http://localhost:8080 पर उपलब्ध है। आप स्वास्थ्य एंडपॉइंट का परीक्षण कर सकते हैं:

   curl http://localhost:8080/
   

2. अपने कोड परिवर्तन करें

   index.js को एडिट करें और अपने बदलाव सेव करें।

3. Google क्लाउड रन में फिर से तैनात करें

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

4. परीक्षण और निगरानी करें

   Agent 365 सतहों के माध्यम से परीक्षण करें और Google क्लाउड रन लॉग की निगरानी करें।

समस्‍या निवारण

इस अनुभाग का उपयोग Google Cloud Run पर अपने Agent 365 एजेंट को परिनियोजित और चलाते समय होने वाली सामान्य समस्याओं का निदान करने के लिए करें। यह आपको कनेक्टिविटी, कॉन्फ़िगरेशन और लाइसेंसिंग समस्याओं के समाधान जल्दी से लागू करने में मदद करता है।

टिप

Agent 365 समस्या निवारण मार्गदर्शिका में उच्च-स्तरीय समस्या निवारण अनुशंसाएँ, सर्वोत्तम प्रथाएँ, और Agent 365 विकास जीवनचक्र के प्रत्येक भाग के लिए समस्या निवारण सामग्री के लिंक शामिल हैं.

मैसेजिंग समापन बिंदु तक नहीं पहुंचा है

निम्न जानकारी जाँच करें:

• एंडपॉइंट ठीक यही है:
  https://<cloud-run-url>/api/messages
• Cloud Run अप्रमाणित पहुंच की अनुमति देता है
• कोई फ़ायरवॉल नियम नहीं

लाइसेंस आवंटन विफल है

एक मान्य Microsoft 365 फ्रंटियर लाइसेंस मैन्युअल रूप से असाइन करें, या यदि समर्थित हो तो बिना लाइसेंस वाले उपयोगकर्ता पथ का उपयोग करें।