Rakenna ja ota käyttöön Agent 365 -agentti Google Cloud Platformissa (GCP)

Opi rakentamaan, isännöimään, rekisteröimään ja julkaisemaan Agent 365 -agentin, joka toimii Google Cloud Run -ympäristössä, hyödyntäen Agent 365 CLI -työkalua. Microsoft Entra & Graph tarjoaa agentin identiteetin, käyttöoikeudet ja blueprintin, kun taas Google Cloud Run tarjoaa suoritusympäristön.

Jos haluat vain suunnata agenttisi AWS-päätepisteen takana olevaan koodiin, tarvitset vain tämän lisävaiheen: Konfiguroi muulle kuin Azure-isännöinnille ja seuraa sitten muita vaiheita Agent 365 -kehityksen aloitus.

Tavoitteet

Opi käyttämään Agent 365:tä ja Microsoft 365:ttä hallintatasona ja:

Ota käyttöön agentin suorituksenaikainen ympäristö Google Cloud Runissa
Määritä a365.config.json muulle kuin Azure-isännöinnille
Luo agentin blueprint Entra ID -tunnus:ssä
Määritä OAuth2 + periytyvät käyttöoikeudet
Rekisteröi Bot Frameworkin viestintäpäätepiste, joka on osoitettu GCP:hen
Luo agentin identiteetti + agentin käyttäjä
Julkaise Microsoft 365 -sovelluksiin
Testaa vuorovaikutukset kaikenkattavasti

Edellytykset

Ennen kuin aloitat, varmista, että seuraavat Azure / Microsoft 365-, Google Cloud Platform (GCP)- ja paikallisen ympäristön vaatimukset on täytetty.

Azuren/Microsoft 365:n edellytykset

Varmista, että sinulla on pääsy Microsoft Entra -vuokraajaan ja asenna seuraavat työkalut identiteettien, blueprintien luomista sekä agentin rekisteröintiä varten.

Microsoft Entra -vuokraaja, jolla on:
- Käyttöoikeus tai rooli sovellusten ja agentti-blueprintien luomiseen (Global Administrator tai muu vastaava rooli)
- Sinun täytyy olla mukana Frontier-esiversio-ohjelmassa saadaksesi ennakkopääsyn Microsoft Agent 365:een.
- Agentti-käyttäjälle on oltava vähintään yksi Microsoft 365 -lisenssi saatavilla
Azure CLI asennettuna ja sisäänkirjautuneena.
Agent 365 CLI asennettuna

GCP-edellytykset

GCP-projekti luotu
Cloud Run API käytössä

gcloud SDK asennettu ja todennettu

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

Paikallisen kehitysympäristön vaatimukset

Koodieditori: Valitsemasi koodieditori käy. Visual Studio Code suositeltu.
Node.js (valinnainen). Voit käyttää mitä tahansa kieltä agentillesi. Tässä artikkelissa käytetään Node 18+:ta seuraavissa vaiheissa.
LLM API -yhteys: Valitse sopiva palvelu agentin määritysten tai haluamasi mallitoimittajan mukaan.
- OpenAI API-avain: Hanki OpenAI API-avain
- Azure OpenAI: Luo ja ota käyttöön Azure OpenAI-resurssi saadaksesi API-avaimen ja päätepisteen

Luo ja ota Agent 365 agentti käyttöön Cloud Runissa

Tässä esimerkissä käytetään minimaalista Agent 365 -agenttia, joka:

Vastaa GET:iin /
Hyväksyy Bot Framework -aktiviteetit POST-pyynnössä /api/messages
Käyttää JWT-tunnistautumista Agent 365 SDK:lla
Kaikki koodi on yhdessä index.js-tiedostossa yksinkertaisuuden vuoksi

Projektin luominen

Noudata näitä ohjeita luodaksesi minimalistisen Node.js-agentin, joka toimii Cloud Runissa ja vastaanottaa Bot Framework aktiviteetteja.

Luo projektihakemisto
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Alusta Node-projekti

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

