Δημιουργήστε έναν παράγοντα Agent 365 που αναπτύσσεται στην Πλατφόρμα Google Cloud (GCP)

Μάθετε πώς μπορείτε να δημιουργήσετε, να φιλοξενήσετε, να καταχωρήσετε και να δημοσιεύσετε έναν παράγοντα Agent 365 που εκτελείται στο Google Cloud Run, χρησιμοποιώντας το Agent 365 CLI. Το Microsoft Entra & Graph παρέχει την ταυτότητα, τα δικαιώματα και το Blueprint του παράγοντα, ενώ το Google Cloud Run παρέχει το περιβάλλον εκτέλεσης.

Αν το μόνο που θέλετε να κάνετε είναι να κατευθύνετε τον Agent 365 σας στον κώδικά σας που βρίσκεται πίσω από ένα τελικό σημείο 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 (GCP) και το τοπικό περιβάλλον.

Προαπαιτούμενα για το Azure / Microsoft 365

Βεβαιωθείτε ότι έχετε πρόσβαση στον μισθωτή Microsoft Entra και εγκαταστήστε τα ακόλουθα εργαλεία για να δημιουργήσετε ταυτότητες, δομές προγράμματος και να καταχωρίσετε τον παράγοντα σας.

Ένας μισθωτής του Microsoft Entra με:
- Δικαιώματα ή ρόλος για τη δημιουργία εφαρμογών και πρότυπων παραγόντων (Καθολικός διαχειριστής ή ισοδύναμο)
- Πρέπει να είστε μέλος του προγράμματος έκδοσης προεπισκόπησης 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 18+ στα παρακάτω βήματα.
Πρόσβαση LLM API: Επιλέξτε την κατάλληλη υπηρεσία με βάση τη διαμόρφωση του παράγοντα σας ή τον προτιμώμενο πάροχο μοντέλου:
- Κλειδί OpenAI API: Αποκτήστε το κλειδί OpenAI API
- Azure OpenAI: Δημιουργήστε και αναπτύξτε έναν πόρο Azure OpenAI για να λάβετε το κλειδί 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.

Δημιουργήστε τον φάκελο του έργου
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Αρχικοποιήστε το έργο Node

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

Δημιουργία 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.

Χρησιμοποιήστε τις ακόλουθες εντολές για να αναπτύξετε το έργο σας στο 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
```
Αυτή είναι η διεύθυνση 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 του Cloud Run + `/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

Ανάλογα με το περιβάλλον σας, χρησιμοποιήστε:

Agents Playground
Teams (εάν έχει δημοσιευτεί)
Παράγοντας Shell

Τώρα μπορείτε να στέλνετε μηνύματα και να επαληθεύετε τα αρχεία καταγραφής του Cloud Run σας. Για να μάθετε περισσότερα, δείτε το Πώς να δοκιμάσετε παράγοντες χρησιμοποιώντας το Microsoft Agent 365 SDK και να επικυρώσετε τη λειτουργικότητα του παράγοντα σας με το εργαλείο δοκιμής Agents Playground.

Ροή εργασίας προγραμματιστή

Μόλις ολοκληρωθεί η ρύθμιση, ακολουθήστε αυτήν τη ροή εργασίας για επαναληπτική ανάπτυξη:

Δοκιμάστε τοπικά (προαιρετικά)

Για να δοκιμάσετε τον παράγοντα σας τοπικά πριν από την ανάπτυξη στο Cloud Run, βεβαιωθείτε ότι το αρχείο .env περιέχει τα σωστά διαπιστευτήρια:
```
# Start the agent locally
node index.js
```
Ο παράγοντας σας είναι διαθέσιμος στη διεύθυνση http://localhost:8080. Μπορείτε να δοκιμάσετε το τελικό σημείο εύρυθμης λειτουργίας:
```
curl http://localhost:8080/
```
Κάντε τις αλλαγές στον κώδικά σας

Επεξεργαστείτε το index.js και αποθηκεύστε τις αλλαγές σας.
Αναπτύξτε ξανά στο Google Cloud Run
```
gcloud run deploy gcp-a365-agent --source .
```
Έλεγχος και παρακολούθηση

Δοκιμάστε μέσω πλατφορμών Agent 365 και παρακολουθήστε τα αρχεία καταγραφής του Google Cloud Run.

Αντιμετώπιση προβλημάτων

Χρησιμοποιήστε αυτήν την ενότητα για να διαγνώσετε συνήθη προβλήματα κατά την ανάπτυξη και την εκτέλεση του Agent 365 παράγοντα στο Google Cloud Run. Σας βοηθά να διορθώνετε άμεσα προβλήματα συνδεσιμότητας, διαμόρφωσης και αδειοδότησης.

Φιλοδώρημα

Ο Οδηγός αντιμετώπισης προβλημάτων του Agent 365 περιλαμβάνει συστάσεις αντιμετώπισης προβλημάτων υψηλού επιπέδου, βέλτιστες πρακτικές και συνδέσμους για περιεχόμενο αντιμετώπισης προβλημάτων για κάθε μέρος του κύκλου ζωής ανάπτυξης του Agent 365.

Δεν είναι δυνατή η πρόσβαση στο τελικό σημείο ανταλλαγής μηνυμάτων

Ελέγξτε τα παρακάτω στοιχεία:

Το τελικό σημείο είναι ακριβώς:
https://<cloud-run-url>/api/messages
Το Cloud Run επιτρέπει την πρόσβαση χωρίς έλεγχο ταυτότητας
Δεν υπάρχουν κανόνες τείχους προστασίας

Η ανάθεση άδειας χρήσης απέτυχε

Εκχωρήστε με μη αυτόματο τρόπο μια έγκυρη άδεια χρήσης του Microsoft 365 Frontier ή χρησιμοποιήστε τη διεργασία για χρήστες χωρίς άδεια, εφόσον υποστηρίζεται.

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-07-30