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
• Crear Plano de Agente en Entra ID
• Configurar OAuth2 + permisos heredables
• Registro del punto final de mensajería del Bot Framework apuntando a GCP
• Crear identidad de agente + usuario del agente
• Publicar en superficies de las 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 su acceso al tenant de Microsoft Entra e instale las siguientes herramientas para crear identidades, modelos y registrar su agente.

• Un inquilino de Microsoft Entra con:

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

• CLI de Azure instalado y iniciado sesión.

• Agente 365 CLI instalado

Requisitos previos para GCP

• Proyecto GCP creado

• API Cloud Run habilitada

• SDK 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 Agent 365 Agent en Cloud Run

Este ejemplo utiliza un agente de ejemplo mínimo que:

• Responde a GET
• Acepta actividades de Bot Framework en solicitudes POST

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

3. Crear

   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));
   

Despliega en Google Cloud Run

Úsalo para compilar y ejecutar el servicio en Cloud Run, luego anota la URL pública para tu aplicación.

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 que utiliza la CLI de herramientas de desarrollo de Agent 365 en el siguiente paso.

Configurar para hospedaje que no sea de Azure

Crea en la carpeta de tu proyecto de Cloud Run ejecutando :

{
  "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 siguiente tabla resume los campos de configuración importantes y su propósito.

Agente de construcción 365

Una vez que tengas el código de tu agente ejecutándose contra un endpoint de AWS, sigue los pasos restantes del ciclo de vida de desarrollo del Agente 365 para configurar tu agente del Agente 365.

Verifica el agente de manera integral

Utiliza estas comprobaciones para confirmar que tu agente alojado en GCP está localizable, recibe actividades del Bot Framework y responde correctamente en las superficies del Agente 365.

Verificar conectividad Cloud Run

Envía una solicitud al valor de tu :

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 llegue a tu agente, deberías ver:

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

Agente de prueba que aparece del Agente 365

Dependiendo de tu entorno:

• Sitio de prueba de agentes
• Equipos (si se publican)
• Agente Shell

Ahora puedes enviar mensajes y verificar tus registros de Cloud Run. Y también puedes aprender a probar agentes usando el Microsoft Agent 365 SDK y validar la funcionalidad de tu agente con la herramienta de pruebas Agents Playground.

Flujo de trabajo del desarrollador

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

1. Cambia tu código de agente

   Haz tus cambios de código, guarda y prueba localmente antes de desplegar.

2. Reimplementación en Google Cloud Run

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

3. Pruebas y supervisión

   Prueba las funcionalidades de Agent 365 y monitoriza los registros de Google Cloud Run.

   Nota:

   Tu identificador, modelo, punto de conexión del bot y permisos no necesitan ser recreados.

Solución de problemas

Utiliza esta sección para diagnosticar problemas comunes al desplegar y ejecutar tu agente Agent 365 en Google Cloud Run, y para aplicar rápidamente soluciones para problemas de conectividad, configuración y licencias.

El endpoint de mensajería no está afectado

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.