Installing the Willow agent for Microsoft 365 Copilot

This guide is for a Microsoft 365 administrator at your organization. It explains how to take the Willow agent package you downloaded from the Willow platform and make it available to your users inside Microsoft 365 Copilot.

There are three parts:

1. Prepare the tool — install the small command‑line tool used to upload the package (one time).
2. Upload the package — sign in and upload the Willow agent.
3. Deploy to users — make the agent available to everyone, or to specific people, from the Microsoft 365 admin center.

A final section, Using the Willow agent, describes what your users do the first time they open it.

You only need to do parts 1–3 once per Willow environment. When Willow ships an updated package later, re‑running part 2 with the new file upgrades the existing agent in place — you do not need to repeat part 3.

Before you begin

You will need:

• Microsoft 365 administrator access — specifically the ability to manage Integrated apps / Copilot agents in the Microsoft 365 admin center. (Global Administrator, or a role such as Teams Administrator combined with app‑management rights.)
• The Willow agent package — a .zip file you downloaded from the Willow platform (for example Willow-MCP-Agent.zip). Keep note of where you saved it.
• A Windows, macOS, or Linux machine with a command line (Windows PowerShell, Terminal, etc.).

1. Prepare the tool

The Willow agent is uploaded using Microsoft's Microsoft 365 Agents Toolkit CLI (atk). This is a free, Microsoft‑published command‑line tool. You install it once.

1a. Install Node.js (LTS)

atk runs on Node.js. Install a current LTS (Long‑Term Support) version — Node 20, 22, or 24.

• Download from https://nodejs.org/ — choose the LTS button (an even‑numbered version).

• Verify after installing:

  node --version

  You should see something like v20.x, v22.x, or v24.x.

⚠️ Avoid the "Current" (odd‑numbered) Node release, e.g. Node 25. The atk tool currently crashes on it with an error like TypeError: Cannot read properties of undefined (reading 'prototype'). If you hit that error, you are on an unsupported Node version — install an even‑numbered LTS (20/22/24) and try again.

1b. Install the Agents Toolkit CLI

npm install -g @microsoft/m365agentstoolkit-cli

Verify it installed:

atk --version

You should see a version number (e.g. 1.1.4). If atk is not recognized, close and reopen your terminal so it picks up the new command.

2. Upload the Willow agent package

2a. Sign in to Microsoft 365

atk auth login m365

A browser window opens. Sign in with an administrator account for the Microsoft 365 tenant where your users will use the agent.

2b. Upload the package

Run install, pointing --file-path at the .zip you downloaded. Put the path in quotes if it contains spaces:

atk install --file-path "C:\Users\you\Downloads\Willow-MCP-Agent.zip"

On success, atk reports that the package was uploaded to Microsoft 365. This registers the agent in your organization's app catalog — the required step that makes its tools available to Copilot. (Uploading the same file through the admin center's "upload" button does not register the agent's tools; you must use atk install.)

Upgrading later: to publish an updated Willow package, just run atk install again with the new .zip. Because the package keeps the same identity, Microsoft 365 treats it as an upgrade of the existing agent — your earlier user assignments (part 3) stay in place.

3. Deploy the agent to your users

Uploading makes the agent available in your catalog. Now choose who can use it, from the Microsoft 365 admin center.

1. Go to https://admin.cloud.microsoft/#/agents/all (Microsoft 365 admin center → Copilot → Agents & connectors, "All agents").
2. Find the Willow agent in the list and open it.
3. Choose how to deploy it:
   • Install for everyone — make the Willow agent available to all users in your organization.
   • Install for specific users or groups — assign it to named users or to a security/Microsoft 365 group. Use this for a limited pilot before a wider rollout.
4. Confirm/save. Availability can take a little time to propagate to all users.

The agent's identity is per‑Willow‑environment, so the assignment you make here applies to that specific Willow agent. If you were given more than one package (e.g. for different Willow environments), repeat parts 2–3 for each.

Using the Willow agent (for end users)

Once the agent is deployed, this is what a user does — you may want to share these steps with your users.

1. Open Microsoft 365 Copilot (in Teams, Outlook, or the Microsoft 365 app / copilot.microsoft.com).
2. In the agents list ("Your agents" / the agents flyout), find and open Willow.
3. The first time, Copilot prompts you to sign in. Sign in with your Willow account (the same credentials you use for the Willow platform). This is a one‑time authorization; Copilot remembers it afterwards.
4. Ask the agent about your buildings, twins, insights, tickets, and other Willow data in natural language.

If a user is repeatedly asked to sign in and it never completes, contact your Willow representative — that usually indicates a configuration item on the Willow side that needs attention, not an end‑user problem.

Troubleshooting