สร้างเอเจนต์ Agent 365 ที่ปรับใช้บน Google Cloud Platform (GCP)

ดูวิธีสร้าง โฮสต์ ลงทะเบียน และเผยแพร่เอเจนต์ Agent 365 ที่ทํางานบน Google Cloud Run โดยใช้ Agent 365 CLI Microsoft Entra & Graph ให้ข้อมูลประจำตัว สิทธิ์ และ Blueprint ของเอเจนต์ ในขณะที่ Google Cloud Run ให้รันไทม์

หากคุณต้องการเพียงแค่ชี้เอเจนต์ของคุณไปยังโค้ดที่อยู่หลังจุดเชื่อมต่อ AWS คุณจะต้องทำขั้นตอนเพิ่มเติมนี้: กำหนดค่าสำหรับโฮสติ้งที่ไม่ใช่ Azure จากนั้นดำเนินการตามขั้นตอนอื่น ๆ ทั้งหมดจาก เริ่มต้นใช้งานการพัฒนา Agent 365

เป้าหมาย

เรียนรู้วิธีใช้ Agent 365 และ Microsoft 365 เป็น 'ชั้นการควบคุม' และ:

  • ปรับใช้รันไทม์ของเอเจนต์บน Google Cloud Run
  • กําหนดค่า a365.config.json สำหรับโฮสติ้งที่ไม่ใช่ Azure
  • สร้าง Blueprint เอเจนต์ใน Entra ID
  • กําหนดค่า OAuth2 + สิทธิ์ที่สืบทอดได้
  • ลงทะเบียนจุดเชื่อมต่อการส่งข้อความของ Bot Framework ที่ชี้ไปที่ GCP
  • สร้างข้อมูลประจำตัวเอเจนต์ + ผู้ใช้เอเจนต์
  • เผยแพร่ไปยังพื้นที่แอปใน Microsoft 365
  • ทดสอบการโต้ตอบแบบครบวงจร

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น โปรดตรวจสอบให้แน่ใจว่าข้อกำหนดเบื้องต้นของ Azure / Microsoft 365, Google Cloud Platform (GCP) และสภาพแวดล้อมภายในเครื่องครบถ้วน

ข้อกำหนดเบื้องต้นของ Azure / Microsoft 365

ยืนยันการเข้าถึงผู้เช่า Microsoft Entra ของคุณ และติดตั้งเครื่องมือต่อไปนี้เพื่อสร้างข้อมูลประจำตัว Blueprint และลงทะเบียนเอเจนต์ของคุณ

  • ผู้เช่า Microsoft Entra ที่มี:

    • สิทธิ์หรือบทบาทในการสร้างแอปพลิเคชันและ Blueprint เอเจนต์ (ผู้ดูแลระบบส่วนกลางหรือเทียบเท่า)
    • คุณต้องเข้าร่วมโปรแกรมพรีวิว Frontierเพื่อรับสิทธิ์เข้าถึง Microsoft Agent 365 ล่วงหน้า
    • ต้องมีสิทธิการใช้งาน Microsoft 365 อย่างน้อยหนึ่งรายการสำหรับผู้ใช้เอเจนต์

  • ติดตั้ง Azure CLI และลงชื่อเข้าใช้

  • ติดตั้ง Agent 365 CLI

ข้อกำหนดเบื้องต้นของ GCP

  • สร้างโครงการ GCP

  • เปิดใช้งาน Cloud Run 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 คุณสามารถใช้ภาษาโปรแกรมใดก็ได้สำหรับเอเจนต์ของคุณ บทความนี้ใช้ Node.js เวอร์ชัน 18 ขึ้นไปในขั้นตอนต่อไปนี้

  • การเข้าถึง LLM API: เลือกบริการที่เหมาะสมตามการกำหนดค่าของเอเจนต์ของคุณหรือผู้ให้บริการโมเดลที่คุณต้องการ:

สร้างและปรับใช้เอเจนต์ Agent 365 บน Cloud Run

ตัวอย่างนี้ใช้เอเจนต์ Agent 365 ขั้นต่ำที่:

  • ตอบกลับ GET /
  • ยอมรับกิจกรรม Bot Framework ผ่าน POST /api/messages
  • ใช้การรับรองความถูกต้อง JWT ผ่าน Agent 365 SDK
  • มีโค้ดทั้งหมดในไฟล์ index.js ไฟล์เดียวเพื่อความสะดวก

สร้างโครงการ

ทําตามขั้นตอนเหล่านี้เพื่อสร้างโครงสร้างเอเจนต์ Node.js แบบขั้นต่ำที่ทํางานบน Cloud Run และยอมรับกิจกรรม Bot Framework

  1. สร้างไดเรกทอรีโครงการ

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

  2. เริ่มต้นโปรเจกต์ Node

    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 ที่จะใช้โดย CLI ของ Agent 365 Dev Tools ในขั้นตอนถัดไป

กําหนดค่าสําหรับโฮสติ้งที่ไม่ใช่ 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 Cloud Run URL ของคุณ + /api/messages
deploymentProjectPath โดยมีการประทับ .env

สร้างเอเจนต์ Agent 365

หลังจากปรับใช้โค้ดของเอเจนต์ของคุณไปยังจุดเชื่อมต่อของ GCP แล้ว ให้ดำเนินขั้นตอนที่เหลือตาม วงจรชีวิตการพัฒนา Agent 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 สำหรับข้อความ Bot Framework ขาเข้า

คุณสามารถตรวจสอบ Google Cloud Log Explorer หรือเรียกใช้:

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 และตรวจสอบฟังก์ชันการทำงานของเอเจนต์ของคุณด้วยเครื่องมือทดสอบ สนามทดลองเอเจนต์

เวิร์กโฟลว์ของนักพัฒนา

เมื่อการตั้งค่าเสร็จสมบูรณ์ ให้ปฏิบัติตามเวิร์กโฟลว์นี้สำหรับการพัฒนาแบบวนซ้ำ:

  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

กำลังแก้ไขปัญหา

ใช้ส่วนนี้เพื่อวินิจฉัยปัญหาทั่วไปเมื่อปรับใช้และเรียกใช้เอเจนต์ Agent 365 บน Google Cloud Run ซึ่งช่วยให้คุณแก้ไขปัญหาการเชื่อมต่อ การกำหนดค่า และการให้สิทธิการใช้งานได้อย่างรวดเร็ว

เคล็ดลับ

คู่มือการแก้ไขปัญหา Agent 365 ประกอบด้วยคำแนะนำการแก้ไขปัญหาระดับสูง แนวทางปฏิบัติที่ดีที่สุด และลิงก์ไปยังเนื้อหาการแก้ไขปัญหาสำหรับแต่ละส่วนของวงจรการพัฒนา Agent 365

ไม่ถึงจุดเชื่อมต่อการส่งข้อความ

ตรวจสอบรายละเอียดต่อไปนี้:

  • จุดเชื่อมต่อคือ:
    https://<cloud-run-url>/api/messages
  • Cloud Run อนุญาตให้เข้าถึงโดยไม่ผ่านการรับรองความถูกต้อง
  • ไม่มีกฎของไฟร์วอลล์

การมอบหมายสิทธิ์การใช้งานล้มเหลว

กำหนดสิทธิการใช้งาน Microsoft 365 Frontier ที่ถูกต้องด้วยตนเอง หรือใช้วิธีสำหรับผู้ใช้ที่ไม่มีสิทธิการใช้งาน หากระบบรองรับ

  • Last updated on