Baue einen Agent 365-Agenten, der in der Google Cloud Platform (GCP) bereitgestellt wird

Lernen Sie, wie Sie einen Agent-365-Agenten, der auf Google Cloud Run läuft, erstellt, hostet, registriert und veröffentlicht, mithilfe der Agent 365 CLI. Microsoft Entra & Graph stellt die Agentidentität, Berechtigungen und Blueprint bereit, während Google Cloud Run die Laufzeit bereitstellt.

Wenn du deinen Agenten nur auf deinen Code hinter einem AWS-Endpunkt verweisen willst, brauchst du nur diesen zusätzlichen Schritt: Für Nicht-Azure-Hosting konfigurieren und dann alle anderen Schritte aus dem Agent 365 Development Lifecycle befolgen.

Ziele

Erfahren Sie, wie Sie Agent 365 und Microsoft 365 als "Steuerungsebene" verwenden und:

• Agent-Runtime auf Google Cloud Run bereitstellen
• Konfigurieren von a365.config.json für das Hosting ohne Azure
• Agent-Blueprint in Entra ID erstellen
• Konfigurieren Sie OAuth2 + vererbbare Berechtigungen
• Richten Sie den Bot Framework Messaging-Endpunkt ein, der auf GCP verweist.
• Agenten-Identität erstellen + Agent-Nutzer
• Veröffentlichen in den App-Oberflächen von Microsoft 365
• Interaktionen End-to-End testen

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass die folgenden Azure/Microsoft 365, Google Cloud Platform (GCP) und lokale Umgebungsvoraussetzungen erfüllt sind.

voraussetzungen für Azure/Microsoft 365

Bestätigen Sie ihren Microsoft Entra Mandantenzugriff, und installieren Sie die folgenden Tools, um Identitäten, Blueprints zu erstellen und Ihren Agent zu registrieren.

• Ein Microsoft Entra Mandant mit:

  • Berechtigung oder Rolle zur Erstellung von Anwendungen und Agenten-Blueprints (Global Administrator oder gleichwertig)
  • Sie müssen Teil des Frontier-Vorschauprogramms sein, um frühzeitigen Zugriff auf Microsoft Agent 365 zu erhalten.
  • Mindestens eine Microsoft 365 Lizenz für den Agent-Benutzer verfügbar

• Azure CLI installiert und angemeldet.

• Agent 365 CLI installiert

GCP-Voraussetzungen

• GCP-Projekt gegründet

• Cloud Run API aktiviert

• gcloud SDK installiert und authentifiziert

  gcloud auth login
  gcloud config set project <GCP_PROJECT_ID>
  gcloud config set run/region us-central1   # or your preferred region
  

Voraussetzungen für das lokale Entwicklungsumfeld

• Code-Editor: Ein beliebiger Code-Editor Ihrer Wahl. Visual Studio Code wird empfohlen.

• (Optional) Node.js. Du kannst für deinen Agenten jede beliebige Sprache verwenden. Dieser Artikel verwendet Node.js 18+ in den folgenden Schritten.

• LLM-API-Zugriff: Wählen Sie den passenden Dienst basierend auf der Konfiguration Ihres Agenten oder Ihres bevorzugten Modellanbieters:

  • OpenAI-API-Schlüssel: So erhalten Sie Ihren OpenAI-API-Schlüssel
  • Azure OpenAI: Erstellen und Bereitstellen einer Azure OpenAI-Ressource, um Ihren API-Schlüssel und Endpunkt zu erhalten

Erstellen und Bereitstellen des Agent 365-Agents für Cloud Run

In diesem Beispiel wird ein minimaler Agent 365-Agent verwendet, der:

• Reagiert auf GET /
• Akzeptiert Bot-Framework-Aktivitäten auf POST /api/messages
• Verwendet die JWT-Authentifizierung über das Agent 365 SDK
• Enthält den gesamten Code in einer einzelnen index.js Datei aus Gründen der Einfachheit

Projekt erstellen

Befolgen Sie diese Schritte, um einen Minimal-Node.js-Agenten zu unterstützen, der auf Cloud Run läuft und Bot-Framework-Aktivitäten akzeptiert.

1. Erstellen Sie das Projektverzeichnis

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

2. Initialisieren Sie das Node-Projekt

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

