Build your first add-in as a Copilot skill

In this article, you'll walk through the process of building a simple Copilot agent that can perform actions on the content of an Office document. The app also includes a task pane add-in.

Knowledge prerequisites

• A basic understanding of declarative agents in Microsoft 365 Copilot. If you aren't familiar with them already, we recommend reading Declarative agents for Microsoft 365 Copilot overview.

Software prerequisites

• All the prerequisites listed at Create declarative agents using Microsoft 365 Agent Toolkit.
• Microsoft 365 Agents Toolkit. For installation instructions, see Install Microsoft 365 Agents Toolkit.

Create the project

1. In Visual Studio Code, open Microsoft 365 Agents Toolkit.

   

2. Select Create a New Agent/App.

3. In the New Project list, select Office Add-in.

   

4. On the Select a capability list, select Create Declarative Agent with Office Add-in Action.

   

5. In the refined capability list that opens, select New Declarative Agent with Office Add-in Actions.

   

6. In the Workspace Folder control that opens, choose a folder for the project.

7. In the Application Name text box, enter "Add-in + Agent Actions".

8. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.

9. Open the Agents Toolkit, and in the ACCOUNTS section, ensure that you are logged into your Microsoft 365 tenancy and that both Custom App Upload and Copilot Access are enabled.

Run the project

1. Close all Office applications.

2. Select View | Run in Visual Studio Code. In the RUN AND DEBUG dropdown menu, select {{HOST}} Desktop (Edge Chromium), where {{HOST}} is Excel, Powerpoint, or Word.

3. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, the Office application opens.

You can start working with either the add-in or the Copilot agent. If both have been started, then they each have an icon tab on the right side of the task pane so you can switch between them.

Start the add-in

1. There should be a Contoso Add-in group on the Home tab of the ribbon. If it isn't there, select the Add-ins button on the ribbon, and then select the Add-in + Agent Actions app in the flyout that opens.

2. The Contoso Add-in group has a Show Taskpane button which opens the task pane and a Perform an action button.

   Note

   If a WebView Stop On Load prompt appears, select OK.

3. Test the add-in by pressing the Run link in the task pane, or selecting the Perform an action button.

Start the agent

1. Select the dynamic action button for Copilot Chat on the surface of the open document.

   

2. In the Copilot pane, select the hamburger control.

3. It may take a minute for the pane to completely rerender. When it does, there is a list of agents and Add-in Skill + Agent for Add-in + Agent Actions should be in the list.

4. When the agent is listed, select it. The Add-in Skill + Agent for Add-in + Agent Actions pane opens.

5. Some conversation starters are listed. Select one that's appropriate for the Office application you have opened, and then press the Send control in the conversation box at the bottom of the pane.

6. Select Confirm in response to the confirmation prompt.

   Tip

   If Copilot reports an error, repeat your prompt but add the following sentence to the prompt: "If you get an error, report the complete text of the error to me."

7. Try entering other instructions in the conversation box. If you request an action that isn't defined in the agent, Copilot responds that it isn't able to do the action.

Shut down the session completely

It's important to shut down the debugging session and uninstall the add-in and agent completely to avoid subtle problems. Use the following steps.

1. In Visual Studio Code, open the Run menu and select Stop debugging, or press Shift+F5. Due to a bug we're working on, this action doesn't always completely shut down the server, close the Office application, and uninstall the add-in. So, carry out the remaining steps.

2. Close the Office application if it's still running.

3. If the dev server is still running, shutting down the server depends on what window it's running in.

   • If the web server is running in a separate window from Visual Studio Code, open a command prompt or the Visual Studio Code TERMINAL. In the root of the project, run npm run stop.
   • If the web server is running in the Visual Studio Code TERMINAL, give the window focus and press Ctrl+C. Choose "Y" in response to the prompt to end the process.

4. Clear the Office cache following the instructions at Manually clear the cache.

5. Open Teams and select Apps from the app bar, then select Manage your apps at the bottom of the Apps pane.

6. If the Add-in + Agent Actions is in the list of apps, select the arrow head to the left of the name to expand its row.

7. Select the trash can icon near the right end of the row, and then select Remove in the prompt.

Troubleshooting

See Troubleshooting combined add-ins and agents.

Next steps

1. Complete the tutorial that begins at Create declarative agents using Microsoft 365 Agent Toolkit.
2. Add a Copilot agent to an existing add-in.

See also

• Combine Copilot Agents with Office Add-ins
• Declarative agent manifest object
• API plugin manifest schema 2.4 for Microsoft 365 Copilot