Bygg en Agent 365-agent distribuert på Google Cloud Platform (GCP)

Finn ut hvordan du bygger, drifter, registrerer og publiserer en Agent 365-agent som kjører på Google Cloud Run, ved hjelp av Agent 365 CLI. Microsoft Entra & Graph byr på agentidentiteten, tillatelsene og malen, mens Google Cloud Run står for kjøretiden.

Hvis du bare vil rette agenten mot koden som ligger bak et Amazon Web Services-endepunkt, trenger du bare dette ekstra trinnet: Konfigurer for vertstjeneste uten Azure og følg deretter alle andre trinn fra Kom i gang med Agent 365-utvikling.

Mål

Finn ut hvordan du bruker Agent 365 og Microsoft 365 som kontrollplan og gjør følgende:

Distribuer agentkjøretiden på Google Cloud Run
Konfigurer a365.config.json for vertstjeneste uten Azure
Opprett Agent Blueprint i Entra ID
Konfigurer OAuth2 + tillatelser som kan arves
Registrer meldingsendepunktet for Bot Framework som peker mot GCP
Opprett agentidentitet og agentbruker
Publiser på Microsoft 365-appoverflater
Test samhandlinger fra ende til ende

Forutsetning

Før du begynner, sørger du for at følgende forutsetninger for Azure / Microsoft 365, Google Cloud Platform (GCP) og lokalt miljø er oppfylt.

Forutsetninger for Azure / Microsoft 365

Bekreft at du har tilgang til Microsoft Entra-leier, og installer følgende verktøy for å opprette identiteter, maler og registrere agenten.

En Microsoft Entra-leier med følgende:
- Tillatelse eller rolle til å opprette programmer og agentmaler (global administrator eller tilsvarende)
- Du må delta i Frontier-forhåndsversjonsprogrammet for å kunne få tidlig tilgang til Microsoft Agent 365.
- Minst én Microsoft 365-lisens tilgjengelig for agentbrukeren
Azure CLI installert og logget på.
Agent 365 CLI installert

GCP-krav

Opprettet GCP-prosjekt
API for Cloud Run aktivert

SDK for gcloud installert og autentisert

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

Forutsetninger for lokalt utviklingsmiljø

Redigeringsprogram for kode: Redigeringsprogrammet for kode du foretrekker. Visual Studio Code anbefales.
(Valgfritt) Node.js. Du kan bruke et hvilket som helst språk for agenten. Denne artikkelen bruker Node 18+ i de følgende trinnene.
Tilgang til API for LLM: Velg riktig tjeneste basert på agentens konfigurasjon eller modelleverandøren du foretrekker:
- API-nøkkel for OpenAI: Få API-nøkkelen din for OpenAI
- Azure OpenAI: Opprett og distribuer en Azure OpenAI-ressurs for å få API-nøkkelen og endepunktet ditt

Opprett og distribuer en Agent 365-agent på Cloud Run

Dette eksemplet bruker en minimal Agent 365-agent som gjør følgende:

Svarer på GET /
Godtar Bot Framework-aktiviteter for POST /api/messages
Bruker JWT-autentisering via Agent 365 SDK
Inneholder all kode i én index.js-fil for enkelhets skyld

Opprett prosjekt

Følg disse trinnene for å forsyne en minimal Node.js-agent med stillas som kjører på Cloud Run og godtar Bot Framework-aktiviteter.

Opprett prosjektkatalogen
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Initialiser Node-prosjektet

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

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

Distribuer på Google Cloud Run

Bruk gcloud run deploy til å bygge og kjøre tjenesten på Cloud Run. Når distribusjonen er ferdig, noterer du den offentlige nettadressen for messagingEndpoint.

Bruk følgende kommandoer til å distribuere prosjektet på Google Cloud Run:

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

Når du er ferdig, noterer du deg endepunktet:
```
https://gcp-a365-agent-XXXX-uc.run.app
```
Denne nettadressen er et messagingEndpoint brukes av Agent 365 Dev Tools CLI i neste trinn.

