Build Agents for Copilot with the Microsoft 365 Agents Toolkit

In the feature video Robert Howard, Matthew Barbour and Sébastien Levert explain how to build and bring your own agent into Microsoft 365 Copilot with the Microsoft 365 Agents Toolkit.

Explore Declarative and Custom Engine Agents, use the Microsoft 365 Agents SDK, and extend with Copilot APIs to ground answers securely in Microsoft 365 data.

Discover the powerful flexibility offered to build the right agent for your needs.

Microsoft 365 Agents Toolkit

The Microsoft 365 Agents Toolkit (formerly known as Teams Toolkit) is a comprehensive development suite designed to simplify the creation of enterprise-ready agents and applications that integrate seamlessly across Microsoft 365 Copilot, Teams, Office, Outlook, web, and third-party channels.

It supports a “write once, run everywhere” model, enabling developers to build declarative agents (which leverage Microsoft 365 Copilot’s AI stack without hosting your own AI) or custom engine agents (using the Microsoft 365 Agents SDK for full control over the AI backend).

This tutorial focuses on building declarative agents for Microsoft 365 Copilot using the toolkit and TypeSpec (a language for defining APIs and agents declaratively). Declarative agents are ideal for scenarios where you want Copilot to handle reasoning, orchestration, and execution based on natural language prompts, without managing infrastructure. We’ll cover prerequisites, setup, creation, customization, deployment, and testing. For custom engine agents, see the appendix.

This guide is based on official Microsoft documentation and best practices as of December 2025.

Prerequisites

Before starting, ensure you have:

• A Microsoft 365 tenant with Copilot enabled (e.g., via a sandbox environment in the TAP program or a production Office 365 setup with a Copilot license).
• Visual Studio Code (VS Code) installed.
• Node.js and npm (for toolkit installation).
• Familiarity with basic JavaScript/TypeScript and API concepts.
• Access to Microsoft 365 admin tools for app registration and deployment.
• Compliance with Microsoft’s guidelines for agent performance, security, and user experience (e.g., Teams Store validation rules).

If you’re new to Copilot extensibility, review the declarative agents overview for context.

Installation and Setup

1. Install the Microsoft 365 Agents Toolkit Extension in VS Code:
   • Open VS Code.
   • Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X on Mac).
   • Search for “Microsoft 365 Agents Toolkit” and install it.
   • Alternatively, install via CLI: npm install -g @microsoft/m365agentstoolkit-cli for command-line access (useful for CI/CD).
2. Verify Installation:
   • In VS Code, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
   • Search for “Microsoft 365 Agents Toolkit” commands; you should see options like “Create a New Agent/App”.
3. Set Up Your Development Environment:
   • Sign in to your Microsoft 365 account in VS Code via the toolkit (it will prompt during project creation).
   • Ensure you have Azure access if provisioning cloud resources (optional for local testing).

The toolkit also supports Visual Studio (.NET), GitHub Copilot (chat-based), and CLI formats, but this tutorial uses VS Code for its visual lifecycle management.

Step-by-Step: Creating a Basic Declarative Agent

Declarative agents are defined using TypeSpec (.tsp files), which the toolkit compiles into manifests for Copilot.

1. Create a New Project:
   • In VS Code, open the Command Palette.
   • Select Microsoft 365 Agents Toolkit > Create a New Agent/App.
   • Choose Declarative Agent.
   • Select Start with TypeSpec for Microsoft 365 Copilot (this scaffolds a basic agent template).
   • Choose the default folder or specify a custom one.
   • Enter a name, e.g., “MyPoemAgent”.
   • A new VS Code window opens with the project.
2. Explore the Project Structure:
   • main.tsp: Core agent definition file (instructions, capabilities, etc.).
   • m365agents.yml: Configuration for provisioning and deployment.
   • Lifecycle pane (in the toolkit sidebar): Handles provision, deploy, and preview.
3. Provision the Agent:
   • In the toolkit sidebar, under Lifecycle, select Provision.
   • This registers the app in Microsoft Entra ID, generates manifests, and sets up local environment variables.
   • If prompted, sign in to your Microsoft 365 account.
4. Test the Basic Agent:
   • Navigate to the Copilot app: https://copilot.microsoft.com or https://m365.cloud.microsoft/chat.
   • Click the conversation drawer icon next to New Chat.
   • Select your agent (e.g., “MyPoemAgent”).
   • Enter a prompt like “Tell me about agents” and send it.
   • The agent responds based on default instructions.

Customizing the Agent

Enhance your agent by adding instructions, conversation starters, and capabilities.

1. Add Instructions:
   • Open main.tsp.
   • Replace the @instructions decorator:

     @instructions("""You are a poem expert. Turn every response into a creative poem. Avoid using quotes or markdown; use plain text.""")
     

   • Save and select Provision in the Lifecycle pane.
   • Reload Copilot and test: e.g., “What is Microsoft 365?” – Expect a poetic response.
