Scaffolding Your First Declarative Agent with the Agents Toolkit

Last week, a customer asked me: “We want to build an AI assistant for our HR team: how long until we have something running?” I told them fifteen minutes: they laughed, but I wasn’t joking. Let’s scaffold the project, understand the moving pieces, and hit F5 to deploy.

What Are Declarative Agents?

A declarative agent is an agent you describe, not one you code. You don’t write conversation logic, you don’t manage state, you don’t build a bot framework. Instead, you write a JSON manifest that tells Microsoft 365 Copilot: “Here’s who this agent is, here’s what it knows, and here’s what it can do.” Copilot handles the rest: the reasoning, the orchestration, the responses.

If custom engine agents are like building a car from parts, declarative agents are like configuring a car on a website. You pick the color, the engine, the features: and the platform assembles it for you. No bot logic required. The tool that makes this possible is the Microsoft 365 Agents Toolkit.

Installing the Agents Toolkit

First things first: you need the Agents Toolkit extension in VS Code. Head to the Extensions marketplace, search for “Microsoft 365 Agents Toolkit”, and install it. It’s free.

Once installed, you’ll see the Agents Toolkit icon in your VS Code sidebar. That’s your launchpad for everything we’re about to do.

You can also install and use the Agents Toolkit CLI directly:

npm install -g @microsoft/m365agentstoolkit-cli
atk --version

Scaffolding the Project

Open the Agents Toolkit panel and click “Create a New Agent/App”. The wizard walks you through three steps:

1. Project type — Select Declarative Agent
2. Capabilities — Select No Action (we’re starting without an API plugin)
3. Name and folder — Name it something like HR Onboarding Buddy and pick a folder

Or, if you prefer the CLI:

atk new -n hr-onboarding-buddy -c declarative-agent -with-plugin no -i false

That’s it. No npm installs, no boilerplate generators, no framework decisions. The toolkit scaffolded everything you need in about two seconds.

Understanding the File Structure

The entire agent is defined by four files.

appPackage/manifest.json

This is the Microsoft 365 app manifest: the same one you’d use for any Microsoft 365 app. It tells the platform that our app contains a declarative agent and points to the agent definition file.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.24/MicrosoftTeams.schema.json",
  "version": "1.0.0",
  "manifestVersion": "1.24",
  "id": "${{TEAMS_APP_ID}}",
  "name": {
    "short": "HR Onboarding Buddy",
    "full": "HR Onboarding Buddy - Zava Insurance"
  },
  "description": {
    "short": "Your friendly onboarding assistant",
    "full": "A declarative agent that helps new employees navigate their first weeks at Zava Insurance."
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}

The key addition is the copilotAgents section, which registers your agent with Microsoft 365 Copilot.

appPackage/declarativeAgent.json

This is the heart of your agent. Right now, the scaffolded version is minimal:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
  "version": "v1.6",
  "name": "HR Onboarding Buddy",
  "description": "A friendly assistant to help new employees at Zava Insurance.",
  "instructions": "$[file('instructions.txt')]"
}

The $[file('instructions.txt')] reference is a file inclusion: the agent’s instructions live in a separate text file for easier editing.

appPackage/instructions.txt

The agent’s brain, so to speak. Out of the box, it contains a generic placeholder like “You are a helpful assistant.” We’ll replace this with rich, structured instructions covering role, tone, scope, guardrails, and response formatting.

m365agents.yml

The provisioning and deployment configuration for the Agents Toolkit. This YAML file tells the toolkit how to package and deploy your agent. You rarely need to edit this by hand: the toolkit manages it for you.

provision:
  - uses: teamsApp/create
    with:
      name: HR Onboarding Buddy-${{TEAMSFX_ENV}}
    writeToEnvironmentFile:
      teamsAppId: TEAMS_APP_ID

  - uses: teamsApp/zipAppPackage
    with:
      manifestPath: ./appPackage/manifest.json
      outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
      outputFolder: ./appPackage/build

  - uses: teamsApp/update
    with:
      appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip

And that’s the entire project. Four files. No server code, no bot framework, no Azure resources: just configuration.

F5: Your First Deploy

Hit F5 in VS Code (or run the provisioning task from the Agents Toolkit panel). The toolkit will:

1. Package your app manifest and agent definition into a zip
2. Upload it to Microsoft 365
3. Register the agent with Copilot
4. Open Copilot in your browser

The whole process takes about 30 seconds.

Once Copilot opens, you’ll see your agent listed. Click it, type “Hey, who are you?” and the agent responds.

The response will be vague: the agent doesn’t know it’s an HR assistant yet. It has no personality, no boundaries, and it’ll try to answer anything. That’s expected. The point is the deployment pipeline works: your agent is running inside Microsoft 365 Copilot.

What We Just Built (and What’s Missing)

In about five minutes, we went from zero to a deployed declarative agent inside Microsoft 365 Copilot. No code. No infrastructure. Just four configuration files and an F5.

What we have:

• ✅ A working agent registered in Microsoft 365
• ✅ A clean project structure we can iterate on
• ✅ A deployment pipeline that takes seconds

What’s missing:

• ❌ Rich instructions that give the agent a real persona and boundaries
• ❌ Knowledge sources (company documents, SharePoint sites)
• ❌ API actions and plugins
• ❌ Conversation starters for discoverability

There are many more capabilities we can layer on top of this foundation. But that’s for another time!

Resources

• Declarative Agents Overview: Microsoft Learn
• Microsoft 365 Agents Toolkit: VS Code Marketplace
• Build a Declarative Agent: Microsoft Learn
• Declarative Agent Schema Reference
• Extensibility Prerequisites and Licensing

---

Have questions or want to share what you’re building? Connect with me on LinkedIn or check out more on The Manifest.