Construa um agente Agent 365 implantado na Google Cloud Platform (GCP)

Aprenda a construir, hospedar, registrar e publicar um agente Agent 365 rodando no Google Cloud Run, usando a CLI do Agent 365. Microsoft Entra e Graph fornecem a identidade do agente, as permissões e o plano, enquanto o Google Cloud Run proporciona o tempo de execução.

Se tudo o que você quer é apontar seu agente para seu código que está atrás de um ponto de extremidade da AWS, você só precisa deste passo adicional: Configurar para hospedagem não-Azure e depois siga todos os outros passos do Ciclo de Vida do Agent 365.

Objetivos

Saiba como usar o Agente 365 e Microsoft 365 como o "plano de controle" e:

• Implantar o runtime do agente no Google Cloud Run
• Configurar a365.config.json para hospedagem não Azure
• Criar Agent Blueprint no Entra ID
• Configurar OAuth2 + permissões herdadas
• Registrar o ponto de extremidade do sistema de mensagens do Bot Framework apontando para o GCP
• Criar Identidade de Agente + Usuário de Agente
• Publicar em plataformas do Microsoft 365
• Testar interações de ponta a ponta

Pré-requisitos

Antes de começar, verifique se os seguintes Azure/Microsoft 365, GCP (Google Cloud Platform) e pré-requisitos de ambiente local são atendidos.

pré-requisitos de Azure/Microsoft 365

Confirme seu acesso ao locatário do Microsoft Entra e instale as seguintes ferramentas para criar identidades, modelos e registrar seu agente.

• Um locatário Microsoft Entra com:

  • Permissão ou função para criar aplicativos e modelos de agente (Administrador Global ou equivalente)
  • Você precisa fazer parte do programa de visualização Frontier para obter acesso antecipado ao Microsoft Agent 365.
  • Pelo menos uma licença de Microsoft 365 disponível para o usuário do Agente

• CLI do Azure instalado e conectado.

• CLI do Agente 365 instalado

Pré-requisitos do GCP

• Projeto GCP criado

• API Cloud Run habilitada

• SDK do gcloud instalado e autenticado

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

Pré-requisitos do ambiente de desenvolvimento local

• Editor de Código: Qualquer editor de código de sua escolha. Visual Studio Code é recomendável.

• (Opcional) Node.js. Você pode usar qualquer linguagem para seu agente. Este artigo utiliza o Node.js 18+ nos passos seguintes.

• Acesso à API LLM: Escolha o serviço apropriado com base na configuração do seu agente ou no seu provedor de modelo preferido:

  • Chave da API OpenAI: Obtenha sua chave API OpenAI
  • Azure OpenAI: Criar e implantar um recurso Azure OpenAI para obter a chave e o ponto de extremidade da API

Criar e implantar agente do Agente 365 na Cloud Run

Este exemplo usa um agente mínimo do Agent 365 que:

• Responde ao GET /
• Aceita atividades do Bot Framework no POST /api/messages
• Usa a autenticação JWT por meio do SDK do Agent 365
• Contém todo o código em um único index.js arquivo para simplificar

Criar projeto

Siga estes passos para estruturar um agente Node.js mínimo que roda no Cloud Run e aceite atividades do Bot Framework.

1. Crie o diretório do projeto

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

2. Inicializar o projeto Node

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

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

Implantar no Google Cloud Run

Use gcloud run deploy para criar e executar o serviço na Cloud Run. Quando a implantação for concluída, anote a URL pública para sua messagingEndpoint.

1. Use os seguintes comandos para implantar seu projeto no Google Cloud Run:

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

2. Quando terminar, anote seu ponto final:

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

   Na próxima etapa, o CLI do Agent 365 Dev Tools usará essa URL messagingEndpoint.

Configurar para hospedagem não-Azure

Crie a365.config.json na pasta do projeto Cloud Run executando 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"
}

A tabela a seguir resume campos de configuração importantes e seu propósito.

Compilar agente do Agent 365

Depois de implantar o código do agente no ponto de extremidade do GCP, siga as etapas restantes do Ciclo de Vida de Desenvolvimento do Agente 365 para concluir a instalação do agente do Agente 365. Esse processo inclui:

• Criando a identidade do agente no Microsoft Entra ID
• Registrando o ponto de extremidade de mensagens do Bot Framework
• Criando o usuário do agente
• Publicando para plataformas do Microsoft 365

A CLI do Agent 365 manipula a maioria dessas etapas automaticamente com base em sua a365.config.json configuração.

Verificar o agente de ponta a ponta

Use essas verificações para confirmar se o agente hospedado pelo GCP é acessível, recebe atividades do Bot Framework e responde corretamente em superfícies do Agente 365.

Verificar a conectividade Cloud Run

Envie uma GET solicitação para o valor do messagingEndpoint de seu a365.config.json:

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

O órgão de resposta deve incluir:

GCP Agent is running.

Verifique os logs do Cloud Run para mensagens recebidas do Bot Framework

Você pode consultar o Google Cloud Log Explorer ou executar:

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

Depois que uma mensagem atingir seu agente, você verá entradas de log que indicam que o servidor recebeu e processou a atividade por meio do SDK do Agente 365.

Testar agente a partir de superfícies do Agent 365

Dependendo do seu ambiente, use:

• Playground de agentes
• Equipes (caso sejam publicados)
• Agente Shell

Agora você pode enviar mensagens e verificar seus logs do Cloud Run. Para saber mais, consulte Aprende como testar agentes usando o SDK do agente Microsoft 365 e validar a funcionalidade do agente com a ferramenta de teste do Agents Playground.

Fluxo de trabalho do desenvolvedor

Uma vez concluída a configuração, siga este fluxo de trabalho para desenvolvimento iterativo:

1. Teste localmente (opcional)

   Para testar o agente localmente antes de implantar na Cloud Run, verifique se o .env arquivo contém as credenciais corretas:

   # Start the agent locally
   node index.js
   

   Seu agente está disponível em http://localhost:8080. Você pode testar o endpoint de saúde:

   curl http://localhost:8080/
   

2. Fazer alterações de código

   Edite index.js e salve suas alterações.

3. Reimplantar para o Google Cloud Run

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

4. Testar e monitorar.

   Teste por meio de superfícies do Agent 365 e monitore os logs do Google Cloud Run.

Resolução de problemas

Use esta seção para diagnosticar problemas comuns ao implantar e executar seu agente do Agent 365 no Google Cloud Run. Ele ajuda você a aplicar rapidamente correções para problemas de conectividade, configuração e licenciamento.

O endpoint de mensagens não foi acessado

Confira os seguintes detalhes:

• O ponto final é exatamente:
  https://<cloud-run-url>/api/messages
• O Cloud Run permite acesso não autenticado
• Sem regras de firewall

Falha na cessão da licença

Atribua uma licença de fronteira Microsoft 365 válida manualmente ou use um caminho de usuário sem licença, se houver suporte.