Maak een Agent 365-agent die wordt geïmplementeerd in Google Cloud Platform (GCP)

Ontdek hoe u een Agent 365-agent maakt, host, registreert en publiceert, die wordt uitgevoerd op Google Cloud Run, met behulp van de Agent 365 CLI. Microsoft Entra & Graph levert de agentidentiteit, machtigingen en blueprint, terwijl Google Cloud Run de runtime verzorgt.

Als u uw agent alleen maar wilt verwijzen naar uw code achter een AWS-eindpunt, hebt u alleen deze extra stap nodig: Configureren voor niet-Azure-hosting en volg vervolgens alle andere stappen van Aan de slag met Agent 365-ontwikkeling.

Doelstellingen

Ontdek hoe u Agent 365 en Microsoft 365 als 'besturingsvlak' gebruikt en:

  • Implementeer agentruntime op Google Cloud Run
  • Configure a365.config.json voor niet-Azure-hosting
  • Maak Agent Blueprint aan in Entra ID
  • Configureer OAuth2 + erfelijke machtigingen
  • Registreer Bot Framework-berichteneindpunt dat verwijst naar GCP
  • Maak Agentidentiteit + Agentgebruiker
  • Publiceren op Microsoft 365 app-locaties
  • Test interacties end-to-end

Vereisten

Controleer of er aan de volgende vereisten voor Azure/Microsoft 365, Google Cloud Platform (GCP) en lokale omgevingen wordt voldaan.

Azure/vereisten van Microsoft 365

Bevestig uw Microsoft Entra-tenanttoegang en installeer de volgende tools om identiteiten en blueprints te maken en uw agent te registreren.

GCP-vereisten

  • GCP-project gemaakt

  • Cloud Run API ingeschakeld

  • gcloud SDK geïnstalleerd en geverificeerd

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

Vereisten voor lokale ontwikkelingsomgevingen

Maak een Agent 365-agent en implementeer deze naar Cloud Run

Dit voorbeeld gebruikt een minimale Agent 365-agent die:

  • Reageert op GET /
  • Accepteert Bot Framework-activiteiten op POST /api/messages
  • Gebruikt JWT-verificatie via de Agent 365 SDK
  • Bevat alle code in één enkel index.js-bestand voor de eenvoud

Project maken

Volg deze stappen om een minimale Node.js-agent te ondersteunen die wordt uitgevoerd op Cloud Run en Bot Framework-activiteiten accepteert.

  1. De projectmap aanmaken

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

  2. Initialiseer het Node-project

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

  3. index.js maken

       // 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}`));

Implementeren naar Google Cloud Run

Gebruik gcloud run deploy om de service te maken en uit te voeren op Cloud Run. Wanneer de implementatie is voltooid, noteert u de openbare URL voor uw messagingEndpoint.

  1. Gebruik de volgende opdrachten om uw project te implementeren in Google Cloud Run:

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

  2. Als u klaar bent, noteer u het eindpunt:

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

    Deze URL is de messagingEndpoint die wordt gebruikt door de Agent 365 Dev Tools CLI in de volgende stap.

Configure voor niet-Azure-hosting

Maak a365.config.json handmatig aan in uw Cloud Run-projectmap:

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

De volgende tabel vat belangrijke configuratievelden en hun doel samen.

Veld Betekenis
messagingEndpoint Uw Cloud Run URL + /api/messages
deploymentProjectPath Waar .env-stempelen plaatsvindt

Agent 365 agent maken

Na het implementeren van uw agentcode in uw GCP-eindpunt, volgt u de resterende stappen van de Agent 365-ontwikkelingslevenscyclus om de instelling van uw Agent 365-agent te voltooien. Dit proces omvat:

  • De agentidentiteit in Microsoft Entra ID maken
  • Het Bot Framework berichteneindpunt registreren
  • De agentgebruiker maken
  • Publiceren op Microsoft 365-locaties

De Agent 365 CLI verwerkt de meeste van deze stappen automatisch op basis van uw a365.config.json-configuratie.

Controleer de agent end-to-end

Gebruik deze controles om te bevestigen dat uw op GCP gehoste agent bereikbaar is, Bot Framework-activiteiten ontvangt en correct reageert op alle Agent 365-locaties.

Verifieer Cloud Run-connectiviteit

Stuur een GET-verzoek naar de messagingEndpoint-waarde van uw a365.config.json:

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

De responstekst moet het volgende bevatten:

GCP Agent is running.

Controleer Cloud Run-logboeken op binnenkomende Bot Framework-berichten

U kunt Google Cloud Log Explorer raadplegen of het volgende uitvoeren:

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

Nadat een bericht uw agent bereikt, ziet u logboekvermeldingen, die aangeven dat de server de activiteit via de Agent 365 SDK heeft ontvangen en verwerkt.

Test de agent vanaf Agent 365-locaties

Afhankelijk van uw omgeving gebruikt u:

  • Agenten van testomgeving
  • Teams (indien gepubliceerd)
  • Agent Shell

U kunt nu berichten sturen en uw Cloud Run-logboeken verifiëren. Voor meer informatie raadpleegt u Ontdek hoe u agenten test met de SDK voor Microsoft 365-agenten en valideer de functionaliteit van uw agent met de Agents Playground-testtool.

Ontwikkelaarswerkstroom

Zodra de installatie voltooid is, volgt u deze werkstroom voor iteratieve ontwikkeling:

  1. Test lokaal (optioneel)

    Om uw agent lokaal te testen voordat u hem uitrolt naar Cloud Run, zorgt u ervoor dat uw .env-bestand de juiste inloggegevens bevat:

    # Start the agent locally
node index.js

    Uw agent is beschikbaar op http://localhost:8080. U kunt het statuseindpunt testen:

    curl http://localhost:8080/

  2. Breng uw codewijzigingen aan

    Bewerk index.js en sla uw wijzigingen op.

  3. Implementeer opnieuw in Google Cloud Run

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

  4. Testen en monitoren

    Test via Agent 365-locaties en monitor Google Cloud Run-logboeken.

Probleemoplossing

Gebruik deze sectie om veelvoorkomende problemen te diagnosticeren bij het implementeren en uitvoeren van uw Agent 365-agent op Google Cloud Run. Het helpt u snel oplossingen toe te passen voor connectiviteit-, configuratie- en licentieproblemen.

Fooi

De Gids voor probleemoplossing in Agent 365 bevat aanbevelingen voor probleemoplossing op hoog niveau, best practices en links naar relevante probleemoplossingsinformatie voor elk onderdeel van de Agent 365-ontwikkelingscyclus.

Het berichteneindpunt wordt niet bereikt

Controleer de volgende gegevens:

  • Het eindpunt is precies:
    https://<cloud-run-url>/api/messages
  • Cloud Run maakt niet-geverifieerde toegang mogelijk
  • Geen firewallregels

Licentietoewijzing mislukt

Wijs handmatig een geldige Microsoft 365-frontierlicentie toe, of gebruik een niet-gelicentieerd gebruikerspad als dat ondersteund wordt.

  • Last updated on