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 todo lo que desea hacer es apuntar el agente al código que reside detrás de un punto de conexión de AWS, solo necesita este paso adicional: Configurar para alojamiento fuera de Azure y siga todos los demás pasos de Comenzar con el desarrollo de 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 las plataformas 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 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 o 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 conectado.
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

Creación de un 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.

Crea el directorio del proyecto
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Inicializar el proyecto Node

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

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.

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

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

Cree a365.config.json manualmente en la carpeta de su proyecto de Cloud Run:

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

Campo	Significado
`messagingEndpoint`	URL de tu Cloud Run + `/api/messages`
`deploymentProjectPath`	Donde `.env` se produce el estampado

Agente de construcción 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ía una GET solicitud para el messagingEndpoint valor de tu 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.

Agente de prueba que aparece del Agente 365

En función de su entorno, use:

Sitio de prueba 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:

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 verificación de estado:
```
curl http://localhost:8080/
```
Realizar cambios en el código

Edite index.js y guarde los cambios.

Reimplementación en Google Cloud Run

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

Prueba y supervisión

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

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.

Sugerencia

La Guía de Resolución de Problemas del Agente 365 contiene recomendaciones de alto nivel para la solución de problemas, mejores prácticas y enlaces a contenido de solución de problemas para cada parte del ciclo de vida del desarrollo del Agente 365.

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.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-01