Criar um agente do Agent 365 implementado no Google Cloud Platform (GCP)

Saiba como criar, alojar, registar e publicar um agente do Agent 365 ao executar no Google Cloud Run, utilizando a CLI do Agent 365. O Microsoft Entra & Graph fornece a identidade do agente, as permissões e o esquema, enquanto o Google Cloud Run fornece o runtime.

Caso apenas pretenda direcionar o seu agente para o seu código que reside atrás de um ponto final do AWS, apenas precisa deste passo adicional: Configurar para alojamento fora do Azure e depois seguir todos os outros passos descritos em Introdução ao desenvolvimento do Agent 365.

Objetivos

Saber como utilizar o Agent 365 e o Microsoft 365 como "plano de controlo" e:

• Implementar o runtime do agente no Google Cloud Run
• Configurar o a365.config.json para alojamento fora do Azure
• Criar o Esquema de Agente no Entra ID
• Configurar o OAuth2 + permissões herdáveis
• Registar o ponto final de mensagens do Bot Framework direcionado para o GCP
• Criar Identidade de Agente + Utilizador de Agente
• Publicar nas superfícies de aplicação do Microsoft 365
• Testar interações ponto a ponto

Pré-requisitos

Antes de começar, certifique-se de que os seguintes pré-requisitos do Azure/Microsoft 365, Google Cloud Platform (GCP) e ambiente local foram cumpridos.

Pré-requisitos do Azure/Microsoft 365

Confirme o acesso ao seu inquilino do Microsoft Entra e instale as seguintes ferramentas para criar identidades, esquemas e registar o seu agente.

• Um inquilino do Microsoft Entra com:

  • Permissão ou função para criar aplicações e esquemas de agente (Administrador Global ou equivalente)
  • É necessário fazer parte do Programa de pré-visualização Frontier para obter acesso antecipado ao Microsoft Agent 365.
  • Pelo menos uma licença do Microsoft 365 disponível para o utilizador do agente

• CLI do Azure instalada e sessão iniciada.

• CLI do Agent 365 instalada

Pré-requisitos do GCP

• Projeto GCP criado

• API do Cloud ativada

• 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 para o ambiente de desenvolvimento local

• Editor de Código: qualquer editor de código à sua escolha. É recomendado o Visual Studio Code.

• (Opcional) Node.js. Pode utilizar qualquer linguagem para o seu agente. Este artigo utiliza Node 18+ nos passos seguintes.

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

  • Chave de API OpenAI: obtenha a sua chave de API OpenAI
  • Azure OpenAI: crie e implemente um recurso do Azure OpenAI para obter a chave de API e o ponto final

Criar e implementar um agente do Agent 365 no Cloud Run

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

• Responde a GET /
• Aceita atividades do Bot Framework em POST /api/messages
• Utilizar a autenticação do JWT com o SDK do Agent 365
• Contém todo o código num único ficheiro index.js para simplificar

Criar o projeto

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

1. Criar o diretório do projeto

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

2. Inicializar o projeto do Node

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

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

Implementar no Google Cloud Run

Utilize o gcloud run deploy para criar e executar o serviço no Cloud Run. Quando a implementação terminar, anote o URL público do seu messagingEndpoint.

1. Utilize os seguintes comandos para implementar o seu projeto no Google Cloud Run:

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

2. Quando terminar, anote o seu ponto final:

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

   Este URL corresponde ao messagingEndpoint utilizado pela CLI do Agent 365 Dev Tools no próximo passo.

Configurar para alojamento fora do Azure

Crie o a365.config.json manualmente no diretório do projeto do 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"
}

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

Campo	Significado
messagingEndpoint	O seu URL do Cloud Run + /api/messages
deploymentProjectPath	Onde ocorre o carimbo de .env

---

Criar o agente do Agent 365

Após implementar o código do seu agente no ponto final do GCP, siga os passos restantes do Ciclo de Vida de Desenvolvimento do Agent 365 para concluir a configuração do seu agente do Agent 365. Este processo inclui:

• Criar a identidade do agente no Microsoft Entra ID
• Registar o ponto final das mensagens do Bot Framework
• Criar o utilizador do agente
• Publicar em superfícies do Microsoft 365

O CLI do Agent 365 processa automaticamente a maioria destes passos com base na configuração do seu a365.config.json.

Verificar o agente ponto a ponto

Faça estas verificações para confirmar que o seu agente alojado no GCP está acessível, recebe atividades do Bot Framework e responde corretamente nas interfaces do Agent 365.

Verificar a conectividade do Cloud Run

Envie um pedido GET para o valor messagingEndpoint do seu a365.config.json:

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

O corpo da resposta deve incluir:

GCP Agent is running.

Verificar os registos do Cloud Run para as mensagens do Bot Framework recebidas

Pode verificar o Google Cloud Log Explorer ou executar:

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

Depois de uma mensagem chegar ao seu agente, verá entradas de registo que indicam que o servidor recebeu e processou a atividade através do SDK do Agent 365.

Agente de teste a partir de superfícies do Agent 365

Dependendo do seu ambiente, utilize:

• Ambiente de Demonstração de Agentes
• Teams (se publicado)
• Shell do Agente

Agora pode enviar mensagens e verificar os registos do Cloud Run. Para obter mais informações, consulte Saber como testar agentes utilizando o SDK do Microsoft Agent 365 e validando a funcionalidade do seu agente com a ferramenta de teste Ambiente de Demonstração de Agentes.

Fluxo de trabalho do programador

Depois de concluir a configuração, siga este fluxo de trabalho para desenvolvimento iterativo:

1. Testar localmente (Opcional)

   Para testar o agente localmente antes de implementar no Cloud Run, certifique-se de que o ficheiro .env contém as credenciais corretas:

   # Start the agent locally
   node index.js
   

   O seu agente está disponível em http://localhost:8080. Pode testar o ponto final do estado de funcionamento:

   curl http://localhost:8080/
   

2. Efetue as alterações de código

   Edite o index.js e guarde as alterações.

3. Reimplementar no Google Cloud Run

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

4. Testar e monitorizar

   Teste através de superfícies do Agent 365 e monitorize os registos do Google Cloud Run.

Resolução de Problemas

Utilize esta secção para diagnosticar problemas comuns ao implementar e executar o seu agente do Agent 365 no Google Cloud Run. Ajuda-o a aplicar rapidamente correções para problemas de conectividade, configuração e licenciamento.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

O ponto final de mensagens não é alcançado

Verifique os detalhes seguintes:

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

A atribuição de licenças falha

Atribua manualmente uma licença do Microsoft 365 Frontier válida ou utilize um caminho de utilizador não licenciado, se for suportado.