Crea un agente Agent 365 desplegado en Google Cloud Platform (GCP)

Aprende a construir, alojar, registrar y publicar un agente Agent 365 que se ejecute en Google Cloud Run, usando la CLI de Agent 365. Microsoft Entra y Graph proporciona la identidad, los permisos y el plano técnico del agente, mientras que Google Cloud Run proporciona el tiempo de ejecución.

Si lo único que quieres es apuntar tu agente a tu código que reside detrás de un endpoint de AWS, solo necesitas este paso adicional: configura para hosting no Azure y luego sigue todos los demás pasos del ciclo de vida de desarrollo del Agente 365.

Objetivos

Obtenga información sobre cómo usar el Agente 365 y Microsoft 365 como "plano de control" y:

• Despliega el tiempo de ejecución del agente en Google Cloud Run
• Configuración de a365.config.json para el hospedaje no Azure
• Creación de un plano técnico del agente en Entra ID
• Configurar OAuth2 + permisos heredables
• Registrar el punto de conexión de mensajería de Bot Framework apuntando a GCP
• Crear identidad de agente + usuario del agente
• Publicar en las interfaces de aplicaciones de Microsoft 365
• Interacciones de prueba de extremo a extremo

Prerrequisitos

Antes de comenzar, asegúrese de que se cumplen los siguientes requisitos previos de Azure o Microsoft 365, Google Cloud Platform (GCP) y entorno local.

requisitos previos de Azure/Microsoft 365

Confirme el acceso a su inquilino de Microsoft Entra e instale las siguientes herramientas para crear identidades, plantillas y registrar su agente.

• Un inquilino de Microsoft Entra con:

  • Permiso o rol para crear aplicaciones y planos de agentes (Administrador Global o equivalente)
  • Debe formar parte del programa de versión preliminar Frontier para obtener acceso anticipado a Microsoft Agent 365.
  • Al menos una licencia de Microsoft 365 disponible para el usuario del Agente

• Azure CLI instalado y con sesión iniciada.

• Agente 365 CLI instalado

Requisitos previos para GCP

• Proyecto GCP creado

• API Cloud Run habilitada

• SDK de gcloud instalado y autenticado

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

Requisitos previos para el entorno del desarrollo local

• Editor de código: cualquier editor de código que elija. se recomienda Visual Studio Code.

• (Opcional) Node.js. Puedes usar cualquier lenguaje para tu agente. Este artículo utiliza el Nodo 18+ en los siguientes pasos.

• Acceso a la API LLM: Elige el servicio adecuado según la configuración de tu agente o tu proveedor de modelos preferido:

  • Clave de la API de OpenAI: obtenga la clave de la API de OpenAI
  • Azure OpenAI: Crear e implementar un recurso de OpenAI Azure para obtener la clave de API y el punto de conexión

Crear y desplegar el agente Agent 365 en Cloud Run

Este ejemplo utiliza un agente básico de Agent 365 que:

• Responde a GET /
• Acepta actividades del Bot Framework en POST /api/messages
• Usa la autenticación JWT a través del SDK del Agente 365
• Contiene todo el código de un único index.js archivo por motivos de simplicidad

Crear proyecto

Sigue estos pasos para crear un agente mínimo de Node.js que se ejecute en Cloud Run y acepte actividades de Bot Framework.

1. Crea el directorio del proyecto

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

2. Inicializar el proyecto Node

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

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

Despliega en Google Cloud Run

Use gcloud run deploy para construir y ejecutar el servicio en Cloud Run. Cuando finalice la implementación, anote la dirección URL pública de messagingEndpoint.

1. Utiliza los siguientes comandos para desplegar tu proyecto en Google Cloud Run:

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

2. Cuando termines, apunta tu punto final:

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

   Esta URL es la messagingEndpoint que utiliza la CLI de herramientas de desarrollo de Agent 365 en el siguiente paso.

Configurar para hospedaje que no sea de Azure

Crea a365.config.json en tu carpeta de proyectos Run en la nube ejecutando a365 config init:

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

La siguiente tabla resume los campos de configuración importantes y su propósito.

Crear agente de Agent 365

Después de implementar el código de su agente en el punto de conexión de GCP, siga los pasos restantes de Agent 365 Development Lifecycle para completar la configuración de su agente de Agent 365. Este proceso incluye:

• Creación de la identidad del agente en Microsoft Entra ID
• Registro del extremo de mensajería de Bot Framework
• Creación del usuario del agente
• Publicación en plataformas de Microsoft 365

La CLI de Agent 365 maneja la mayoría de estos pasos automáticamente en función de tu a365.config.json configuración.

Verifica el agente de manera integral

Use estas comprobaciones para confirmar que el agente hospedado en GCP es accesible, recibe actividades de Bot Framework y responde correctamente en las superficies del Agente 365.

Verificar conectividad Cloud Run

Envíe una solicitud de GET al valor messagingEndpoint de su a365.config.json:

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

El órgano de respuesta debe incluir:

GCP Agent is running.

Revisa los registros de Cloud Run para ver si llegan mensajes de Bot Framework

Puedes consultar Google Cloud Log Explorer o ejecutar:

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

Después de que un mensaje alcance el agente, verá entradas de registro que indican que el servidor recibió y procesó la actividad a través del SDK del Agente 365.

Probar agente de las superficies de Agent 365

En función de su entorno, use:

• Área de juegos de agentes
• Equipos (si se publican)
• Agente Shell

Ahora puedes enviar mensajes y verificar tus registros de Cloud Run. Para obtener más información, consulte Learn cómo probar agentes mediante el SDK de Microsoft Agent 365 y validar la funcionalidad del agente con la herramienta de prueba Agents Playground.

Flujo de trabajo del desarrollador

Una vez completada la configuración, sigue este flujo de trabajo para el desarrollo iterativo:

1. Prueba localmente (opcional)

   Para probar el agente localmente antes de implementar en Cloud Run, asegúrese de que el .env archivo contiene las credenciales correctas:

   # Start the agent locally
   node index.js
   

   El agente está disponible en http://localhost:8080. Puede probar el punto de conexión de estado:

   curl http://localhost:8080/
   

2. Realizar cambios en el código

   Edite index.js y guarde los cambios.

3. Reimplementación en Google Cloud Run

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

4. Pruebas y supervisión

   Pruebe las superficies de Agent 365 y supervisa los registros de ejecución en la nube de Google.

Solución de problemas

Use esta sección para diagnosticar problemas comunes al implementar y ejecutar el agente 365 en Google Cloud Run. Ayuda a aplicar rápidamente correcciones para problemas de conectividad, configuración y licencias.

No se alcanza el punto de conexión de mensajería

Consulta los siguientes detalles:

• El punto final es exactamente:
  https://<cloud-run-url>/api/messages
• Cloud Run permite el acceso no autenticado
• No hay reglas de cortafuegos

Fallo en la cesión de licencias

Asigne manualmente una licencia de Microsoft 365 frontier válida o use una ruta de acceso de usuario sin licencia si se admite.