Freigeben über

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

Von Bedeutung

Sie müssen Teil des Frontier-Vorschauversionsprogramms sein, um Vorabzugriff auf Microsoft Agent 365 zu erhalten. Frontier verbindet Sie direkt mit den neuesten KI-Innovationen von Microsoft. Frontier-Vorschauversionen unterliegen den bestehenden Vorschauversionsbedingungen Ihrer Kundenvereinbarungen. Da sich diese Funktionen noch in der Entwicklung befinden, können sich ihre Verfügbarkeit und Merkmale im Laufe der Zeit ändern.

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 Agentenidentität, Berechtigungen und den 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

Lernen Sie, wie Sie Agent 365 und Microsoft 365 als 'Kontrollebene' verwenden und:

  • Agent-Runtime auf Google Cloud Run bereitstellen
  • Configure a365.config.json for non-Azure hosting
  • Agent Blueprint in Entra ID erstellen
  • Konfigurieren Sie OAuth2 + vererbbare Berechtigungen
  • Register Bot Framework Messaging-Endpunkt zeigt auf GCP
  • Agenten-Identität erstellen + Agent-Nutzer
  • Veröffentlichen auf Microsoft 365 App-Oberflächen
  • Testwechselwirkungen End-to-End-Verfahren

Voraussetzungen

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

Azure / Microsoft 365 prerequisites

Bestätigen Sie Ihren Microsoft Entra-Tenant-Zugriff und installieren Sie die folgenden Tools, um Identitäten, Baupläne zu erstellen und Ihren Agenten zu registrieren.

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 Knoten 18+ in den folgenden Schritten.

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

Erstellen und Deployen des Agenten 365 Agents in Cloud Run

Dieses Beispiel verwendet einen minimalen Beispielagenten, der:

  • Antwortet auf GET /
  • Akzeptiert Bot-Framework-Aktivitäten auf POST /api/messages

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 body-parser

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

Deployen auf Google Cloud Run

Nutze gcloud run deploy es, um den Dienst in Cloud Run zu erstellen und zu betreiben, und notiere dann die öffentliche URL für deinen 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.

Configure for Non-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.

Feld Bedeutung
messagingEndpoint Deine Cloud-URL + /api/messages
"needDeployment"=false Sagt zu CLI: 'Ich hoste meinen eigenen Server; don't deploy to Azure'
deploymentProjectPath Wo .env das Stempeln stattfindet

Build Agent 365 Agent

Sobald Ihr Agentencode an einem AWS-Endpunkt läuft, folgen Sie den verbleibenden Schritten aus dem Entwicklungszyklus von Agent 365 , um Ihren Agent-365-Agenten einzurichten.

Verifizieren Sie den Agenten von Anfang bis Ende

Nutzen Sie diese Prüfungen, um sicherzustellen, dass Ihr GCP-gehosteter Agent erreichbar ist, Bot-Framework-Aktivitäten empfängt und korrekt auf Agent-365-Oberflächen 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 Antwortkörper 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 Makler erreicht hat, sollten Sie sehen:

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

Testmittel von Agent-365-Oberflächen

Je nach Umgebung:

  • Agents Playground
  • Teams (falls veröffentlicht)
  • Agent Shell

Du kannst jetzt Nachrichten senden und deine Cloud Run-Protokolle überprüfen. Außerdem können Sie lernen, wie man Agenten mit dem Microsoft Agent 365 SDK testet und die Funktionalität Ihres Agenten mit dem Testwerkzeug Agents Playground validiert.

Entwickler-Workflow

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

  1. Ändere deinen Agentencode

    Mach deine Code-Änderungen, speichere und teste lokal, bevor du es bereitstellst.

  2. Neuausrollen in Google Cloud Run

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

  3. Testen und überwachen

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

    Hinweis

    Ihre Identität, Ihr Blueprint, Ihr Bot-Endpunkt und Ihre Berechtigungen müssen NICHT neu erstellt werden.

Problembehandlung

Nutzen Sie diesen Abschnitt, um häufige Probleme beim Bereitstellen und Betrieb Ihres Agent 365-Agenten auf Google Cloud Run zu diagnostizieren und schnell Lösungen für Verbindungs-, Konfigurations- und Lizenzprobleme anzuwenden.

Der Messaging-Endpunkt wird nicht getroffen

Ü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 manuell eine gültige Microsoft 365 Frontier-Lizenz zu oder verwenden Sie einen nicht lizenzierten Benutzerpfad, falls dies unterstützt wird.

Hilfe erhalten

Weitere Hilfeoptionen

Betrachten Sie Folgendes, um Hilfe zu finden:

  • Last updated on