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-Azure
• Crea il Blueprint dell'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
• Pubblicare sulle interfacce dell'app Microsoft 365
• Testare le 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 tenant Microsoft Entra con:

  • Permesso / ruolo per creare applicazioni e schemi di agente (Amministratore Globale o equivalente)
  • Devi far parte del programma Frontier preview per ottenere l'accesso anticipato a Microsoft Agent 365.
  • Almeno una licenza Microsoft 365 disponibile per l'utente di Agent

• Azure CLI installato e accesso effettuato.

• Agente 365 CLI installato

Prerequisiti GCP

• Progetto GCP creato

• API Cloud Run abilitata

• SDK gcloud 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

Crea e distribuisce l'agente 365 su Cloud Run

Questo esempio utilizza un agente di esempio minimale che:

• Risponde a GET /
• Accetta attività del Bot Framework su POST /api/messages

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 body-parser
   

3. Creare index.js

   const express = require("express");
   const bodyParser = require("body-parser");
   
   const app = express();
   app.use(bodyParser.json());
   
   app.get("/", (req, res) => {
   res.status(200).send("GCP Agent is running.");
   });
   
   // Bot Framework Activity Handler
   app.post("/api/messages", (req, res) => {
   console.log("Received activity:", JSON.stringify(req.body, null, 2));
   
   // Echo activity
   const reply = {
      type: "message",
      text: `You said: ${req.body?.text}`
   };
   
   res.status(200).send(reply);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => console.log("Server listening on port " + port));
   

Distribuisci su Google Cloud Run

Usa gcloud run deploy per costruire ed eseguire il servizio su Cloud Run, poi prendi nota dell'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 basato su 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.

Build Agente 365

Una volta che il codice dell'agente è in esecuzione su un endpoint AWS, segui i passaggi rimanenti del ciclo di sviluppo di Agent 365 per configurare il tuo agente Agent 365.

Verifica l'agente end-to-end

Usa questi controlli per confermare che il tuo agente ospitato su GCP sia raggiungibile, riceva le attività del Bot Framework e risponda correttamente sulle superfici dell'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 è arrivato al tuo agente, dovresti vedere:

POST 200 /api/messages
Received activity: { ... }

Agente di prova di Agent 365 Surfaces

A seconda del tuo ambiente:

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

Ora puoi inviare messaggi e verificare i log Cloud Run. E puoi anche imparare a testare gli agenti usando l'SDK Microsoft Agent 365 e a validare le funzionalità del tuo agente con lo strumento di testing Agents Playground.

Flusso di lavoro degli sviluppatori

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

1. Cambia il codice del tuo agente

   Modifica il codice, salva e testa localmente prima di distribuire.

2. Ridistribuzione su Google Cloud Run

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

3. Testare e monitorare

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

   Annotazioni

   La tua identità, il blueprint, l'endpoint del bot e i permessi NON devono essere ricreati.

Risoluzione dei problemi

Usa questa sezione per diagnosticare i problemi comuni durante il deployment e l'esecuzione del tuo agente Agent 365 su Google Cloud Run, e per applicare rapidamente soluzioni a problemi di connettività, configurazione e licenza.

L'endpoint di messaggistica non viene colpito

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.