2. Add Conversation Starters:
   • In main.tsp, add or replace:

     @conversationStarter(#{ title: "Poem Ideas", text: "Suggest a poem about technology." })
     @conversationStarter(#{ title: "Help", text: "How do I use this agent?" })
     

   • Provision and reload Copilot; starters appear as suggestions.
3. Add Capabilities:
   Use namespaces in main.tsp to enable features. Provision after each addition.
   • Web Search (ground responses in web data):

     namespace MyPoemAgent {
       op webSearch is AgentCapabilities.WebSearch<Sites = [ { url: "https://learn.microsoft.com" } ]>;
     }
     

   • OneDrive/SharePoint Access (use organizational files):

     namespace MyPoemAgent {
       op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [ { url: "https://yourorg.sharepoint.com/sites/YourSite" } ]>;
     }
     

   • Teams Messages (access channel data):

     namespace MyPoemAgent {
       op teamsMessages is AgentCapabilities.TeamsMessages<Urls = [ { url: "https://teams.microsoft.com/l/team/your-team-id" } ]>;
     }
     

   • People Knowledge (user profiles):

     namespace MyPoemAgent {
       op people is AgentCapabilities.People;
     }
     

   • Email Knowledge (inbox access):

     namespace MyPoemAgent {
       op email is AgentCapabilities.Email<Folders = [ { folder_id: "Inbox" } ]>;
     }
     

   • Image Generation:

     namespace MyPoemAgent {
       op graphicArt is AgentCapabilities.GraphicArt;
     }
     

   • Code Interpreter (run Python code):

     namespace MyPoemAgent {
       op codeInterpreter is AgentCapabilities.CodeInterpreter;
     }
     

   • Copilot Connectors (custom data sources):

     namespace MyPoemAgent {
       op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [ { connectionId: "your-connector-id" } ]>;
     }
     

   Test each by reloading Copilot and using relevant prompts, e.g., “Generate an image of a robot poet” for graphicArt.

Deployment

1. Local Deployment (for Testing):
   • Use the Preview command in the Lifecycle pane.
   • Select a host like “Copilot” or “Teams”.
   • This sideloads the agent for your user.
2. Production Deployment:
   • In the Lifecycle pane, select Deploy.
   • This packages the app and deploys to Azure (if configured) or your tenant.
   • Publish to the Microsoft Store or organizational catalog via Publish in the pane.
   • Use CLI alternative: atk deploy --env prod (after atk provision).
3. Governance:
   • Use Microsoft Agent 365 (in admin center) for registry, access control, and monitoring.
   • Integrate with Purview for data loss prevention and Defender for threat protection.

Testing and Best Practices

• Testing:
  • Use the Microsoft 365 Agents Playground (toolkit-integrated sandbox) for local debugging without a tenant.
  • In Copilot, test edge cases, performance, and multi-turn conversations.
  • Validate with atk validate (CLI) for schema compliance.
• Best Practices:
  • Keep instructions concise and specific to avoid hallucination.
  • Scope capabilities narrowly to enhance security (e.g., limit sites/urls).
  • Monitor usage via Agent 365 for performance and interoperability.
  • Handle errors gracefully; use states in plugins for reasoning/responding.
  • Iterate: Provision after changes and clear cache if needed.
  • For scalability, integrate Azure AI Foundry for advanced AI features.
  • Ensure accessibility and inclusivity in responses.

Advanced Example: Building an Excel Add-in as a Copilot Agent

For agents that interact with Office apps, combine add-ins with declarative agents.

1. Create Project:
   • Use toolkit to scaffold an Excel add-in named “ExcelColorAgent”.
2. Add Function Logic (in commands.ts):

   async function fillcolor(cell: string, color: string) {
     await Excel.run(async (context) => {
       context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
       await context.sync();
     });
   }
   
   Office.actions.associate("fillcolor", async (message) => {
     const { cell, color } = JSON.parse(message);
     await fillcolor(cell, color);
     return "Cell color changed.";
   });
   

3. Update Manifest and JSON Files:
   • Add copilotAgents to manifest.json.
   • Create declarativeAgent.json and Excel-API-local-plugin.json with actions for “fillcolor”.
4. Provision, Deploy, and Test:
   • Provision via toolkit.
   • Run npm run dev-server.
   • In Excel Copilot pane, select the agent and prompt: “Change cell B2 to blue.”

This creates an agent that modifies Excel cells via natural language.

Appendix: Custom Engine Agents (Alternative Approach)

For full AI control, use the Microsoft 365 Agents SDK with the toolkit.

1. Quickstart in Python:
   • Create project: mkdir echo-agent; cd echo-agent.
   • Install: pip install microsoft-agents-hosting-aiohttp.
   • Add app.py with echo logic (see code in tool results).
   • Run: python app.py.
   • Test with Agents Playground: npm install -g @microsoft/teams-app-test-tool; teamsapptester.

Integrate with toolkit for deployment: Scaffold a custom agent project and host the backend.

Conclusion

You’ve now built and customized a declarative agent for Microsoft 365 Copilot using the Agents Toolkit. Start with simple instructions and scale to complex capabilities. For more, explore the toolkit CLI for automation or Copilot Studio for no-code options. Always test thoroughly and adhere to security best practices.