Bygg en Agent 365-agent distribuerad i Google Cloud Platform (GCP)

Lär dig hur du skapar, driftar, registrerar och publicerar en Agent 365-agent som körs på Google Cloud Run, med hjälp av Agent 365 CLI. Microsoft Entra & Graph tillhandahåller agentens identitet, behörigheter och blueprint, medan Google Cloud Run tillhandahåller runtime-miljön.

Om allt du vill göra är att peka din agent mot kod bakom en AWS-slutpunkt behöver du bara detta extra steg: Konfigurera för icke-Azure-hosting och följ sedan övriga steg från Kom igång med Agent 365-utveckling.

Mål

Lär dig att använda Agent 365 och Microsoft 365 som "kontrollplanet" och:

Distribuera agentens körmiljö på Google Cloud Run
Konfigurera a365.config.json för värdmiljö utanför Azure
Skapa Agent Blueprint i Entra ID
Konfigurera OAuth2 + ärvbara behörigheter
Registrera Bot Framework slutpunkt för meddelanden riktad mot GCP
Skapa agentidentitet + agentanvändare
Publicera till Microsoft 365-ytor
Testa kompletta interaktioner

Krav

Innan du börjar, säkerställ att följande Azure / Microsoft 365-, Google Cloud Platform (GCP)- och lokala förutsättningar är uppfyllda.

Azure / Microsoft 365 förutsättningar

Bekräfta att du har åtkomst till din Microsoft Entra-tenant och installera följande verktyg för att skapa identiteter, blueprints och registrera din agent.

En Microsoft Entra ID-klientorganisation med:
- Behörighet eller roll att skapa appar och agent blueprints (Global Administratör eller motsvarande)
- Du måste vara en del av Frontier-förhandsversionsprogrammet för att få tidig tillgång till Microsoft Agent 365.
- Minst en Microsoft 365-licens tillgänglig för agentanvändaren
Azure CLI installerat och inloggat.
Agent 365 CLI installerad

GCP-förutsättningar

Skapat GCP-projekt
Cloud Run API aktiverat

gcloud SDK installerat och autentiserat

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

Förutsättningar för lokal utvecklingsmiljö

Kodredigerare: valfri kodredigerare. Visual Studio Code rekommenderas.
(Valfritt) Node.js. Du kan använda vilket språk som helst för din agent. I de följande stegen används Node 18+.
LLM API-åtkomst: Välj lämplig tjänst baserat på agentens konfiguration eller önskad modellleverantör:
- OpenAI API-nyckel: Hämta din OpenAI API-nyckel
- Azure OpenAI: Skapa och driftsätt en Azure OpenAI-resurs för att hämta din API-nyckel och slutpunkt

Skapa och distribuera en Agent 365-agent till Cloud Run

Detta exempel använder en minimal Agent 365-agent som:

Svarar på GET /
Accepterar Bot Framework-aktiviteter på POST /api/messages
Använder JWT-autentisering via Agent 365 SDK
Innehåller all kod i en enda index.js fil för enkelhetens skull

Skapa projekt

Följ dessa steg för att bygga upp en minimal Node.js-agent som körs på Cloud Run och accepterar Bot Framework-aktiviteter.

Skapa projektkatalogen
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Initiera Node-projektet

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

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

Distribuera till Google Cloud Run

Använd gcloud run deploy för att bygga och köra tjänsten på Cloud Run. När distributionen är klar, notera den publika URL:en för din messagingEndpoint.

Använd följande kommandon för att distribuera ditt projekt till Google Cloud Run:

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

När du är klar, notera din slutpunkt:
```
https://gcp-a365-agent-XXXX-uc.run.app
```
Den här URL:en är messagingEndpoint, som används av Agent 365 Dev Tools CLI i nästa steg.

Konfigurera för värdmiljö utanför Azure

Skapa a365.config.json manuellt i din Cloud Run-projektmapp:

{
  "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öljande tabell sammanfattar viktiga konfigurationsfält och deras syfte.

Fält	Betydelse
`messagingEndpoint`	Din Cloud Run-URL + `/api/messages`
`deploymentProjectPath`	Där `.env`-stämpling sker

Bygg Agent 365-agent

Efter att du har distribuerat din agentkod till din GCP-slutpunkt, följ de återstående stegen från Agent 365 Development Lifecycle för att slutföra konfigurationen av din Agent 365-agent. Denna process omfattar:

Skapa agentens identitet i Microsoft Entra ID
Registrera Bot Framework-meddelandeändpunkten
Skapa agentanvändaren
Publicera till Microsoft 365-ytor

Agent 365 CLI hanterar de flesta av dessa steg automatiskt baserat på din a365.config.json-konfiguration.

Verifiera agenten från början till slut

Använd dessa kontroller för att säkerställa att din GCP-hostade agent är nåbar, tar emot Bot Framework-aktiviteter och svarar korrekt över Agent 365-ytor.

Verifiera Cloud Run-anslutning

Skicka en GET-förfrågan till messagingEndpoint-värdet från din a365.config.json:

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

Svarskroppen bör inkludera:

GCP Agent is running.

Kontrollera Cloud Run-loggar för inkommande Bot Framework-meddelanden

Du kan kontrollera Google Cloud Log Explorer eller köra:

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

När ett meddelande når din agent ser du loggar som visar att servern har tagit emot och hanterat aktiviteten via Agent 365 SDK.

Testämne från Agent 365-ytor

Beroende på din miljö, använd:

Testplats för agenter
Teams (om publicerat)
Agent Shell

Du kan nu skicka meddelanden och verifiera dina Cloud Run-loggar. För att lära dig mer, se Lär dig hur du testar agenter med Microsoft Agent 365 SDK och validerar din agents funktionalitet med testverktyget Agents Playground.

Arbetsflöde för utvecklare

När installationen är klar, följ detta arbetsflöde för iterativ utveckling:

Testa lokalt (valfritt)

För att testa din agent lokalt innan du distribuerar till Cloud Run, se till att din .env-fil innehåller rätt inloggningsuppgifter:
```
# Start the agent locally
node index.js
```
Din agent finns tillgänglig på http://localhost:8080. Du kan testa hälsoändpunkten:
```
curl http://localhost:8080/
```
Gör önskade kodändringar

Redigera index.js och spara dina ändringar.

Distribuera igen till Google Cloud Run

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

Testa och övervaka

Testa via Agent 365 Surfaces och övervaka Google Cloud Run-loggar.

Felsökning

Använd detta avsnitt för att diagnostisera vanliga problem när du distribuerar och kör din Agent 365-agent på Google Cloud Run. Det hjälper dig att snabbt åtgärda anslutnings-, konfigurations- och licensproblem.

Dricks

Agent 365-felsökningsguide innehåller övergripande felsökningsrekommendationer, bästa praxis och länkar till felsökningsinnehåll för varje enskild del av Agent 365:s utvecklingslivscykel.

Meddelandeterminalen nås inte

Kontrollera följande detaljerad information:

Slutpunkten är exakt följande:
https://<cloud-run-url>/api/messages
Cloud Run tillåter åtkomst utan autentisering
Inga brandväggsregler

Licenstilldelning misslyckas

Tilldela en giltig Microsoft 365 Frontier-licens manuellt, eller använd ett alternativ för olicensierade användare om det stöds.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-07-30