Crea un agente Agent 365 distribuito su Google Cloud Platform (GCP)

Impara a costruire, ospitare, registrare e pubblicare un agente Agent 365 che giri su Google Cloud Run, utilizzando la CLI di Agent 365. Microsoft Entra e Graph fornisce l'identità, le autorizzazioni e il progetto dell'agente, mentre Google Cloud Run fornisce il runtime.

Se tutto ciò che vuoi fare è indirizzare il tuo agente al codice che si trova dietro un endpoint AWS, ti serve solo questo passaggio aggiuntivo: configura per l'hosting non Azure e poi segui tutti gli altri passaggi del ciclo di sviluppo dell'Agent 365.

Obiettivi

Informazioni su come usare Agent 365 e Microsoft 365 come "piano di controllo" e:

• Distribuzione del runtime dell'agente su Google Cloud Run
• Configurare a365.config.json per l'hosting non basato su Azure
• Creare un progetto agente in Entra ID
• Configura OAuth2 + permessi ereditabili
• Registra l'endpoint di messaggistica del Bot Framework indirizzato a GCP
• Crea Identità dell'Agente + Utente dell'Agente
• Pubblica nelle superfici delle app di Microsoft 365
• Test di interazioni end-to-end

Prerequisiti

Prima di iniziare, assicurarsi che siano soddisfatti i prerequisiti di Azure/Microsoft 365 seguenti, Google Cloud Platform (GCP) e ambiente locale.

prerequisiti di Azure/Microsoft 365

Verificare l'accesso Microsoft Entra tenant e installare gli strumenti seguenti per creare identità, progetti e registrare l'agente.

• Un cliente Microsoft Entra con:

  • Permesso o ruolo per creare applicazioni e schemi di progetto per agenti (Amministratore Globale o equivalente)
  • È necessario far parte del programma di anteprima Frontier per ottenere l'accesso anticipato a Microsoft Agent 365.
  • Almeno una licenza Microsoft 365 disponibile per l'utente di Agent

• interfaccia della riga di comando di Azure installato e accesso effettuato.

• Agente 365 CLI installato

Prerequisiti GCP

• Progetto GCP creato

• API Cloud Run abilitata

• gcloud SDK installato e autenticato

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

Prerequisiti per lo sviluppo locale dell'ambiente

• Editor di codice: qualsiasi editor di codice di tua scelta. è consigliabile Visual Studio Code.

• (Opzionale) Node.js. Puoi usare qualsiasi linguaggio per il tuo agente. Questo articolo utilizza il Nodo 18+ nei passaggi seguenti.

• Accesso API LLM: Scegli il servizio appropriato in base alla configurazione del tuo agente o al fornitore di modelli preferito:

  • Chiave API OpenAI: ottieni la chiave API OpenAI
  • Azure OpenAI: Creare e distribuire una risorsa OpenAI Azure per ottenere la chiave API e l'endpoint

Creare e distribuire l'Agente 365 su Cloud Run

Questo esempio utilizza un agente 365 minimo che:

• Risponde a GET /
• Accetta attività del Bot Framework su POST /api/messages
• Usa l'autenticazione JWT tramite Agent 365 SDK
• Contiene tutto il codice in un singolo index.js file per semplicità

Creare un progetto

Segui questi passaggi per impostare un agente Node.js minimale che venga eseguito su Cloud Run e accetti le attività del Bot Framework.

1. Crea la directory del progetto

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

2. Inizializzare il progetto Node

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

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

Distribuisci su Google Cloud Run

Usare gcloud run deploy per compilare ed eseguire il servizio su Cloud Run. Al termine della distribuzione, annotare l'URL pubblico per il tuo messagingEndpoint.

1. Usa i seguenti comandi per distribuire il tuo progetto su Google Cloud Run:

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

2. Quando hai finito, annota il tuo endpoint:

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

   Questo URL è utilizzato messagingEndpoint dalla CLI degli Strumenti di Sviluppo Agent 365 nel passo successivo.

Configurare per l'hosting non Azure

Crea a365.config.json nella cartella del progetto Cloud Run eseguendo a365 config init:

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

La tabella seguente riassume i campi di configurazione importanti e il loro scopo.

Creare agente Agent 365

Dopo aver distribuito il codice dell'agente nell'endpoint GCP, seguire i passaggi rimanenti del ciclo di vita dello sviluppo di Agent 365 per completare la configurazione dell'agente Agent 365. Questo processo include:

• Creazione dell'identità dell'agente in Microsoft Entra ID
• Registrazione dell'endpoint di messaggistica di Bot Framework
• Creazione utente agente
• Pubblicazione sulle interfacce di Microsoft 365

L'Agent 365 CLI gestisce automaticamente la maggior parte di questi passaggi in base alla configurazione a365.config.json.

Verifica l'agente end-to-end

Usare questi Controlli per verificare che l'Agente ospitato da GCP sia raggiungibile, riceva le attività di Bot Framework e risponda correttamente sulle superfici di Agent 365.

Verifica la connettività Cloud Run

Invia una GET richiesta al messagingEndpoint valore del tuo a365.config.json:

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

L'organo di risposta dovrebbe includere:

GCP Agent is running.

Controlla i log di Cloud Run per i messaggi in arrivo del Bot Framework

Puoi controllare Google Cloud Log Explorer o eseguire:

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

Dopo che un messaggio raggiunge il tuo agente, vengono visualizzate voci di log che indicano che il server ha ricevuto ed elaborato l'attività tramite l'SDK dell'Agent 365.

Agente di test da Agent 365

A seconda dell'ambiente, usare:

• Parco Giochi degli Agenti
• Squadre (se pubblicate)
• Agente Shell

Ora puoi inviare messaggi e verificare i log Cloud Run. Per altre informazioni, vedere Informazioni su come testare gli agenti usando Microsoft Agent 365 SDK e convalidare le funzionalità dell'agente con lo strumento di test Agents Playground.

Flusso di lavoro degli sviluppatori

Una volta completata la configurazione, segui questo flusso di lavoro per lo sviluppo iterativo:

1. Testare localmente (opzionale)

   Per testare l'agente in locale prima di eseguire la distribuzione in Cloud Run, verificare che il .env file contenga le credenziali corrette:

   # Start the agent locally
   node index.js
   

   L'agente è disponibile all'indirizzo http://localhost:8080. È possibile testare l'endpoint di integrità:

   curl http://localhost:8080/
   

2. Apportare le modifiche al codice

   Modificare index.js e salvare le modifiche.

3. Ridistribuzione su Google Cloud Run

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

4. Testare e monitorare

   Testa tramite superfici Agent 365 e monitora i log di Google Cloud Run.

Risoluzione dei problemi

Usare questa sezione per diagnosticare i problemi comuni durante la distribuzione e l'esecuzione dell'agente Agent 365 in Google Cloud Run. Consente di applicare rapidamente correzioni per problemi di connettività, configurazione e gestione delle licenze.

L'endpoint di messaggistica non viene raggiunto

Controlla i seguenti dettagli:

• Il punto finale è esattamente:
  https://<cloud-run-url>/api/messages
• Cloud Run consente l'accesso non autenticato
• Nessuna regola firewall

Fallimento della cessione della licenza

Assegnare manualmente una licenza di frontiera Microsoft 365 valida oppure usare un percorso utente senza licenza, se supportato.