Vytvořte agenta Agent 365 nasazeného v Google Cloud Platform (GCP)

Naučte se, jak vytvořit, hostovat, registrovat a publikovat agenta Agent 365 běžícího na Google Cloud Run pomocí Agent 365 CLI. Microsoft Entra & Graph poskytuje identitu agenta, oprávnění a blueprint, zatímco Google Cloud Run poskytuje běhové prostředí.

Pokud chcete pouze nasměrovat svého agenta na svůj kód umístěný za koncovým bodem AWS, potřebujete jen tento další krok: Konfigurace pro ne-azure hosting a poté postupujte podle všech ostatních kroků z Začínáme s vývojem Agent 365.

Cíle

Naučte se používat Agent 365 a Microsoft 365 jako „řídicí úroveň“ a:

Nasadit modul runtime agenta na Google Cloud Run
Konfigurace a365.config.json pro hostování mimo Azure
Vytvořit podrobného plánu agenta v Entra ID
Konfigurovat OAuth2 a dědičná oprávnění
Zaregistrujte koncový bod zpráv Bot Framework směřující na GCP
Vytvořte identitu agenta a uživatele agenta
Publikujte na plochy aplikací Microsoft 365
Testování interakcí od začátku do konce

Předpoklady

Než začnete, ujistěte se, že máte splněny následující požadavky pro Azure / Microsoft 365, Google Cloud Platform (GCP) a lokální prostředí.

Předpoklady Azure / Microsoft 365

Potvrďte přístup ke svému klientovi Microsoft Entra a nainstalujte následující nástroje pro vytváření identit, podrobných plánů a registraci svého agenta.

Klient Microsoft Entra ID s:
- Oprávnění nebo role k vytváření aplikací a podrobných plánů agentů (Globální správce nebo ekvivalent)
- Musíte být součástí verze Preview programu Frontier, abyste získali předčasný přístup k Microsoft Agent 365.
- Alespoň jedna licence Microsoft 365 je dostupná pro uživatele agenta.
Azure CLI nainstalovaná a přihlášená.
Rozhraní příkazového řádku Agent 365 nainstalované

Předpoklady GCP

Projekt GCP vytvořen
Cloud Run API povoleno

gcloud SDK nainstalován a ověřen

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

Předpoklady místního vývojového prostředí

Editor kódu: Jakýkoli editor kódu dle vašeho výběru. Visual Studio Code je doporučen.
(Volitelné) Node.js. Můžete použít jakýkoli jazyk pro svého agenta. Tento článek používá Node 18+ v následujících krocích.
Přístup k LLM API: Vyberte vhodnou službu podle konfigurace vašeho agenta nebo preferovaného poskytovatele modelu:
- Klíč API OpenAI: Získejte svůj klíč API OpenAI
- Azure OpenAI: Vytvořte a nasazujte prostředek Azure OpenAI pro získání svého API klíče a koncového bodu

Vytvořte a nasaďte agenta Agent 365 do služby Cloud Run

Tento příklad používá minimálního agenta Agenta 365, který:

Reaguje na GET /
Přijímá aktivity Bot Framework na POST /api/messages
Používá autentizaci JWT pomocí Agent 365 SDK
Obsahuje veškerý kód v jednom souboru index.js pro jednoduchost

Vytvoření projektu

Postupujte podle těchto kroků k vytvoření základního agenta Node.js, který běží na Cloud Run a přijímá aktivity Bot Framework.

Vytvoření adresáře projektu
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Inicializace projektu Node.js

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

