Partager via

Construire un agent Agent 365 déployé sur Google Cloud Platform (GCP)

Important

Vous devez faire partie du programme Frontier en version préliminaire pour obtenir un accès anticipé à Microsoft Agent 365. Frontier vous connecte directement aux dernières innovations d’IA de Microsoft. Les versions préliminaires Frontier sont soumises aux conditions existantes de vos contrats clients qui régissent les versions préliminaires. Comme ces fonctionnalités sont encore en cours de développement, leur disponibilité et leurs capacités peuvent évoluer au fil du temps.

Apprenez à construire, héberger, enregistrer et publier un agent Agent 365 fonctionnant sur Google Cloud Run, en utilisant la CLI Agent 365. Microsoft Entra & Graph fournit l’identité de l’agent, les permissions et le blueprint, tandis que Google Cloud Run fournit l’exécution.

Si tout ce que vous voulez, c’est orienter votre agent vers votre code situé derrière un terminau AWS, vous n’avez besoin que de cette étape supplémentaire : configurez pour un hébergement non-Azure , puis suivez toutes les autres étapes du cycle de développement de l’Agent 365.

Objectifs

Apprenez à utiliser Agent 365 et Microsoft 365 comme « plan de contrôle » et :

  • Déploiement de l’exécution de l’agent sur Google Cloud Run
  • Configure a365.config.json for non-Azure hosting
  • Créer un plan d’agent dans Entra ID
  • Configurer OAuth2 + permissions héréditaires
  • Terminaison de messagerie du Cadre de Bots Register pointant vers GCP
  • Créer une identité d’agent + Utilisateur d’agent
  • Publier sur Microsoft 365 App Surfaces
  • Interactions de test de bout en bout

Prerequisites

Avant de commencer, assurez-vous que les prérequis suivants pour Azure / Microsoft 365, Google Cloud Platform (GCP) et environnement local sont remplis.

Azure / Microsoft 365 prerequisites

Confirmez l’accès à votre locataire Microsoft Entra et installez les outils suivants pour créer des identités, des plans et enregistrer votre agent.

Prérequis GCP

  • Projet GCP créé

  • API Cloud Run activée

  • SDK gcloud installé et authentifié :

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

Prérequis environnementaux de développement local

  • Éditeur de code  : n’importe quel éditeur de code de votre choix. Visual Studio Code est recommandé

  • (Optionnel) Node.js. Vous pouvez utiliser n’importe quel langage pour votre agent. Cet article utilise le Node 18+ dans les étapes suivantes.

  • Accès à l’API LLM : Choisissez le service approprié en fonction de la configuration de votre agent ou de votre fournisseur de modèle préféré :

Créer et déployer l’agent 365 vers le cloud

Cet exemple utilise un agent d’exemple minimal qui :

  • Répond à GET /
  • Accepte les activités du cadre Bot sur POST /api/messages

Créer un projet

Suivez ces étapes pour échaffacer un agent Node.js minimal qui fonctionne sur Cloud Run et accepte les activités du Bot Framework.

  1. Créez le répertoire du projet

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

  2. Initialiser le projet Node

    npm init -y
npm install express body-parser

  3. Créer 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));

Déploiement sur Google Cloud Run

Utilisez gcloud run deploy pour construire et exécuter le service sur Cloud Run, puis notez l’URL publique de votre messagingEndpointfichier .

  1. Utilisez les commandes suivantes pour déployer votre projet sur Google Cloud Run :

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

  2. Une fois terminé, notez votre point final :

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

    Cette URL est utilisée messagingEndpoint par le CLI Agent 365 Dev Tools à l’étape suivante.

Configure for Non-Azure Hosting

Créez a365.config.json dans votre dossier Cloud Run Project en exécutant 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"
}

Le tableau suivant résume les champs de configuration importants et leur objectif.

Terrain Meaning
messagingEndpoint Votre URL Cloud Run + /api/messages
"needDeployment"=false Dit à CLI : « J’héberge mon propre serveur ; ne pas déployer sur Azure'
deploymentProjectPath Là où .env le stamping a lieu

Build agent 365

Une fois que votre code d’agent s’exécute sur un terminal AWS, suivez les étapes restantes du cycle de développement de l’Agent 365 pour configurer votre agent Agent 365.

Vérifier l’agent de bout en bout

Utilisez ces vérifications pour confirmer que votre agent hébergé sur GCP est joignable, reçoit les activités du Bot Framework et répond correctement sur les surfaces Agent 365.

Verify la connectivité Cloud Run

Envoyez une GET requête à la messagingEndpoint valeur de votre a365.config.json:

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

L’organe de réponse doit inclure :

GCP Agent is running.

Vérifiez les journaux Cloud Run pour les messages arrivants du Bot Framework

Vous pouvez consulter Google Cloud Log Explorer ou exécuter :

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

Après qu’un message ait reçu votre agent, vous devriez voir :

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

Agent de test à partir des surfaces de l’Agent 365

Selon votre environnement :

  • Terrain de jeu des agents
  • Équipes (si publiées)
  • Agent Shell

Vous pouvez désormais envoyer des messages et vérifier vos journaux Cloud Run. Et vous pouvez aussi apprendre à tester des agents en utilisant le Microsoft Agent 365 SDK et à valider les fonctionnalités de votre agent avec l’outil de test Agents Playground.

Flux de travail du développeur

Une fois la configuration terminée, suivez ce flux de travail pour un développement itératif :

  1. Changez votre code d’agent

    Faites vos modifications de code, sauvegardez et testez localement avant de déployer.

  2. Redéployer sur Google Cloud Run

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

  3. Tester et surveiller

    Testez via des surfaces Agent 365 et surveillez les journaux Google Cloud Run.

    Note

    Votre identité, votre blueprint, votre point de terminaison du bot et vos permissions N’ONT PAS BESOIN d’être recréés.

Résolution des problèmes

Utilisez cette section pour diagnostiquer les problèmes courants lors du déploiement et de l’exécution de votre agent Agent 365 sur Google Cloud Run, et pour appliquer rapidement des correctifs aux problèmes de connectivité, de configuration et de licence.

Le point de terminaison de messagerie n’est pas touché

Consultez les détails suivants :

  • Le point final est exactement :
    https://<cloud-run-url>/api/messages
  • Cloud Run permet un accès non authentifié
  • Pas de règles de pare-feu

Échec de la cession de licence

Attribuez manuellement une licence Microsoft 365 Frontier valide, ou utilisez un chemin utilisateur non licencié si cela est supporté.

Obtenir de l’aide

Plus d’options d’aide

Considérez les points suivants pour obtenir de l’aide :

  • Last updated on