Compartilhar via

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

Importante

Você precisa fazer parte do programa de prévia Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. Prévias da Frontier estão sujeitas aos termos de pré-visualização existentes dos seus contratos com clientes. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

Aprenda a construir, hospedar, registrar e publicar um agente Agent 365 rodando no Google Cloud Run, usando a CLI do Agent 365. O Microsoft Entra & Graph fornece a identidade do agente, permissões e blueprint, enquanto o Google Cloud Run fornece o tempo 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: configure para hospedagem não Azure e depois siga todos os outros passos do ciclo de vida do Agente 365.

Objetivos

Aprenda a usar o Agent 365 e o Microsoft 365 como o 'plano de controle' e:

  • Deploy agent runtime no Google Cloud Run
  • Configure a365.config.json para hospedagem não-Azure
  • Criar Blueprint do Agente no Entra ID
  • Configurar OAuth2 + permissões herdadas
  • Registrar o ponto final de mensagens do Bot Framework apontando para o GCP
  • Criar Identidade de Agente + Usuário de Agente
  • Publicar para as superfícies de aplicativos do Microsoft 365
  • Interações de teste de ponta a ponta

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 estejam cumpridos.

Azure / Microsoft 365 prerequisites

Confirme o acesso ao seu tenant Microsoft Entra e instale as seguintes ferramentas para criar identidades, projetos e registrar seu agente.

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

  • Um editor de texto ou editor de código de sua escolha. O Visual Studio Code é recomendado

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

  • 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 365 para Nuvem Executar

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 rodar o serviço no Cloud Run, depois anote a URL pública do seu messagingEndpointarquivo .

  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

    Essa URL é usada messagingEndpoint pela CLI do Agent 365 Dev Tools na próxima etapa.

Configure for Non-Azure Hosting

Crie a365.config.json na sua nuvem a pasta do projeto 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.

Campo Meaning
messagingEndpoint URL do seu Cloud Run + /api/messages
"needDeployment"=false Diz ao CLI: 'Eu hospedo meu próprio servidor; não deploy para Azure'
deploymentProjectPath Onde .env ocorre o carimbo

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 GET solicitação para o messagingEndpoint valor 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 de execução na nuvem 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 a partir de superfícies do Agente 365

Dependendo do seu ambiente:

  • Playground de agentes
  • Times (se 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 manualmente uma licença Frontier válida do Microsoft 365, ou use um caminho de usuário não licenciado, se for suportado.

Obtendo ajuda

Mais opções de ajuda

Considere o seguinte para encontrar ajuda:

  • Last updated on