Vytvořit: 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}`));

Nasazení na Google Cloud Run

Použijte gcloud run deploy k sestavení a spuštění služby na Cloud Run. Po dokončení nasazení si poznamenejte veřejnou URL své messagingEndpoint.

Použijte následující příkazy k nasazení svého projektu do Google Cloud Run:

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

Po dokončení si poznamenejte koncový bod:
```
https://gcp-a365-agent-XXXX-uc.run.app
```
Tato URL je messagingEndpoint, kterou použijete s nástrojem Agent 365 Dev Tools CLI v dalším kroku.

Konfigurace pro hostování mimo Azure

Ručně vytvořte a365.config.json ve složce svého projektu 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"
}

Následující tabulka shrnuje důležitá konfigurační pole a jejich účel.

Pole	Význam
`messagingEndpoint`	Vaše Cloud Run URL + `/api/messages`
`deploymentProjectPath`	Kde dochází k označování `.env`

Vytvoření agenta Agent 365

Po nasazení kódu agenta na koncový bod GCP pokračujte podle zbývajících kroků z vývojového životního cyklu Agent 365 a dokončete nastavení svého agenta Agent 365. Tento proces zahrnuje:

Vytvoření identity agenta v Microsoft Entra ID
Registrace koncového bodu pro zprávy Bot Framework
Vytvoření uživatele agenta
Publikování na rozhraní Microsoft 365

Rozhraní příkazového řádku Agent 365 většinu těchto kroků provádí automaticky podle vaší konfigurace a365.config.json.

Ověření agenta v celém procesu

Pomocí těchto kontrol ověříte, že váš agent hostovaný na GCP je dosažitelný, přijímá aktivity Bot Framework a správně reaguje napříč kanály Agent 365.

Ověření připojení ke službě Cloud Run

Pošlete požadavek GET na hodnotu messagingEndpoint uvedenou ve vašem a365.config.json:

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

Tělo odpovědi by mělo obsahovat:

GCP Agent is running.

Zkontrolujte protokoly služby Cloud Run na příchozí zprávy Bot Frameworku

Můžete zkontrolovat Google Cloud Log Explorer nebo spustit:

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

Po doručení zprávy vašemu agentovi vidíte záznamy v logech, které ukazují, že server přijal a zpracoval aktivitu prostřednictvím Agent 365 SDK.

Testování agenta z prostředí Agentu 365

V závislosti na vašem prostředí použijte:

Agents Playground
Teams (je-li agent publikován)
Agent Shell

Nyní můžete posílat zprávy a kontrolovat protokoly Cloud Run. Další informace najdete v tématu Jak testovat agenty pomocí Microsoft Agent 365 SDK a ověřovat funkčnost vašeho agenta pomocí testovacího nástroje Agents Playground.

Pracovní postup vývojáře

Po dokončení nastavení postupujte podle tohoto postupu pro iterativní vývoj:

Testujte lokálně (volitelně)

Pro testování agenta lokálně před nasazením do Cloud Run se ujistěte, že váš soubor .env obsahuje správné přihlašovací údaje:
```
# Start the agent locally
node index.js
```
Váš agent je k dispozici na http://localhost:8080. Můžete otestovat koncový bod stavu:
```
curl http://localhost:8080/
```
Provedení změn kódu

Upravte index.js a uložte změny.

Opětovné nasazení na Google Cloud Run

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

Testování a monitorování

Testujte prostřednictvím rozhraní Agent 365 a sledujte protokoly Google Cloud Run.

Řešení problému

Použijte tuto sekci k diagnostice běžných problémů při nasazování a provozování vašeho agenta Agent 365 na Google Cloud Run. Pomáhá vám rychle aplikovat opravy problémů s připojením, konfigurací a licencováním.

Zpropitné

Průvodce odstraňováním problémů Agent 365 obsahuje doporučení k odstraňování problémů na vysoké úrovni, osvědčené postupy a odkazy na obsah o řešení problémů pro každou část životního cyklu vývoje Agent 365.

Koncový bod pro zasílání zpráv není dosažen

Zkontrolujte následující údaje:

Koncový bod je přesně:
https://<cloud-run-url>/api/messages
Cloud Run umožňuje neověřený přístup
Žádná pravidla brány firewall

Přiřazení licence selže

Platnou licenci Microsoft 365 Frontier přiřaďte manuálně, nebo použijte cestu pro nelicencované uživatele, pokud je podporována.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-30