Share via

How-to: Publish an agent using Google Cloud Platform (GCP)

Important

You need to be part of the Frontier preview program to get early access to Microsoft Agent 365. Frontier connects you directly with Microsoft’s latest AI innovations. Frontier previews are subject to the existing preview terms of your customer agreements. As these features are still in development, their availability and capabilities may change over time.

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.

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.

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:

Create & Deploy A365 Agent to Cloud Run

This example uses a minimal example agent that:

  • Responds to GET /
  • Accepts Bot Framework activities on POST /api/messages

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 body-parser

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

Deploy to Google Cloud Run

Use gcloud run deploy to build and run the service on Cloud Run, then 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.

Field Meaning
messagingEndpoint Your Cloud Run URL + /api/messages
"needDeployment"=false Tells CLI 'I host my own server; don't deploy to Azure'
deploymentProjectPath Where .env stamping happens

Run Agent 365 CLI (a365)

Use the Agent 365 CLI to create the blueprint, grant permissions, and register the Bot Framework messaging endpoint against your GCP Cloud Run URL. These steps assume a365.config.json is prepared and needDeployment is set to false.

Setup command

From the same folder, use the a365 setup all command:

a365 setup all

This command performs:

  • Infrastructure (skipped because needDeployment=false)
  • Create Blueprint
  • Admin consent for Graph scopes
  • Client secret creation
  • Model Context Protocol(MCP) permissions
  • Bot Framework API permissions
  • Register messaging endpoint → GCP URL

Expected result:

[OK] Agent blueprint created
[OK] Messaging endpoint registered
[OK] Messaging Bot API permissions configured

Your a365.generated.config.json contains:

  • agentBlueprintId
  • botId
  • botMessagingEndpoint
  • agentBlueprintClientSecret

Publish Agent to Microsoft 365

If you want users to see your agent in:

  • Microsoft 365 admin center
  • Teams apps and developer portal
  • Microsoft 365 Hub

Use a365 publish to publish the manifest:

a365 publish

This command registers your title and updates your manifest with:

  • Bot ID
  • Agent Blueprint ID
  • Cloud Run messaging endpoint

Onboard the Agent

To complete the A365 agent onboarding workflow, see Onboard A365 Agents and Test agents in Teams. These guides explain how to make your agent available for your organization to discover and create an agent in Microsoft 365 and the Teams App Store.

The following example steps to onboard the Agent from Teams demonstrate how it should work:

  1. Run a365 publish

    After the agent is published, the agent is visible in Teams and Microsoft 365 admin center

  2. Configure the notifications in Teams Developer Portal

    1. Sign-in to the Teams Developer Portal using the following URL:

      https://dev.teams.microsoft.com/tools/agent-blueprint/<YOUR_BLUEPRINT_ID>/configuration

      Replace <YOUR_BLUEPRINT_ID> with your agent blueprint ID.

    2. Find the agent blue print and add API based notification URL to the messagingEndpoint value from your a365.config.json. This URL should be something like: https://gcp-a365-agent-XXXX-uc.run.app. See more details in Configure the Agent Identity Blueprint

  3. Provision agent in Teams App Store

    1. Go to Teams and select the Teams Apps Store tab.
    2. Find and open your agent blueprint under Agent for your Teams.
    3. Send the activation request by clicking the Provision button.

  4. Approve the activation request in Microsoft admin center

    1. Go to the Microsoft admin center > Agents > overview
    2. Ensure there are Microsoft Agent 365 Frontier licenses available for the agent user
    3. Approve the request from the agent blue print under the Requests tab

  5. Create agent instance/user in Teams App Store

    1. Go back to Teams App Store and open your agent blueprint again.
    2. Select Create Instance and create new agent instance/user.

  6. Wait for provisioning, then test:

    • Search the new agent user in Teams by email.
    • Send a chat message to the user.
    • Verify Cloud Run logs show the incoming activity.
    • Verify your bot posts a reply back. This capability requires Bot Framework SDK and environment variables not included in the minimal example included in these instructions.

Verify the agent end-to-end

Use these checks to confirm your GCP-hosted agent is reachable, receiving Bot Framework activities, and responding 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 should see:

POST 200 /api/messages
Received activity: { ... }

Test agent from Agent 365 surfaces

Depending on your environment:

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

You can now send messages and verify your Cloud Run logs. And you can also 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. Change your agent code

    Make your code changes, save, and test locally before deploying.

  2. Redeploy to Google Cloud Run

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

  3. Test and monitor

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

    Note

    Your identity, blueprint, bot endpoint, and permissions DO NOT need to be recreated.

Troubleshooting

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

Messaging endpoint isn't hit

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.

Getting help

More help options

Consider the following to find help:

  • Last updated on