Agents Toolkit and TypeSpec

TL;DR: You will move a declarative Microsoft 365 Copilot agent from no-code to code-first by scaffolding it with the Agents Toolkit, defining it in TypeSpec, putting it under version control and testing it, so its instructions and knowledge become reviewable, auditable governance artefacts.

What you will learn

How to scaffold a declarative agent project from the Microsoft 365 Agents Toolkit using the TypeSpec for Microsoft 365 Copilot template.
How to express an agent’s instructions, conversation starters and knowledge sources declaratively in a main.tsp file.
How to provision the agent and test it inside Microsoft 365 Copilot.
How to version the TypeSpec definition in Git so every change to behaviour and knowledge scope is reviewable and traceable.
Which governance controls a Microsoft 365 security practitioner must apply when knowledge sources move into code.

Prerequisites

A Microsoft 365 Copilot licence assigned to the developer account, or a Microsoft 365 Copilot developer licence (some capabilities are limited for Copilot Chat users).
Permission to sideload custom apps in your Microsoft 365 tenant, granted by a Teams or Microsoft 365 administrator.
Visual Studio Code with the Microsoft 365 Agents Toolkit extension installed.
Node.js (LTS) and Git installed locally.
Access to any SharePoint, OneDrive or Copilot connector content you intend to scope as knowledge.
Recommended: complete an introductory no-code declarative agent tutorial first, so you understand instructions, knowledge and conversation starters before defining them in code.

Scaffold the agent with the Agents Toolkit

The Agents Toolkit generates a project that compiles a TypeSpec definition into a declarative agent manifest at provision time.

Create a new TypeSpec project

Open Visual Studio Code.
In the activity bar, select Microsoft 365 Agents Toolkit, then Create a New Agent/App.
Select Declarative Agent.
Select Start with TypeSpec for Microsoft 365 Copilot.
Select Default folder to store the project root in the default location.
Enter My Agent as the application name and press Enter.
A new Visual Studio Code window opens with the scaffolded project.

The key file is main.tsp. It holds the agent’s name, description, instructions, conversation starters and knowledge capabilities. This single file is the code-first source of truth for the agent’s behaviour.

Define the agent in TypeSpec

Open main.tsp and edit the definition. Provision after each change to apply it.

Set instructions

Instructions shape how the agent behaves. Replace the @instructions decorator with your own grounded, least-surprise guidance.


@instructions("""
  You are a declarative agent that helps the security and governance team
  find approved policy guidance. Only answer from the knowledge sources
  provided. If the answer is not in those sources, say you do not know.
""")

Add conversation starters

Conversation starters are hints shown to users when they open the agent.


@conversationStarter(#{
  title: "Getting started",
  text: "How do I report a data handling exception?"
})
 
@conversationStarter(#{
  title: "Policy lookup",
  text: "What is our retention policy for shared mailboxes?"
})

Scope knowledge sources deliberately

Knowledge capabilities are added as operations inside the agent namespace. Scope each one to specific sites or connections rather than leaving the arrays empty, because an omitted scope array grants the agent everything the signed-in user can already see.


namespace MyAgent {
  // Scope to a single SharePoint site, not the whole tenant.
  op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [
    {
      url: "https://contoso.sharepoint.com/sites/ProductSupport"
    }
  ]>;
 
  // Scope web search to a known, trusted domain only.
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com"
    }
  ]>;
}

Provision and apply changes

In the scaffolded window, select Microsoft 365 Agents Toolkit.
In the Lifecycle pane, select Provision.
The Toolkit compiles main.tsp into the manifest and uploads the agent to your tenant.

Test the agent in Microsoft 365 Copilot

Navigate to the Copilot application at https://m365.cloud.microsoft/chat .
Next to the New Chat button, select the conversation drawer icon.
Select the declarative agent My Agent.
Enter a question and confirm the agent answers only from the scoped knowledge.

Re-provision after each edit, then reload the Copilot page to pick up the new behaviour. Use this loop to verify that tightening a knowledge scope actually narrows what the agent can retrieve.

Version the definition

Because the agent now lives in main.tsp, treat it like any other reviewed code asset.

Initialise a repository in the project root and commit the scaffold as a baseline.
Make one behavioural change per commit, for example narrowing a SharePoint scope or tightening instructions, with a clear message.
Open a pull request for any change to instructions or knowledge scope, so a second reviewer signs off before it reaches the tenant.
Tag releases that you provision, so a provisioned agent in production maps to an exact commit.

This gives you a reviewable history of every change to what the agent can say and see.

Governance call-outs

Least-privilege knowledge: always populate scope arrays such as ItemsByUrl, Sites or Connections. An empty or omitted array exposes everything the signed-in user can access, which is a data-leakage risk hiding in a default.
Identity and data boundaries: the agent inherits the permissions of the user invoking it, so review which content the audience can already reach before scoping a site or connector as knowledge.
Compliance gates in code review: require pull-request approval for any change to instructions or knowledge sources, turning the TypeSpec file into an enforceable control point.
Audit trail: keep the provisioned agent tied to a Git tag or commit so you can prove which definition was live at any point in time.
Trusted sources only: scope web search to known domains and prefer governed SharePoint, OneDrive and Copilot connector content over open web access to reduce exposure to unvetted information.

Next step

Continue with the next tutorial.

Sources

Licensed under CC BY 4.0 by Educ4te .