Create your first declarative agent the pro-code way with VSCode

Introduction

Nowadays Microsoft Copilot is THE argument when it comes to the Microsoft tenants, moreover we’re seeing an increase about using agents. Due to this I think it would be a good idea to start covering Copilot and I want to start with a Declarative Agent and since I’m a developer I want to start with the pro-code way of creating one.

If you’re interested in having a look at the code, you can find it here.

What we’re building

What I want to cover with this post is a Declarative Agent the pro-code way. All the developers should have their own rubber duck sitting on the desk, but in this times it can be a little “old school” to have one, so in this example I want to create a virtual one!

The agent will be displaying as follows:

The user can interact with it asking questions like:

I am facing an issue in my SPFx solution that I cannot understand

The agent will help the user understanding the issue and reaching a solution without explicitly giving the answer to the issue:

This is just a sample, I know there are quicker ways to resolve issues or understanding why things are not working as expected, but again this is a sample and the actual rubber ducks don’t even reply to developers

Show me the code

Prerequisites

In order to create the Declarative Agent you will need a couple of things:

• A Microsoft tenant.
• VSCode, which you can find here.
• The Microsoft 365 Agents Toolkit extension for VSCode, which you can find here.

This blog post is not about how to setup the environment, but if you’re interested in knowing more you can have a look here skipping the Azure section and installing the extension for VSCode.

If you search, in the extension panel of VSCode, for “Microsoft 365 Agents Toolkit”, you will find the following extension to install:

After installing the extension, if you open it, you will see the following panel:

From here you can start developing your Declarative Agent in the pro-code fashion.

Creating the agent

To create a Declarative Agent with ATK (Microsoft 365 Agents Toolkit), you will have to open a new instance of VSCode, select the extension and click the “Create a New Agent/App” button shown in the following screenshot:

Clicking on the button will open a menu from the command palette where you can select what kind of agent or app you want to build:

In this sample we are using the “Declarative Agent” option, clicking on that option a new menu will open asking how you want to configure your agent:

This Declarative Agent is not relying on any action or connector, so here simply select the “No Action” option. After specifying the option you are prompted to specify the name of the agent, in this case it will be “Rubber duck”:

Finally, you will be prompted for where you want to store your agent.

Keep in mind that you will be selecting the folder where the root folder of your agent will be created.

After selecting the root folder the solution will be scaffolded and a new instance of VSCode will be opened in that location.

Solution structure

The created solution will have a structure like the following:

The appPackage folder includes the Teams application manifest and the GPT manifest, in the sample we have the following:

• manifest.json: the manifest of the Teams application that defines the metadata of the declarative agent.
• declarativeAgent.json: defines the behaviour and configurations of the declarative agent.
• instruction.txt: the actual system prompt for the declarative agent, this is used inside the declarativeAgent.json file instead of writing the full prompt directly into the JSON file.
• color and outline PNGs: those are the icons for the agent, keep in mind that:
  • color.png: a square coloured image of 192×192 pixels.
  • outline.png: a square outlined image of 32×32 pixels.

The env folder contains the environment files used to configure the declarative agent for each specific environment.

One last thing that deserves a mention are the yml files, those files are the main Teams Toolkit (the former name of the Microsoft Agents Toolkit) project files, each is for a specific environment. The main content of the project files are properties and configuration stage definitions.

declarativeAgent.json

The main file for this example is the declarativeAgent.json this contains the following properties:

• name: this will be the name of the agent. By default this comes with a suffix taken from the environment file and named APP_NAME_SUFFIX.
• description: this contains the description for the agent.
• instructions: this will contains the system prompt for the agent. The system prompt can be stored in an external file. By default the value is loaded from the instruction.txt file, to achieve that the value is: $[file('instruction.txt')]

For the sample agent the file contains the following:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
  "version": "v1.6",
  "name": "Rubber duck${{APP_NAME_SUFFIX}}",
  "description": "Sample declarative agent that act as a rubber duck to help developers.",
  "instructions": "$[file('instruction.txt')]"
}

Declarative Agent configuration

Now let’s cover how the agent is configured and this means that, for this sample, we need to only write the system prompt for the rubber duck agent.

As described in the previous section, the system prompt is defined in the instruction.txt file, I won’t copy its content here, but let me explain a little bit its content.

Core behaviour of the system prompt:

• Act as a patient listener guiding developers through problems
• Encourage step-by-step explanations and reflection
• Ask open-ended questions instead of giving immediate solutions
• Help break complex problems into smaller parts
• Only give direct solutions if explicitly asked or user is stuck

Other sections of the system prompt includes:

• Specific interaction style
• Narrow down issues with isolation and debugging techniques
• Don’t overwhelm with too many questions
• Keep responses concise and thoughtful
• Prefer guiding over explaining

Conclusions

Building a Declarative Agent the pro-code way, using VSCode and the Microsoft Agent Toolkit, highlights the power of combining familiar development environments with a declarative approach to fully leverage Copilot’s capabilities. This approach also integrates seamlessly into existing development workflows allowing developers to store and manage agents within a source control system, making versioning, collaboration, and long-term maintenance significantly easier and more reliable.

Hope this helps!