3. Erstellen Sie 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}`));
   

Deployen auf Google Cloud Run

Verwenden Sie gcloud run deploy, um den Dienst in Cloud Run zu erstellen und auszuführen. Wenn die Bereitstellung abgeschlossen ist, notieren Sie sich die öffentliche URL für Ihre messagingEndpoint.

1. Verwenden Sie folgende Befehle, um Ihr Projekt in Google Cloud Run zu deployen:

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

2. Wenn Sie fertig sind, notieren Sie Ihren Endpunkt:

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

   Diese URL wird messagingEndpoint im nächsten Schritt von der Agent 365 Dev Tools CLI verwendet.

Konfigurieren für Nicht-Azure Hosting

Erstellen Sie a365.config.json in Ihrem Cloud Run-Projektordner, indem Sie a365 config initausführen:

{
  "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"
}

Die folgende Tabelle fasst wichtige Konfigurationsfelder und deren Zweck zusammen.

Build Agent 365 Agent

Nachdem Sie Ihren Agent-Code auf Ihrem GCP-Endpunkt bereitgestellt haben, führen Sie die verbleibenden Schritte aus dem Agent 365 Development Lifecycle aus, um die Einrichtung Ihres Agent 365-Agents abzuschließen. DieserProzess umfasst::

• Erstellen der Agentidentität in Microsoft Entra ID
• Registrieren des Bot Framework-Messagingendpunkts
• Erstellen des Agent-Benutzers
• Veröffentlichen auf Microsoft 365 Oberflächen

Der Agent 365 CLI verarbeitet die meisten dieser Schritte automatisch basierend auf Ihrer a365.config.json Konfiguration.

Verifizieren Sie den Agenten von Anfang bis Ende

Verwenden Sie diese Überprüfungen, um zu bestätigen, dass Ihr von GCP gehosteter Agent erreichbar ist, Bot Framework-Aktivitäten empfängt und auf agent 365-Oberflächen korrekt reagiert.

Cloud Run-Konnektivität überprüfen

Senden Sie eine GET-Anfrage an den messagingEndpoint-Wert von Ihrem a365.config.json:

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

Der Antwortinhalt sollte enthalten:

GCP Agent is running.

Überprüfen Sie die Cloud Run-Logs auf eingehende Bot-Framework-Nachrichten

Sie können den Google Cloud Log Explorer prüfen oder Folgendes ausführen:

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

Nachdem eine Nachricht Ihren Agenten erreicht hat, werden Protokolleinträge angezeigt, die darauf hinweisen, dass der Server die Aktivität über das Agent-365-SDK empfangen und verarbeitet hat.

Agent von Agent 365-Oberflächen aus testen

Verwenden Sie je nach Ihrer Umgebung Folgendes:

• Agenten Spielplatz
• Teams (sofern veröffentlicht)
• Agent-Shell

Du kannst jetzt Nachrichten senden und deine Cloud Run-Protokolle überprüfen. Weitere Informationen finden Sie unter Erfahren Sie, wie Sie Agenten mit dem Microsoft Agent 365 SDK testen und wie Sie die Funktionalität Ihres Agenten mit dem Agents Playground Testing Tool validieren können.

Entwickler-Arbeitsablauf

Sobald die Einrichtung abgeschlossen ist, folgen Sie diesem Workflow für die iterative Entwicklung:

1. Lokal testen (optional)

   Um Ihren Agent vor der Bereitstellung in Cloud Run lokal zu testen, stellen Sie sicher, dass Ihre .env Datei die richtigen Anmeldeinformationen enthält:

   # Start the agent locally
   node index.js
   

   Ihr Agent ist unter http://localhost:8080 erreichbar. Sie können den Überwachungsendpunkt testen:

   curl http://localhost:8080/
   

2. Nehmen Sie Ihre Codeänderungen vor

   Bearbeiten index.js und speichern Sie Ihre Änderungen.

3. Neuausrollen in Google Cloud Run

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

4. Testen und überwachen

   Teste über Agent 365 Surfaces und überwache die Google Cloud Run-Logs.

Problembehandlung

Verwenden Sie diesen Abschnitt, um häufige Probleme beim Bereitstellen und Ausführen Ihres Agent 365-Agents auf Google Cloud Run zu diagnostizieren. Sie können schnell Korrekturen für Konnektivitäts-, Konfigurations- und Lizenzierungsprobleme anwenden.

Der Messagingendpunkt wurde nicht erreicht.

Überprüfen Sie die folgenden Details:

• Der Endpunkt ist genau:
  https://<cloud-run-url>/api/messages
• Cloud Run ermöglicht unauthentifizierten Zugriff
• Keine Firewall-Regeln

Lizenzübertragung fehlschlägt

Weisen Sie eine gültige Microsoft 365 Grenzlizenz manuell zu, oder verwenden Sie bei Unterstützung einen nicht lizenzierten Benutzerpfad.