Konfigurer for vertstjeneste uten Azure

Opprett a365.config.json manuelt i Cloud Run-prosjektmappen:

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

Tabellen nedenfor oppsummerer viktige konfigurasjonsfelter og formålet med dem.

Felt	Betydning
`messagingEndpoint`	Cloud Run-nettadressen + `/api/messages`
`deploymentProjectPath`	Der `.env`-stempling skjer

Bygg Agent 365-agenten

Etter at du har distribuert agentkoden din i GCP-endepunktet, følger du de resterende trinnene fra Agent 365-utviklingslivssyklus for å fullføre konfigurasjonen av Agent 365-agenten. Denne prosessen omfatter:

Oppretting av agentidentitet i Microsoft Entra ID
Registrering av Bot Framework-meldingsendepunkt
Oppretting av agentbrukeren
Publisering på Microsoft 365-overflater

Agent 365 CLI håndterer de fleste av disse trinnene automatisk basert på konfigurasjonen i a365.config.json.

Kontroller agenten fra ende til ende

Bruk disse kontrollene til å bekrefte at den vertsbasert GCP-agenten er tilgjengelig, mottar Bot Framework-aktiviteter og svarer riktig på tvers av Agent 365-overflater.

Kontroller tilkoblingen til Cloud Run

Send en GET-forespørsel til messagingEndpoint-verdien fra a365.config.json:

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

Brødteksten i svaret skal omfatte følgende:

GCP Agent is running.

Se i Cloud Run-logger etter innkommende Bot Framework-meldinger

Du kan sjekke Google Cloud Log Explorer eller kjøre følgende:

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

Etter at agenten har mottatt en melding, vises loggoppføringer som viser at serveren mottok og behandlet aktiviteten via Agent 365 SDK.

Test agenten fra Agent 365-overflater

Bruk følgende avhengig av miljøet ditt:

Agents Playground
Teams (hvis publisert)
Agent Shell

Du kan nå sende meldinger og kontrollere Cloud Run-loggene dine. Hvis du vil vite mer, kan du se Finn ut hvordan du tester agenter ved hjelp av Microsoft Agent 365 SDK og validerer agentens funksjonalitet med testverktøyet Agents Playground.

Utviklerarbeidsflyt

Når konfigurasjonen er fullført, følger du denne arbeidsflyten for gjentatt utvikling:

Test lokalt (valgfritt)

For å teste agenten din lokalt før du distribuerer til Cloud Run, sørger du for at .env-filen inneholder riktig legitimasjon:
```
# Start the agent locally
node index.js
```
Agenten din er tilgjengelig på http://localhost:8080. Du kan teste tilstandsendepunktet:
```
curl http://localhost:8080/
```
Foreta kodeendringene

Rediger index.js og lagre endringene.

Distribuer på Google Cloud Run på nytt

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

Test og overvåk

Test via Agent 365-overflater og overvåk Google Cloud Run-logger.

Feilsøking

Bruk denne delen til å diagnostisere vanlige problemer ved distribusjon og kjøring av Agent 365-agenten på Google Cloud Run. Den hjelper deg å bruke løsninger på problemer med tilkobling, konfigurasjon og lisensiering.

Tips

Feilsøkingsveiledning for Agent 365 inneholder anbefalinger på høyt nivå for feilsøking, anbefalte fremgangsmåter og koblinger til feilsøkingsinnhold for hver fase i utviklingssyklusen i Agent 365.

Meldingsendepunktet er ikke nådd

Kontroller følgende detaljer:

Endepunktet er nøyaktig som følger:
https://<cloud-run-url>/api/messages
Cloud Run tillater uautentisert tilgang
Ingen brannmurregler

Lisenstilordning mislyktes

Tildel en gyldig Microsoft 365 Frontier-lisens manuelt, eller bruk en ulisensiert brukerbane hvis den støttes.

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2026-07-29