Introduction
Have you ever wondered—especially as a pro developer—if there’s a way to build Copilot agents with precision and full control, beyond what low-code tools can offer? If you’re seeking a more customizable, scalable, and developer-centric approach to Copilot agent development, the Microsoft 365 Agents Toolkit in Visual Studio is the answer. Unlike traditional low-code methods, which are great for rapid prototyping but often limited in flexibility, the pro-code approach empowers you to:
Define agent behaviors declaratively using structured schemas
Integrate advanced capabilities like external APIs, adaptive cards, and M365 connectors
Tailor every interaction with full control over prompts, actions, and instructions
In this blog, we’ll walk through how to build and deploy Copilot agents using the Microsoft 365 Agents Toolkit—ideal for developers who want to go beyond the basics and deliver powerful, role-specific automations across the Microsoft 365 ecosystem.
What is an Agent in VS Code?
An agent is a customizable Copilot extension built using the Agent Toolkit in Visual Studio.
It allows developers to define user interactions using structured declarations instead of writing imperative code.
Key capabilities include:
- Specification of instructions, actions, and knowledge sources using a schema-driven approach.
- Integration with external APIs and data sources for grounding and action execution.
- Customization of prompts and behaviors via adaptive cards, plugins, and manifest configurations.
- Utilization of Microsoft 365’s orchestration and AI foundation.
Let’s create an agent using Agent Toolkit –
- Install Microsoft 365 Agents Toolkit in VS Code –
- Select M365 Agent Toolkit option available in the left pane. Select create a new agent/app
- It will prompt you with 4 different options to create a new declarative agent.
Below is explanation of these options with use case examples about when to use them followed by the screenshots below.
No Action – Create a declarative agent only
- Use Case: Build a lightweight agent that responds to user queries based on predefined rules or data.
- Example: An FAQ bot for HR policies returning static answers based on user questions.
Add an Action – Create a declarative agent with an action
- Use Case: Define specific tasks such as fetching data, sending emails, or updating records.
- Example: A helpdesk agent that creates a support ticket in ServiceNow based on user input.
Add a Copilot Connector – Integrate with Microsoft 365 Copilot
- Use Case: Connect with Microsoft 365 apps like Outlook or Teams to automate tasks.
- Example: An agent that summarizes recent emails and schedules meetings in Outlook.
Start with TypeSpec for Microsoft 365 Copilot (Preview)
- Use Case: Use a flexible TypeSpec definition for advanced scenarios and enterprise workflows.
- Example: A project management assistant that manages Planner tasks and SharePoint documents.
Writing Instructions for Agents
Instructions define how the agent behaves when interacting with users. They are stored in the file: `appPackage/instructions.txt`, and they get inserted into the `instructions` property in the agent’s manifest during provisioning.
Tips for Writing Effective Instructions:
- Be as detailed as possible (limit: 8000 characters).
- Use clear directives like:
- I **must** strictly respond back to the user with a single line response as ‘—‘.
- I **should never** add any other details from adaptive card.
- I **must** always add citation for interactive forms or adaptive cards.
- To handle errors:
- I **must** politely ask user to retry with a proper message if `tool_invocations` status encounters an error.
- Use `###` to separate multiple capabilities (Graph Connectors, API, Code Interpreter, etc.)
- Ensure clarity when referencing API plugins or knowledge sources for multi-turn scenarios.
- Verify that Manifest JSON is updated with right content which will be visible to all the users of this agent once you share it with other users.
Agent Capabilities and Grounding
By default, agents do not have access to all Microsoft 365 data. You must ground your agent with specific skills, APIs, or data sources to enhance its capabilities. These skills are controlled by the configuration and manifest setup.
Lifecycle Provisioning
Lifecycle provisioning refers to the stages through which an agent moves from development to deployment. Defined using configuration files like `m365agents.yml` and `m365agents.local.yml`, these stages streamline cloud setup and management.
Lifecycle Stages:
• Provision – Sets up Azure resources and Microsoft Entra ID registration.
• Deploy – Pushes your source code and configuration to the cloud.
• Publish – Makes your agent available inside Microsoft 365 apps like Teams.
• Debug – Supports local or remote debugging via Visual Studio Code.
Packaging and Sideloading the Agent
To generate a deployable agent package:
1. Use the **Zip App Package Utility** to generate your `.zip` file.
2. Click on the local address to retrieve the package.
3. Rename the ‘.zip’ file meaningfully.
4. Sideload the agent into Microsoft Teams.
Testing and Publishing the Agent
After sideloading:
• Test interactions and flows directly inside Teams.
• Follow your organization’s process to publish the agent into the Teams app catalog for wider distribution.
Summary
In this blog, we explored how to build custom Copilot agents using the Microsoft 365 Agents Toolkit in Visual Studio. We began by understanding what agents are and the different types you can build using declarative approaches. We covered step-by-step guidance on writing effective instructions, leveraging Microsoft 365 capabilities, provisioning the agent lifecycle, and packaging and publishing the agent to Microsoft Teams. This pro-code approach gives developers enhanced control and flexibility while integrating deeply with the Microsoft 365 ecosystem.
References
• Microsoft Learn – Agent Toolkit Overview: https://learn.microsoft.com/en-us/microsoft-365/developer/agents/toolkit/overview
• Write Instructions for Declarative Agents with API plugins: https://learn.microsoft.com/en-us/microsoft-365/developer/agents/toolkit/write-instructions