Condividi tramite

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

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

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 & Graph fornisce l'identità dell'agente, i permessi e il blueprint, mentre Google Cloud Run fornisce l'esecuzione del 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

Impara a usare Agent 365 e Microsoft 365 come 'piano di controllo' e:

  • Deploy agent runtime su Google Cloud Run
  • Configure a365.config.json for non-Azure hosting
  • Crea Blueprint Agente in Entra ID
  • Configura OAuth2 + permessi ereditabili
  • Registra l'endpoint di messaggistica del Bot Framework che punta a GCP
  • Crea Identità Agente + Utente Agente
  • Pubblica su Microsoft 365 app surface
  • Interazioni di test end-to-end

Prerequisiti

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

Azure / Microsoft 365 prerequisites

Conferma l'accesso al tuo tenant Microsoft Entra e installa i seguenti strumenti per creare identità, progetti e registrare il tuo agente.

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. Visual Studio Code è consigliato

  • (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:

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 fare una scafflaw di un agente Node.js minimale che giri 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 annota l'URL pubblico per il tuo messagingEndpointfile di servizi .

  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.

Configura 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.

Campo Meaning
messagingEndpoint Il tuo URL Cloud Run + /api/messages
"needDeployment"=false Dice a CLI: 'Ospito un mio server; non distribuire su Azure'
deploymentProjectPath Dove .env avviene la stampa

Build Agent 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 dalle superfici dell'Agente 365

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

Assegna manualmente una licenza Microsoft 365 Frontier valida, oppure usa un percorso utente non autorizzato se supportato.

Ottenere assistenza

Più opzioni di aiuto

Considera quanto segue per trovare aiuto:

  • Last updated on