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

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é, les autorisations et le blueprint de l’agent, tandis que Google Cloud Run fournit le runtime.

Si tout ce que vous souhaitez faire est de pointer votre agent vers votre code résidant derrière un point de terminaison AWS, vous avez uniquement besoin de cette étape supplémentaire : Configurer pour l’hébergement non-Azure , puis suivre toutes les autres étapes de prise en main du développement Agent 365.

Objectifs

Découvrez comment 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
Configurer a365.config.json pour l’hébergement non Azure
Créer un blueprint d’agent dans Entra ID
Configurer OAuth2 + permissions héréditaires
Enregistrer le point de terminaison de communication du Framework Bot lié à GCP
Créer une identité d'agent + Utilisateur d'agent
Publier sur des surfaces d’application Microsoft 365
Tester les interactions de manière complète

Prerequisites

Avant de commencer, vérifiez que les conditions préalables suivantes sont remplies pour Azure/Microsoft 365, la Google Cloud Platform (GCP) et l'environnement local.

prérequis Azure /Microsoft 365

Vérifiez votre accès au locataire Microsoft Entra et installez les outils suivants pour créer des identités, des plans de configuration et enregistrer votre agent.

Un client Microsoft Entra avec :
- Permission ou rôle pour créer des applications et des plans d’agent (Administrateur global ou équivalent)
- Vous devez faire partie du programme de préversion Frontier pour obtenir un accès anticipé à Microsoft Agent 365.
- Au moins une licence Microsoft 365 disponible pour l’utilisateur agent
Azure CLI installé et connecté.
Agent 365 CLI installé

Prérequis GCP

Projet GCP créé
API Cloud Run activée

Kit de développement logiciel (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é :
- Clé d’API OpenAI : Obtenir votre clé d’API OpenAI
- Azure OpenAI : Creater et déployer une ressource OpenAI Azure pour obtenir votre clé API et votre point de terminaison

Créer et déployer l’agent 365 sur Cloud Run

Cet exemple utilise un agent minimal de l'Agent 365 qui :

Répond à GET /
Accepte les activités du cadre Bot sur POST /api/messages
Utilise l’authentification JWT via le Kit de développement logiciel (SDK) Agent 365
Contient tout le code d’un fichier unique index.js par souci de simplicité

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.

Créez le répertoire du projet
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Initialiser le projet Node

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

Créer 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}`));

Déploiement sur Google Cloud Run

Utilisez gcloud run deploy pour compiler et exécuter le service sur Cloud Run. Une fois le déploiement terminé, notez l’URL publique de votre messagingEndpoint.

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

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.

Configurer pour l’hébergement non Azure

Créez a365.config.json manuellement dans votre dossier de projet d’exécution cloud :

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

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

Champ	Signification
`messagingEndpoint`	Votre URL Cloud Run + `/api/messages`
`deploymentProjectPath`	Là où `.env` le marquage a lieu

Build Agent 365 Agent

Après avoir déployé votre code d’agent sur votre point de terminaison GCP, suivez les étapes restantes de l’Agent 365 Development Lifecycle pour terminer la configuration de votre agent Agent 365. Ce Traitement comprennent :

Création de l’identité de l’agent dans Microsoft Entra ID
Enregistrement du point de terminaison de messagerie du Bot Framework
Création de l’utilisateur de l’agent
Publication sur les interfaces de Microsoft 365

L’interface CLI Agent 365 gère la plupart de ces étapes automatiquement en fonction de votre a365.config.json configuration.

Vérifier l’agent de bout en bout

Utilisez ces vérifications pour confirmer que votre agent hébergé par GCP est accessible, reçoit des activités Bot Framework et répond correctement sur les surfaces de l’agent 365.

Vérifiez la connectivité Cloud Run

Envoyez une requête GET à la valeur messagingEndpoint depuis 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

Une fois qu’un message a atteint votre agent, vous voyez les entrées de journal qui indiquent que le serveur a reçu et traité l’activité via le Kit de développement logiciel (SDK) Agent 365.

Agent de test de l’Agent 365 apparaît

Selon votre environnement, utilisez :

Terrain de jeu des agents
Équipes (si publiées)
Interpréteur de commandes d’agent

Vous pouvez désormais envoyer des messages et vérifier vos journaux Cloud Run. Pour plus d'informations, consultez Learn comment tester des agents à l'aide du SDK Microsoft Agent 365 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 :

Tester localement (optionnel)

Pour tester votre agent localement avant de déployer sur Cloud Run, vérifiez que votre .env fichier contient les informations d’identification appropriées :
```
# Start the agent locally
node index.js
```
Votre agent est disponible à l’adresse http://localhost:8080. Vous pouvez tester le point de terminaison de l’état d’intégrité :
```
curl http://localhost:8080/
```
Apporter vos modifications de code

Modifiez index.js et enregistrez vos modifications.

Redéployer sur Google Cloud Run

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

Tester et surveiller

Testez via les surfaces d'Agent 365 et surveillez les logs de Google Cloud Run.

Dépannage

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. Il vous aide à appliquer rapidement des correctifs pour les problèmes de connectivité, de configuration et de licence.

Conseil

Le Guide de dépannage de l’Agent 365 contient des recommandations générales de dépannage, les meilleures pratiques et des liens vers du contenu de dépannage pour chaque étape du cycle de développement de l’Agent 365.

Le point de terminaison de messagerie n’est pas atteint

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 de frontière Microsoft 365 valide ou utilisez un chemin d’accès utilisateur sans licence si pris en charge.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-05-01