Byg en Agent 365-agent implementeret i Google Cloud Platform (GCP)

Lær at bygge, hoste, registrere og publicere en Agent 365-agent, der kører på Google Cloud Run, ved hjælp af Agent 365 CLI. Microsoft Entra & Graph leverer agentens identitet, tilladelser og blueprint, mens Google Cloud Run leverer kørsel.

Hvis alt, du ønsker, er at pege din agent på din kode, der ligger bag et AWS-slutpunkt, skal du blot tage dette ekstra trin: Konfigurer til ikke-Azure hosting og følg derefter alle andre trin fra Kom i gang med Agent 365-udvikling.

Mål

Lær at bruge Agent 365 og Microsoft 365 som 'kontrolplan' og:

• Udrul agent-runtime på Google Cloud Run
• Konfigurer a365.config.json til hosting uden Azure
• Opret agentblueprint i Entra ID
• Konfigurer OAuth2 + nedarvede tilladelser
• Registrer Bot Framework-beskedslutpunkt, der peger på GCP
• Opret agentidentitet + agentbruger
• Publicer til Microsoft 365 appflader
• Test komplette interaktioner

Forudsætninger

Inden du går i gang, skal du sikre dig, at følgende forudsætninger for Azure / Microsoft 365, Google Cloud Platform (GCP) og det lokale miljø er opfyldt.

Azure / Microsoft 365-forudsætninger

Bekræft din adgang til din Microsoft Entra-lejer, og installer følgende værktøjer for at oprette identiteter, blueprints og registrere din agent.

• En Microsoft Entra-lejer med:

  • Tilladelse eller rolle til at oprette applikationer og agentblueprints (Global administrator eller tilsvarende)
  • Du skal være en del af Frontier-forhåndsversionsprogrammet for at få tidlig adgang til Microsoft Agent 365.
  • Mindst én Microsoft 365-licens tilgængelig for agentbrugeren

• Azure CLI installeret og logget på.

• Agent 365 CLI installeret

GCP-forudsætninger

• Oprettet GCP-projekt

• Cloud Run API aktiveret

• gcloud SDK installeret og autentificeret

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

Forudsætninger for det lokale udviklingsmiljø

• Kodeeditor: En hvilken som helst kodeeditor efter eget valg. Visual Studio Code anbefales.

• (Valgfrit) Node.js. Du kan bruge ethvert sprog til din agent. Denne artikel bruger Node 18+ i følgende trin.

• LLM API-adgang: Vælg den relevante tjeneste baseret på din agents konfiguration eller din foretrukne modeludbyder:

  • OpenAI API-nøgle: Hent din OpenAI API-nøgle
  • Azure OpenAI: Opret og udrul en Azure OpenAI-ressource for at hente din API-nøgle og dit slutpunkt

Opret og udrul Agent 365 agent til Cloud Run

Dette eksempel benytter en minimal Agent 365-agent, der:

• Responderer på GET /
• Accepterer Bot Framework-aktiviteter på POST /api/messages
• Bruger JWT-godkendelse via Agent 365 SDK
• Indeholder al kode i en enkelt index.js fil for enkelhedens skyld

Oprette projekt

Følg disse trin for at oprette en minimal Node.js-agent, der kører på Cloud Run og accepterer Bot Framework-aktiviteter.

1. Opret projektmappen

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

2. Initialiser Node-projektet

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

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

Udrul til Google Cloud Run

Brug gcloud run deploy til at bygge og køre tjenesten på Cloud Run. Når udrulningen er færdig, skal du notere den offentlige URL for din messagingEndpoint.

1. Brug følgende kommandoer til at udrulle dit projekt på Google Cloud Run:

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

2. Når du er færdig, skal du notere dit slutpunkt:

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

   Denne URL er det messagingEndpoint der bruges af Agent 365 Dev Tools CLI i næste trin.

Konfigurer til ikke-Azure hosting

Opret a365.config.json manuelt i din Cloud Run-projektmappe:

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

Følgende tabel opsummerer vigtige konfigurationsfelter og deres formål.

Felt	Betydning
messagingEndpoint	Din Cloud Run-URL + /api/messages
deploymentProjectPath	Hvor .env stempling sker

---

Byg Agent 365-agent

Efter at have udrullet din agentkode til dit GCP-slutpunkt, følger du de resterende trin fra Agent 365-udviklingslivscyklussen for at fuldføre opsætningen af din Agent 365-agent. Denne proces omfatter:

• Oprettelse af agentidentiteten i Microsoft Entra ID
• Registrering af Bot Framework-meddelelsesslutpunktet
• Oprettelse af agentbrugeren
• Udgivelse til Microsoft 365-platforme

Agent 365 CLI håndterer de fleste af disse trin automatisk baseret på din a365.config.json-konfiguration.

Kontrollér agenten fuldt ud.

Brug disse tjek for at bekræfte, at din GCP-hostede Agent 365-agent er tilgængelig, modtager Bot Framework-aktiviteter og svarer korrekt på tværs af Agent 365-overflader.

Verificér Cloud Run-forbindelsen

Send en GET-anmodning til messagingEndpoint-værdien fra din a365.config.json:

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

Svaret bør indeholde:

GCP Agent is running.

Kontrollér Cloud Run-logge for indgående Bot Framework-meddelelser

Du kan kontrollere Google Cloud Log Explorer eller køre:

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

Når en meddelelse rammer din agent, ser du logposter, der viser, at serveren har modtaget og behandlet aktiviteten gennem Agent 365 SDK.

Testagent fra Agent 365-overflader

Afhængigt af dit miljø kan du bruge:

• Agents Playground
• Teams (hvis publiceret)
• Agent Shell

Du kan nu sende beskeder og kontrollere dine Cloud Run-logfiler. For yderligere information, se Læs hvordan du tester agenter med Microsoft Agent 365 SDK og validerer din agents funktionalitet med Agents Playground-testværktøjet.

Udviklerarbejdsproces

Følg denne arbejdsproces for iterativ udvikling, når opsætningen er fuldført:

1. Test lokalt (valgfrit)

   For at teste din agent lokalt, før du udruller til Cloud Run, skal du sikre dig, at din .env-fil indeholder de korrekte legitimationsoplysninger:

   # Start the agent locally
   node index.js
   

   Din agent er tilgængelig på http://localhost:8080. Du kan teste sundhedsendepunktet:

   curl http://localhost:8080/
   

2. Foretag kodeændringer

   Rediger index.js, og gem ændringerne.

3. Genudrul til Google Cloud Run

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

4. Test og overvåg

   Test via Agent 365-flader og overvåg Google Cloud Run-logfiler.

Fejlfinding

Brug dette afsnit til fejlfinding af almindelige problemer under udrulning og drift af din Agent 365-agent på Google Cloud Run. Det hjælper dig med hurtigt at foretage rettelser til forbindelses-, konfigurations- og licensproblemer.

Tip

Agent 365 Fejlfindingsguide indeholder overordnede anbefalinger til fejlfinding, bedste praksis og links til fejlfindingsindhold for hver fase af udviklingslivscyklussen for Agent 365.

Meddelelsesslutpunkt nås ikke

Tjek følgende oplysninger:

• Dit slutpunkt er nøjagtigt:
  https://<cloud-run-url>/api/messages
• Cloud Run tillader adgang uden autentificering
• Ingen firewallregler

Licenstildeling mislykkes

Tildel en gyldig Microsoft 365 Frontier-licens manuelt, eller brug en ikke-licenseret brugersti, hvis det understøttes.