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 a arquitetura, enquanto o Google Cloud Run fornece o ambiente de execução.

Se tudo o que você quer é apontar seu agente para seu código que está atrás de um endpoint 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 Agente 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 Blueprint do Agente no Entra ID
• Configurar OAuth2 + permissões herdadas
• Registrar o endpoint de mensagens do Bot Framework apontando para o GCP
• Criar Identidade de Agente + Usuário de Agente
• Publicar nas interfaces de aplicativos 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 cliente do Microsoft Entra e instale as seguintes ferramentas para criar identidades, planos e registrar o seu agente.

• Um inquilino do Microsoft Entra com:

  • Permissão/função para criar aplicações e modelos de agentes (Administrador Global ou equivalente)
  • Você precisa fazer parte do programa de prévia 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

• Azure CLI instalado e conectado.

• CLI do Agente 365 instalado

Pré-requisitos do GCP

• Projeto GCP criado

• API Cloud Run habilitada

• SDK 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 Deploar Agente 365 no Cloud Run

Este exemplo usa um agente de exemplo mínimo que:

• Responde ao GET /
• Aceita atividades do Bot Framework no POST /api/messages

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

3. Criar index.js

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

Implantar no Google Cloud Run

Use gcloud run deploy para construir e executar o serviço no Cloud Run, depois anote a URL pública do seu 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 fora do 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.

Agente Build Agent 365

Depois que você tiver o código do seu agente rodando em um endpoint da AWS, siga os passos restantes do Ciclo de Vida de Desenvolvimento do Agente 365 para configurar seu agente do Agente 365.

Verifique o agente de ponta a ponta

Use essas verificações para confirmar que seu agente hospedado no GCP está acessível, recebendo atividades do Bot Framework e respondendo corretamente em todas as superfícies do Agente 365.

Verificar a conectividade Cloud Run

Envie uma solicitação GET para o valor messagingEndpoint do 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 chega ao seu agente, você deve ver:

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

Agente de teste emerge do Agente 365

Dependendo do seu ambiente:

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

Agora você pode enviar mensagens e verificar seus logs do Cloud Run. E você também pode aprender a testar agentes usando o Microsoft Agent 365 SDK e validar a funcionalidade do seu agente com a ferramenta de teste Agents Playground.

Fluxo de Trabalho do Desenvolvedor

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

1. Mude o código do seu agente

   Faça suas alterações no código, salve e teste localmente antes de implantar.

2. Reimplantar para o Google Cloud Run

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

3. Testar e monitorar.

   Teste via superfícies do Agent 365 e monitore os logs do Google Cloud Run.

   Observação

   Sua identidade, blueprint, endpoint do bot e permissões NÃO precisam ser recriados.

Resolução de problemas

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

O endpoint de mensagens não foi atingido

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.