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ê deseja fazer é apontar seu agente para o código que reside atrás de um endpoint da AWS, você só precisará desta etapa adicional: Configurar para hospedagem não Azure e, em seguida, seguir todas as outras etapas do Get Started with Agent 365 development.

Metas

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.

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:

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 fora do Azure

Crie a365.config.json manualmente na pasta do projeto 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 a seguir resume campos de configuração importantes e seu propósito.

Campo Significado
messagingEndpoint URL do seu Cloud Run + /api/messages
deploymentProjectPath Onde ocorre a estampagem .env

Agente Build 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.

Verifique 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 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 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.

Agente de teste emerge do Agente 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 ponto de extremidade da integridade:

    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 via superfícies do Agent 365 e monitore os logs do Google Cloud Run.

Solucionando 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.

Tip

O Guia de Solução de Problemas do Agente 365 contém recomendações de resolução de problemas de alto nível, melhores práticas e links para conteúdo de solução de problemas para cada parte do ciclo de desenvolvimento do Agente 365.

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.

  • Last updated on