Build an Agent 365 agent deployed in Google Cloud Platform (GCP)

Learn how to build, host, register, and publish an Agent 365 agent running on Google Cloud Run, using the Agent 365 CLI. Microsoft Entra & Graph provides the agent identity, permissions, and blueprint, while Google Cloud Run provides the runtime.

If all you want to do is point your agent to your code residing behind an AWS endpoint, you only need this additional step: Configure for non-azure hosting and then follow all other steps from Agent 365 Development Lifecycle.

Goals

Learn how to use Agent 365 and Microsoft 365 as the 'control plane' and:

• Deploy agent runtime on Google Cloud Run
• Configure a365.config.json for non‑Azure hosting
• Create Agent Blueprint in Entra ID
• Configure OAuth2 + inheritable permissions
• Register Bot Framework messaging endpoint pointing to GCP
• Create Agent Identity + Agent User
• Publish to Microsoft 365 app surfaces
• Test interactions end-to-end

Prerequisites

Before you begin, ensure the following Azure / Microsoft 365, Google Cloud Platform (GCP), and local environment prerequisites are met.

Azure / Microsoft 365 prerequisites

Confirm your Microsoft Entra tenant access and install the following tools to create identities, blueprints, and register your agent.

• A Microsoft Entra tenant with:

  • Permission or role to create applications and agent blueprints (Global Administrator or equivalent)
  • You need to be part of the Frontier preview program to get early access to Microsoft Agent 365.
  • At least one Microsoft 365 license available for the Agent user

• Azure CLI installed and signed in.

• Agent 365 CLI installed

GCP prerequisites

• GCP project created

• Cloud Run API enabled

• gcloud SDK installed and authenticated

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

Local development environment prerequisites

• Code Editor: Any code editor of your choice. Visual Studio Code is recommended.

• (Optional) Node.js. You can use any language for your agent. This article uses Node 18+ in the following steps.

• LLM API access: Choose the appropriate service based on your agent's configuration or your preferred model provider:

  • OpenAI API Key: Get your OpenAI API key
  • Azure OpenAI: Create and deploy an Azure OpenAI resource to get your API key and endpoint

Create and deploy Agent 365 agent to Cloud Run

This example uses a minimal Agent 365 agent that:

• Responds to GET /
• Accepts Bot Framework activities on POST /api/messages
• Uses JWT authentication via the Agent 365 SDK
• Contains all code in a single index.js file for simplicity

Create project

Follow these steps to scaffold a minimal Node.js agent that runs on Cloud Run and accepts Bot Framework activities.

1. Create the project directory

   mkdir gcp-a365-agent
   cd gcp-a365-agent
   

2. Initialize the Node project

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

3. Create 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}`));
   

Deploy to Google Cloud Run

Use gcloud run deploy to build and run the service on Cloud Run. When the deployment finishes, note the public URL for your messagingEndpoint.

1. Use the following commands to deploy your project to Google Cloud Run:

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

2. When finished, note your endpoint:

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

   This URL is the messagingEndpoint used by the Agent 365 Dev Tools CLI in the next step.

Configure for Non-Azure Hosting

Create a365.config.json in your Cloud Run project folder by running 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"
}

The following table summarizes important configuration fields and their purpose.

Build Agent 365 agent

After deploying your agent code to your GCP endpoint, follow the remaining steps from Agent 365 Development Lifecycle to complete the setup of your Agent 365 agent. This process includes:

• Creating the agent identity in Microsoft Entra ID
• Registering the Bot Framework messaging endpoint
• Creating the agent user
• Publishing to Microsoft 365 surfaces

The Agent 365 CLI handles most of these steps automatically based on your a365.config.json configuration.

Verify the agent end-to-end

Use these checks to confirm your GCP-hosted agent is reachable, receives Bot Framework activities, and responds correctly across Agent 365 surfaces.

Verify Cloud Run connectivity

Send a GET request to the messagingEndpoint value from your a365.config.json:

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

The response body should include:

GCP Agent is running.

Check Cloud Run logs for incoming Bot Framework messages

You can check Google Cloud Log Explorer or run:

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

After a message hits your agent, you see log entries that indicate the server received and processed the activity through the Agent 365 SDK.

Test agent from Agent 365 surfaces

Depending on your environment, use:

• Agents Playground
• Teams (if published)
• Agent Shell

You can now send messages and verify your Cloud Run logs. To learn more, see Learn how to test agents using the Microsoft Agent 365 SDK and validating your agent's functionality with the Agents Playground testing tool.

Developer workflow

Once setup is complete, follow this workflow for iterative development:

1. Test locally (optional)

   To test your agent locally before deploying to Cloud Run, ensure your .env file contains the correct credentials:

   # Start the agent locally
   node index.js
   

   Your agent is available at http://localhost:8080. You can test the health endpoint:

   curl http://localhost:8080/
   

2. Make your code changes

   Edit index.js and save your changes.

3. Redeploy to Google Cloud Run

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

4. Test and monitor

   Test via Agent 365 surfaces and monitor Google Cloud Run logs.

Troubleshooting

Use this section to diagnose common issues when deploying and running your Agent 365 agent on Google Cloud Run. It helps you quickly apply fixes for connectivity, configuration, and licensing problems.

Messaging endpoint isn't reached

Check the following details:

• The endpoint is exactly:
  https://<cloud-run-url>/api/messages
• Cloud Run allows unauthenticated access
• No firewall rules

License assignment fails

Assign a valid Microsoft 365 frontier license manually, or use an unlicensed user path if supported.