Luo 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}`));

Julkaise Google Cloud Runiin

Käytä gcloud run deploy palvelun rakentamiseen ja ajamiseen Cloud Runissa. Kun käyttöönotto päättyy, huomioi palvelusi julkinen URL-osoite messagingEndpoint.

Käytä seuraavia komentoja julkaistaksesi projektisi Google Cloud Runiin:

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

Kun olet valmis, kirjaa ylös päätepisteesi:
```
https://gcp-a365-agent-XXXX-uc.run.app
```
Tämä URL-osoite on messagingEndpoint, jota Agent 365 Dev Tools CLI käyttää seuraavassa vaiheessa.

Määritykset muuta kuin Azure-isännöintiä varten

Luo a365.config.json käsin Cloud Run -projektikansioon:

{
  "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"
}

Seuraava taulukko tiivistää tärkeät määrityskentät ja niiden tarkoituksen.

Kenttä	Merkitys
`messagingEndpoint`	Cloud Run -URL-osoitteesi + `/api/messages`
`deploymentProjectPath`	Missä `.env`-leimaus suoritetaan

Rakenna Agent 365 -agentti

Kun olet ottanut agenttikoodisi käyttöön GCP-päätepisteessäsi, jatka Agent 365 Development Lifecycle -ohjeen jäljellä olevien vaiheiden suorittamista Agent 365 -agentin käyttöönoton viimeistelemiseksi. Näitä käsittelyjä ovat:

Agentin identiteetin luominen Microsoft Entra ID:ssä
Bot Frameworkin viestipäätepisteen rekisteröinti
Agenttikäyttäjän luominen
Julkaiseminen Microsoft 365 -alustoille

Agent 365 CLI hoitaa suurimman osan näistä vaiheista automaattisesti a365.config.json-määrityksen perusteella.

Tarkasta agentti perusteellisesti

Käytä näitä tarkistuksia varmistaaksesi, että GCP:ssä isännöity agentti on tavoitettavissa, vastaanottaa Bot Framework -aktiviteetteja ja vastaa oikein Agent 365 -alustoilla.

Varmista Cloud Run -yhteys

Lähetä GET-pyyntö messagingEndpoint-arvoon, joka on määritetty a365.config.json-määrityksessäsi:

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

Vastauksen rungossa tulisi olla:

GCP Agent is running.

Tarkista Cloud Run -lokit saapuvien Bot Framework -viestien osalta

Voit tarkistaa Google Cloud Log Explorerin tai suorittaa seuraavan komennon:

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

Kun viesti saapuu agentillesi, näet lokimerkintöjä, jotka osoittavat, että palvelin on vastaanottanut ja käsitellyt aktiviteetin Agent 365 SDK:n kautta.

Agent 365 -pinnoilta peräisin oleva testiagentti

Käytä ympäristöstäsi riippuen:

Agenttien testausalusta
Teams (jos julkaistu)
Agenttien komentoliittymä

Voit nyt lähettää viestejä ja tarkistaa Cloud Run -lokit. Lisätietoja saat kohdasta Lue, miten voit testata agentteja Microsoft Agent 365 SDK:lla ja validoida agenttisi toiminnallisuutta Agents Playground -testaustyökalulla.

Kehittäjän työnkulku

Kun asennus on valmis, seuraa tätä työnkulkua iteratiivisessa kehityksessä:

Testaa paikallisesti (tarvittaessa)

Testataksesi agenttiasi paikallisesti ennen käyttöönottoa Cloud Runissa, varmista, että tiedostossasi .env on oikeat tunnistetiedot:
```
# Start the agent locally
node index.js
```
Agenttisi on saatavilla osoitteessa http://localhost:8080. Voit testata terveysrajapintaa:
```
curl http://localhost:8080/
```
Tee haluamasi koodimuutokset

Muokkaa index.js ja tallenna muutokset.

Julkaise uudelleen Google Cloud Runiin

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

Testaa ja valvo

Testaa Agent 365 -pintojen kautta ja seuraa Google Cloud Run -lokeja.

Vianmääritys

Käytä tätä osiota diagnosoimaan yleisiä ongelmia Agent 365 -agentin käyttöönotossa ja toiminnassa Google Cloud Runissa. Se auttaa sinua nopeasti tekemään korjauksia yhteys-, konfigurointi- ja lisenssiongelmiin.

Vinkki

Agent 365:n vianmääritysopas sisältää yleisluontoisia vianmääritykseen liittyviä suosituksia, parhaita käytäntöjä sekä linkkejä vianmääritykseen liittyvään sisältöön Agent 365:n kehityksen elinkaaren kaikissa vaiheissa.

Viestinvälityspäätepisteeseen ei saada yhteyttä

Tarkista seuraavat tiedot:

Päätepiste on tarkalleen:
https://<cloud-run-url>/api/messages
Cloud Run sallii pääsyn ilman tunnistautumista
Ei palomuurisääntöjä

Käyttöoikeuden määritys epäonnistuu

Määritä voimassa oleva Microsoft 365 Frontier -lisenssi manuaalisesti tai käytä lisensoimatonta käyttäjäpolkua, jos se on tuettu.

Palaute

Onko tästä sivusta apua?

Last updated on 2026-07-30