Repository: OfficeDev/office-js-docs-pr
Pull request #5156: [All Hosts] (ux) combine copilot agent and add-in
Author: login: Rick-Kirkham
Created: 2025-05-03T20:36:15Z | Merged: 2025-05-16T21:13:24Z

MERGE TO MAIN ON AFTERNOON OF MAY 16TH


Diff:
diff --git a/docs/design/add-in-commands.md b/docs/design/add-in-commands.md
index a2e0e9f82b..4163f29bf2 100644
--- a/docs/design/add-in-commands.md
+++ b/docs/design/add-in-commands.md
@@ -1,7 +1,7 @@
 ---
 title: Basic concepts for add-in commands
 description: Learn how to add custom ribbon buttons and menu items to Excel, Outlook, PowerPoint, and Word as part of an Office Add-in.
-ms.date: 03/11/2025
+ms.date: 05/19/2025
 ms.topic: overview
 ms.localizationpriority: high
 ---
@@ -31,6 +31,12 @@ There are two types of add-in commands, based on the kind of action that the com
 
   - If the add-in is configured to use a [shared runtime](../testing/runtimes.md#shared-runtime), the function can also call the [showAsTaskpane](/javascript/api/office/office.addin#office-office-addin-showastaskpane-member(1)) method.
 
+   > [!TIP]
+   > Function commands aren't the only way to run arbitrary JavaScript in an add-in. An add-in can also include:
+   >
+   > - Custom handlers for certain events, such as a user opening an new message pane in Outlook.
+   > - Custom [Copilot agents](agent-and-add-in-overview.md) that take actions in response to natural language requests from the add-in's users.
+
 ## Location of add-in commands
 
 When a user installs an add-in, the location of its commands depends on the application, platform, and context. Add-in commands are found on the ribbon, in a default or custom tab, or on an action bar (only applies to certain Outlook platforms). They appear in the UI as a button or an item in a drop-down menu.
diff --git a/docs/design/agent-and-add-in-overview.md b/docs/design/agent-and-add-in-overview.md
new file mode 100644
index 0000000000..6f223ebf63
--- /dev/null
+++ b/docs/design/agent-and-add-in-overview.md
@@ -0,0 +1,262 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you're familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office Add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in**: When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be prompted to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis**: An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply prompts the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data**: If you prompt a typical AI engine with a question, it will combine information it finds and compose an answer; a process that can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user prompts the agent: "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user prompts: "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plug-in configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
+
+- The conversation starter appears in the chat canvas of Copilot.
+- The `"actions.id"` property in this file is the collective ID of all the functions in the file specified in `"actions.file"`. It doesn't have to match the `"actions.id"` in the manifest.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.3/schema.json",
+    "version": "v1.3",
+    "name": "Excel Add-in + Agent",
+    "description": "Agent for working with Excel cells.",
+    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+    "conversation_starters": [
+        {
+            "title": "Change cell color",
+            "text": "I want to change the color of cell B2 to orange"
+        }
+    ],
+    "actions": [
+        {
+            "id": "localExcelPlugin",
+            "file": "Excel-API-local-plugin.json"
+        }
+    ]
+}
+```
+
+The reference documentation for declarative agents is at [Declarative agent schema 1.3 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.3).
+
+### Copilot API plug-in configuration
+
+The API plug-in configuration file specifies the "functions" of the plug-in in the sense of agent actions, not JavaScript functions, including the instructions for the action. It also configures the JavaScript runtime for Copilot. The following is an example. About this JSON, note the following:
+
+- The `"functions.name"` must match the `"extensions.runtimes.actions.id"` property in the add-in manifest.
+- The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+- The `"responding.instructions"` property only provides guidance to Copilot about how to respond. It doesn't put any limits or structural requirements on the response.
+- The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+- The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. In this case, it specifies that the JavaScript function that is associated with the "fillcolor" string is available in an Office Add-in, rather than in some REST endpoint.
+-The `"runtimes.spec.allowed_host"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. In this case, it specifies that the agent should only be visible in Excel.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+    "schema_version": "v2.3",
+    "name_for_human": "Excel Add-in + Agent",
+    "description_for_human": "Add-in Actions in Agents",
+    "namespace": "addinfunction",
+    "functions": [
+        {
+            "name": "fillcolor",
+            "description": "fillcolor changes a single cell location to a specific color.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "Cell": {
+                        "type": "string",
+                        "description": "A cell location in the format of A1, B2, etc.",
+                        "default" : "B2"
+                    },
+                    "Color": {
+                        "type": "string",
+                        "description": "A color in hex format, e.g., #30d5c8",
+                        "default" : "#30d5c8"
+                    }
+                },
+                "required": ["Cell", "Color"]
+            },
+            "returns": {
+                "type": "string",
+                "description": "A string indicating the result of the action."
+            },
+            "states": {
+                "reasoning": {
+                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                    "instructions": "The user will ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                },
+                "responding": {
+                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                    "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                }
+            }
+        }
+    ],
+    "runtimes": [
+        {
+            "type": "LocalPlugin",
+            "spec": {
+                "local_endpoint": "Microsoft.Office.Addin",
+                "allowed_host": ["workbook"]
+            },
+            "run_for_functions": ["fillcolor"]
+        }
+    ]
+}
+```
+
+The reference documentation for API plug-ins is at [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2). The following is the documentation for two new properties of the `"runtimes.spec"` property.
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `local_endpoint` | String | Optional. The ID of a set of available JavaScript functions. This property is roughly analogous to the [`"runtimes.spec.url"`](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2#openapi-specification-object) property, but for local functions on the client, not REST APIs. Currently, the only allowed value is "Microsoft.Office.Addin".|
+| `allowed_host` | String | Optional. Specifies which Office application Copilots can host the agent. Possible values are "document", "mail", "presentation", and "workbook".|
+
+## Create the JavaScript functions
+
+The JavaScript functions that will be invoked by the Copilot agent are created exactly as [function commands](../develop/create-addin-commands-unified-manifest.md#add-a-function-command) are created. The following is an example. Note the following about this code.
+
+- Unlike a function command, a function associated with a Copilot action can take parameters.
+- The first parameter of the `associate` method must match both the `"extensions.runtimes.actions.id"` property in the add-in manifest and the `"functions.name"` property in the API plug-in's JSON.
+
+```javascript
+async function fillColor(cell, color) {
+    await Excel.run(async (context) => {
+        context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
+        await context.sync();
+    })
+}
+
+Office.onReady((info) => {
+    Office.actions.associate("fillcolor", async (message) => {
+        const {cell, color} = JSON.parse(message);
+        await fillColor(cell, color);
+        return "Cell color changed.";
+    });
+});
+```
+
+After your functions are created, create a UI-less HTML file that contains a `<script>` tag that loads the JavaScript file with the functions. The URL of this HTML file must match the value of the [`"extensions.runtimes.code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property in the manifest. See [Unified manifest for Microsoft 365](#unified-manifest-for-microsoft-365) earlier in this article.
+
+## Troubleshooting combined agents and add-ins
+
+The following are some common problems and suggested solutions.
+
+- The agent action fails with a message indicating that the action wasn't found in the add-in. The following are some possible causes.
+
+   - The `"functions.name"` property value in the plug-in's JSON doesn't *exactly match* any `"extensions.runtimes.actions.id"` property in the add-in manifest.
+   - There is a matching `"actions.id"` in the manifest, but the sibling `"actions.type"` value for the same action object isn't "executeDataFunction".
+
+- The agent action fails with a message indicating the action handler registration wasn't found. The following is a possible cause.
+
+   - The add-in's JavaScript doesn't have a call of `Office.actions.associate` with the first parameter *exactly matching* the `"functions.name"` property value in the plug-in's JSON.
+
+## Next steps
+
+- [Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md)
+- [Add a Copilot agent to an add-in](../develop/agent-and-add-in.md)
\ No newline at end of file
diff --git a/docs/develop/agent-and-add-in.md b/docs/develop/agent-and-add-in.md
new file mode 100644
index 0000000000..bcce98ffb3
--- /dev/null
+++ b/docs/develop/agent-and-add-in.md
@@ -0,0 +1,349 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plug-in configuration](#create-the-agent-and-api-plug-in-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plug-ins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The latter have five minutes to complete or Office shuts down the JavaScript runtime. But Copilot-invoked functions have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+    // Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+      context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+      await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following:
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plug-in configuration
+
+1. Create a file in the same folder where your manifest is and give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.3/schema.json",
+        "version": "v1.3",
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the `"actions.file"` property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the `"actions.file"` property in the preceding step; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g., #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "Microsoft.Office.Addin",
+                    "allowed_host": ["workbook"]
+                },
+                "run_for_functions": ["FillColor"]
+            }
+        ]
+    }
+   ```
+
+1. *With some exceptions noted later, replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2).
+
+   As you work, keep the following points in mind.
+
+   - Do *not* change the `"namespace"`, `"runtimes.type"`, or `"runtimes.spec.local_endpoint"` values.
+   - The `"functions.name"` must be an exact match for both of the following:
+
+      - An `"extensions.runtimes.actions.id"` property in the manifest (for an action of type "executeDataFunction").
+      - The first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+
+   - The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+   - The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+   - The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. It tells the Copilot agent to look for functions in an Office Add-in instead of at a REST service URL.
+
+### Create the app package
+
+> [!IMPORTANT]
+> To test the agent, as described later in this article in [Test the agent](#test-the-agent), the domain segment of any absolute URLs in the manifest must be a localhost domain; for example, `localhost:3000`. You can change these segments to a production domain later.
+
+Using any zip utility, create a zip file that contains the following files.
+
+- The manifest
+- The icon files referenced in the manifest's [`"icons.color"`](/microsoft-365/extensibility/schema/root-icons#color) and [`"icons.outline"`](/microsoft-365/extensibility/schema/root-icons#outline)
+- The two files you created in [Create the agent and API plug-in configuration](#create-the-agent-and-api-plug-in-configuration)
+- Any files referenced in the [`"localizationInfo.additionalLanguages"`](/microsoft-365/extensibility/schema/root-localization-info#additionallanguages) property
+
+> [!IMPORTANT]
+> Most of these files have URLs in the manifest that are relative to the location of the manifest, so the folder structure of the zip file must maintain this structure. For example, if the `"icons.color"` value is "/assets/icon-32.png", then there must be an **/assets** folder in the zip file with the **icon-32.png** file in it.
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a subfolder named **build** in the **appPackage** folder and create the zip file in it.
+
+### Test the agent
+
+The three major steps to test the agent &mdash; sideloading, starting a server, and running the agent &mdash; are described in the following subsections.
+
+#### Sideload the agent and add-in
+
+Sideloading is done through Teams even when there's no Teams feature in the app. The steps are as follows.
+
+1. Close all Office applications, and then clear the Office cache following the instructions at [Manually clear the cache](../testing/clear-cache.md#manually-clear-the-cache).
+1. Open Teams and select **Apps** from the app bar, then select **Manage your apps** at the bottom of the **Apps** pane.
+1. Select **Upload an app** in the **Apps** dialog, and then in the dialog that opens, select **Upload a custom app**.
+1. In the **Open** dialog, navigate to, and select, the package zip file.
+1. Select **Add** in the dialog that opens.
+1. When you're prompted that the app was added, *don't* open it in Teams. Instead, close Teams.
+
+#### Start the server
+
+Your task is to start a local web server that hosts your project's HTML and JavaScript files. How you do this depends on several factors including the folder structure of your project, the tools you use, such as a bundler, task manager, server application, and how you have configured those tools. Since you're adding an agent to an existing add-in project, you already know how to do this. The following instruction applies only to projects that meet the following conditions.
+
+- There's a **webpack.config.js** file in the root of the project that is similar to the ones in add-in projects that are created with the [Yeoman Generator for Office Add-ins](yeoman-generator-overview.md) or [Microsoft 365 Agent Toolkit](teams-toolkit-overview.md).
+- There's a **package.json** file in the root of the project similar to the ones created by the same two tools and the file has a "scripts" section with the following script in it.
+
+   ```json
+   "dev-server": "webpack serve --mode development"
+   ```
+
+In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost.
+
+#### Run the agent
+
+1. Open the Office application (Excel, PowerPoint, or Word) that your combined agent and add-in targets. Wait until the add-in has loaded. This may take as much as two minutes. Depending on your version of Office, ribbon buttons and other artifacts may appear automatically. In recent versions, you need to manually activate the add-in: Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in. It will have the name from the name from the [`"name.short"`](/microsoft-365/extensibility/schema/root-name) property in the manifest.
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. Your agent should be be in the list of agents. It has the name specified in the `"name"` property of the declarative agent configuration file (which may not be the same as the name from the `"name.short"` property in the manifest); for example, **Excel Agent**. You may need to select **See more** to ensure that all agents are listed. If the agent isn't listed, try one or both of the following actions.
+
+   - Wait a few minutes and reload Copilot.
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl</kbd>+<kbd>R</kbd>.
+
+   :::image type="content" source="../images/copilot-agent-list.png" alt-text="A screenshot of the agent list in the Copilot pane in an Office application":::
+   
+1. When the agent is listed, select it and the pane for the agent opens. The conversation starters you configured in the `"conversation_starters"` property of declarative agent configuration file will be displayed.
+1. Select a conversation starter, and then press the **Send** control in the conversation box at the bottom of the pane. Select **Confirm** in response to the confirmation prompt. The agent action occurs.
+1. Try entering prompts the conversation box that are different from the conversation starters, but that your agent should be able to do.
+
+### Make changes in the app
+
+Live reloading and hot reloading for a combined add-in and agent aren't supported in the preview period. To make changes, first shut down the server and uninstall the agent and add-in with these steps.
+
+1. Close the Office application.
+1. If the web server is running in the Visual Studio Code **TERMINAL**, give the terminal focus and press <kbd>Ctrl</kbd>+<kbd>C</kbd>. Choose "Y" in response to the prompt to end the process. Then go to the next step. If the web server is running in a separate window, skip this step and go to the next step.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run stop`.
+1. Clear the Office cache following the instructions at [Manually clear the cache](../testing/clear-cache.md#manually-clear-the-cache).
+1. Open Teams and select **Apps** from the app bar, then select **Manage your apps** at the bottom of the **Apps** pane.
+1. Find your agent in the list of apps. It will have the name specified in the `"name"` property of the declarative agent configuration file; for example, **Excel Add-in + Agent**.
+1. Select the arrow head to the left of the name to expand its row.
+1. Select the trash can icon near the right end of the row, and then select **Remove** in the prompt.
+
+Make your changes and then repeat the steps in [Test the agent](#test-the-agent).
+
+## Troubleshooting
+
+See [Troubleshooting combined add-ins and agents](../design/agent-and-add-in-overview.md#troubleshooting-combined-agents-and-add-ins).
diff --git a/docs/images/copilot-agent-list.png b/docs/images/copilot-agent-list.png
new file mode 100644
index 0000000000..af79f34637
Binary files /dev/null and b/docs/images/copilot-agent-list.png differ
diff --git a/docs/quickstarts/agent-and-add-in-quickstart.md b/docs/quickstarts/agent-and-add-in-quickstart.md
new file mode 100644
index 0000000000..9b8c3bccf7
--- /dev/null
+++ b/docs/quickstarts/agent-and-add-in-quickstart.md
@@ -0,0 +1,342 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office Add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press <kbd>F5</kbd>. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears, select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps.
+
+1. In the manifest file, make the following changes.
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.3/schema.json",
+        "version": "v1.3",
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g., #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "Microsoft.Office.Addin",
+                    "allowed_host": ["workbook"]
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. There is a file called either **teamsapp.yaml** or **m365agents.yaml** in the root of project. Replace its contents with the following:
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
+     - uses: teamsApp/publishAppPackage
+       with:
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
+   projectId: da53b0a2-1561-415e-919a-5b870bcd2f49
+   ```
+
+1. Replace the value of `projectId` in the last line of content you pasted in the preceding step with a new randomly generated GUID.
+1. Open the **\env\.env.dev** file and add the following lines to the end of the file, right after the line "ADDIN_ENDPOINT=".
+
+   ```
+   TEAMS_APP_ID=
+   TEAMS_APP_TENANT_ID=
+   M365_TITLE_ID=
+   M365_APP_ID=
+   ```
+
+## Test the add-in and agent
+
+1. Close all Office applications.
+1. Open Microsoft 365 Agent Toolkit.
+1. In the **Lifecycle** pane, select **Provision**. Among other things, provisioning does the following:
+
+   - Set values for the four lines you added to the .env.dev file.
+   - Create a **/build** folder inside the **/appPackage** folder with the package zip file. The file contains the manifest and JSON files for the agent and plug-in.
+
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost. Wait until you see a line in the server window that the app compiled successfully. This means the server is running and serving the files.
+    
+    > [!NOTE]
+    > If this is the first time inover a month you have run a local server for an Office Add-in on your computer, you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+1. The first step in testing depends on the platform.
+
+   - To test in Office on Windows, open Excel. In a few moments, the **Show Task pane** button appears on the **Home** ribbon in the Contoso Add-in group. (If it doesn't appear on the ribbon, select the **Add-ins** button on the ribbon, and then select the **Excel Add-in + Agent** app in the flyout that opens.)
+   - To test in Office on the web, in a browser, navigate to `https://excel.cloud.microsoft.com/`, and then create a new workbook.
+ 
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. **Excel Add-in + Agent** should be in the list of agents. (You may need to select **See more** to ensure that all agents are listed.) If the agent isn't, try one or both of the following actions.
+
+   - Wait a few minutes and reload Copilot.
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl</kbd>+<kbd>R</kbd>.
+
+
+1. When the agent is listed, select it. The **Excel Add-in + Agent** pane opens.
+1. Select the **Change cell color** conversation starter, and then press the **Send** control in the conversation box at the bottom of the pane. Select **Confirm** in response to the confirmation prompt. The cell's color should change.
+
+   > [!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."
+
+1. Try entering other combinations of cell and color in the conversation box, such as "Set cell G5 to the color of the sky".
+
+## Make changes in the add-in or agent
+
+Live reloading and hot reloading for a combined add-in and agent aren't supported in the preview period. To make changes, first shut down the server and uninstall the extension with these steps.
+
+1. Shutting down the server depends on what window it's running in.
+
+   - If the web server is running in the same command prompt or Visual Studio Code **TERMINAL** where you ran `npm run dev-server`, give the window focus and press <kbd>Ctrl</kbd>+<kbd>C</kbd>. Choose "Y" in response to the prompt to end the process. 
+   - If the web server is running in a separate window, then in a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run stop`.
+
+1. Clear the Office cache following the instructions at [Manually clear the cache](../testing/clear-cache.md#manually-clear-the-cache).
+1. Open Teams and select **Apps** from the app bar, then select **Manage your apps** at the bottom of the **Apps** pane.
+1. Find **Excel Add-in + Agent** in the list of apps, and select the arrow head to the left of the name to expand its row.
+1. Select the trash can icon near the right end of the row, and then select **Remove** in the prompt.
+
+Make your changes and then repeat the steps in [Test the add-in and agent](#test-the-add-in-and-agent).
+
+## Troubleshooting
+
+See [Troubleshooting combined add-ins and agents](../design/agent-and-add-in-overview.md#troubleshooting-combined-agents-and-add-ins).
+
+## Next steps
+
+- [Add a Copilot agent to an existing add-in](../develop/agent-and-add-in.md)
+
+## See also
+
+- [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md)
+- [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object)
+- [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2)
\ No newline at end of file
diff --git a/docs/toc.yml b/docs/toc.yml
index 46016b637b..43b2b24c51 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -265,6 +265,17 @@ items:
             href: design/custom-tab-placement.md
         - name: Content add-ins
           href: design/content-add-ins.md
+        - name: Copilot agents
+          items:
+          - name: Combine Copilot Agents with Office Add-ins
+            href: design/agent-and-add-in-overview.md
+            displayName: preview
+          - name: Build your first add-in as a Copilot skill
+            href: quickstarts/agent-and-add-in-quickstart.md
+            displayName: preview
+          - name: Add a Copilot agent to an add-in
+            href: develop/agent-and-add-in.md
+            displayName: preview
         - name: Dialog boxes
           items:
           - name: Use the Office dialog API in your Office Add-ins


Reviews:
user: login: ElizabethSamuel-MSFT
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T15:56:56Z
user: login: ElizabethSamuel-MSFT
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T15:59:07Z
user: login: Rick-Kirkham
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T16:58:43Z
user: login: ElizabethSamuel-MSFT
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:51:10Z
user: login: ElizabethSamuel-MSFT
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:25:19Z

Review comments:
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
> This article assumes you're familiar with Copilot declarative agents. If you're not, start with the following:
```
created_at: 2025-05-09T14:37:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
You can also think of an Office Add-in as a skill in a Copilot agent. Because Office Add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
```
created_at: 2025-05-09T14:38:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
- **Learning how to use the add-in**: When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
```
created_at: 2025-05-09T14:52:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
- **Content analysis**: An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
```
created_at: 2025-05-09T14:52:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
- **Trusted insertion of data**: If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process that can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
```
created_at: 2025-05-09T14:54:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent: "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
```
created_at: 2025-05-09T14:55:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests: "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
```
created_at: 2025-05-09T14:55:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plugin configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/plug-in

```suggestion
The agent configuration file includes instructions for the agent and specifies one or more API plug-in configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
```
created_at: 2025-05-09T14:59:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plugin configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
+
+- The conversation starter appears in the chat canvas of Copilot.
+- The `"actions.id"` property in this file is the collective ID of all the functions in the file specified in `"actions.file"`. It doesn't have to match the `"actions.id"` in the manifest.
+
+```json
+{
+    "name": "Excel Add-in + Agent",
+    "description": "Agent for working with Excel cells.",
+    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+    "conversation_starters": [
+        {
+            "title": "Change cell color",
+            "text": "I want to change the color of cell B2 to orange"
+        }
+    ],
+    "actions": [
+        {
+            "id": "localExcelPlugin",
+            "file": "Excel-API-local-plugin.json"
+        }
+    ]
+}
+```
+
+The reference documentation for declarative agents is at [Declarative agent schema 1.3 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.3).
+
+### Copilot API plugin configuration
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
### Copilot API plug-in configuration
```
created_at: 2025-05-09T15:00:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plugin configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
+
+- The conversation starter appears in the chat canvas of Copilot.
+- The `"actions.id"` property in this file is the collective ID of all the functions in the file specified in `"actions.file"`. It doesn't have to match the `"actions.id"` in the manifest.
+
+```json
+{
+    "name": "Excel Add-in + Agent",
+    "description": "Agent for working with Excel cells.",
+    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+    "conversation_starters": [
+        {
+            "title": "Change cell color",
+            "text": "I want to change the color of cell B2 to orange"
+        }
+    ],
+    "actions": [
+        {
+            "id": "localExcelPlugin",
+            "file": "Excel-API-local-plugin.json"
+        }
+    ]
+}
+```
+
+The reference documentation for declarative agents is at [Declarative agent schema 1.3 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.3).
+
+### Copilot API plugin configuration
+
+The API plugin configuration file specifies the "functions" of the plugin in the sense of agent actions, not JavaScript functions, including the instructions for the action. It also configures the JavaScript runtime for Copilot. The following is an example. About this JSON, note the following:
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
The API plug-in configuration file specifies the "functions" of the plug-in in the sense of agent actions, not JavaScript functions, including the instructions for the action. It also configures the JavaScript runtime for Copilot. The following is an example. About this JSON, note the following:
```
created_at: 2025-05-09T15:01:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plugin configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
+
+- The conversation starter appears in the chat canvas of Copilot.
+- The `"actions.id"` property in this file is the collective ID of all the functions in the file specified in `"actions.file"`. It doesn't have to match the `"actions.id"` in the manifest.
+
+```json
+{
+    "name": "Excel Add-in + Agent",
+    "description": "Agent for working with Excel cells.",
+    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+    "conversation_starters": [
+        {
+            "title": "Change cell color",
+            "text": "I want to change the color of cell B2 to orange"
+        }
+    ],
+    "actions": [
+        {
+            "id": "localExcelPlugin",
+            "file": "Excel-API-local-plugin.json"
+        }
+    ]
+}
+```
+
+The reference documentation for declarative agents is at [Declarative agent schema 1.3 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.3).
+
+### Copilot API plugin configuration
+
+The API plugin configuration file specifies the "functions" of the plugin in the sense of agent actions, not JavaScript functions, including the instructions for the action. It also configures the JavaScript runtime for Copilot. The following is an example. About this JSON, note the following:
+
+- The `"functions.name"` must match the `"extensions.runtimes.actions.id"` property in the add-in manifest.
+- The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+- The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+- The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. In this case, it specifies that the JavaScript function that is associated with the "fillcolor" string is available in an Office add-in, rather than in some REST endpoint.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+    "schema_version": "v2.3",
+    "name_for_human": "Excel Add-in + Agent",
+    "description_for_human": "Add-in Actions in Agents",
+    "namespace": "addinfunction",
+    "functions": [
+        {
+            "name": "fillcolor",
+            "description": "fillcolor changes a single cell location to a specific color.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "Cell": {
+                        "type": "string",
+                        "description": "A cell location in the format of A1, B2, etc.",
+                        "default" : "B2"
+                    },
+                    "Color": {
+                        "type": "string",
+                        "description": "A color in hex format, e.g. #30d5c8",
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
                        "description": "A color in hex format, e.g., #30d5c8",
```
created_at: 2025-05-09T15:03:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plugin configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
+
+- The conversation starter appears in the chat canvas of Copilot.
+- The `"actions.id"` property in this file is the collective ID of all the functions in the file specified in `"actions.file"`. It doesn't have to match the `"actions.id"` in the manifest.
+
+```json
+{
+    "name": "Excel Add-in + Agent",
+    "description": "Agent for working with Excel cells.",
+    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+    "conversation_starters": [
+        {
+            "title": "Change cell color",
+            "text": "I want to change the color of cell B2 to orange"
+        }
+    ],
+    "actions": [
+        {
+            "id": "localExcelPlugin",
+            "file": "Excel-API-local-plugin.json"
+        }
+    ]
+}
+```
+
+The reference documentation for declarative agents is at [Declarative agent schema 1.3 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.3).
+
+### Copilot API plugin configuration
+
+The API plugin configuration file specifies the "functions" of the plugin in the sense of agent actions, not JavaScript functions, including the instructions for the action. It also configures the JavaScript runtime for Copilot. The following is an example. About this JSON, note the following:
+
+- The `"functions.name"` must match the `"extensions.runtimes.actions.id"` property in the add-in manifest.
+- The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+- The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+- The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. In this case, it specifies that the JavaScript function that is associated with the "fillcolor" string is available in an Office add-in, rather than in some REST endpoint.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+    "schema_version": "v2.3",
+    "name_for_human": "Excel Add-in + Agent",
+    "description_for_human": "Add-in Actions in Agents",
+    "namespace": "addinfunction",
+    "functions": [
+        {
+            "name": "fillcolor",
+            "description": "fillcolor changes a single cell location to a specific color.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "Cell": {
+                        "type": "string",
+                        "description": "A cell location in the format of A1, B2, etc.",
+                        "default" : "B2"
+                    },
+                    "Color": {
+                        "type": "string",
+                        "description": "A color in hex format, e.g. #30d5c8",
+                        "default" : "#30d5c8"
+                    }
+                },
+                "required": ["Cell", "Color"]
+            },
+            "returns": {
+                "type": "string",
+                "description": "A string indicating the result of the action."
+            },
+            "states": {
+                "reasoning": {
+                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                    "instructions": "The user will ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                },
+                "responding": {
+                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                    "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                }
+            }
+        }
+    ],
+    "runtimes": [
+        {
+            "type": "LocalPlugin",
+            "spec": {
+                "local_endpoint": "ms-office-addin"
+            },
+            "run_for_functions": ["fillcolor"]
+        }
+    ]
+}
+```
+
+The reference documentation for API plugins is at [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2). The following is the documentation for the `"runtimes.spec.local_endpoint"` property.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
The reference documentation for API plug-ins is at [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2). The following is the documentation for the `"runtimes.spec.local_endpoint"` property.
```
created_at: 2025-05-09T15:04:47Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plugin configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
+
+- The conversation starter appears in the chat canvas of Copilot.
+- The `"actions.id"` property in this file is the collective ID of all the functions in the file specified in `"actions.file"`. It doesn't have to match the `"actions.id"` in the manifest.
+
+```json
+{
+    "name": "Excel Add-in + Agent",
+    "description": "Agent for working with Excel cells.",
+    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+    "conversation_starters": [
+        {
+            "title": "Change cell color",
+            "text": "I want to change the color of cell B2 to orange"
+        }
+    ],
+    "actions": [
+        {
+            "id": "localExcelPlugin",
+            "file": "Excel-API-local-plugin.json"
+        }
+    ]
+}
+```
+
+The reference documentation for declarative agents is at [Declarative agent schema 1.3 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.3).
+
+### Copilot API plugin configuration
+
+The API plugin configuration file specifies the "functions" of the plugin in the sense of agent actions, not JavaScript functions, including the instructions for the action. It also configures the JavaScript runtime for Copilot. The following is an example. About this JSON, note the following:
+
+- The `"functions.name"` must match the `"extensions.runtimes.actions.id"` property in the add-in manifest.
+- The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+- The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+- The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. In this case, it specifies that the JavaScript function that is associated with the "fillcolor" string is available in an Office add-in, rather than in some REST endpoint.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+    "schema_version": "v2.3",
+    "name_for_human": "Excel Add-in + Agent",
+    "description_for_human": "Add-in Actions in Agents",
+    "namespace": "addinfunction",
+    "functions": [
+        {
+            "name": "fillcolor",
+            "description": "fillcolor changes a single cell location to a specific color.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "Cell": {
+                        "type": "string",
+                        "description": "A cell location in the format of A1, B2, etc.",
+                        "default" : "B2"
+                    },
+                    "Color": {
+                        "type": "string",
+                        "description": "A color in hex format, e.g. #30d5c8",
+                        "default" : "#30d5c8"
+                    }
+                },
+                "required": ["Cell", "Color"]
+            },
+            "returns": {
+                "type": "string",
+                "description": "A string indicating the result of the action."
+            },
+            "states": {
+                "reasoning": {
+                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                    "instructions": "The user will ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                },
+                "responding": {
+                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                    "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                }
+            }
+        }
+    ],
+    "runtimes": [
+        {
+            "type": "LocalPlugin",
+            "spec": {
+                "local_endpoint": "ms-office-addin"
+            },
+            "run_for_functions": ["fillcolor"]
+        }
+    ]
+}
+```
+
+The reference documentation for API plugins is at [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2). The following is the documentation for the `"runtimes.spec.local_endpoint"` property.
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `local_endpoint` | String | Optional. The ID of a set of available JavaScript functions. This property is roughly analogous to the [`"runtimes.spec.url"`](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2#openapi-specification-object) property, but for local functions on the client, not REST APIs.|
+
+## Create the JavaScript functions
+
+The JavaScript functions that will be invoked by the Copilot agent are created exactly as [function commands](../develop/create-addin-commands-unified-manifest.md#add-a-function-command) are created. The following is an example. Note the following about this code.
+
+- Unlike a function command, a function associated with a Copilot action can take parameters.
+- The first parameter of the `associate` method must match both the `"extensions.runtimes.actions.id"` property in the add-in manifest and the "functions.name" property in the API plugins JSON.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
- The first parameter of the `associate` method must match both the `"extensions.runtimes.actions.id"` property in the add-in manifest and the `"functions.name"` property in the API plug-in's JSON.
```
created_at: 2025-05-09T15:13:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
```
created_at: 2025-05-09T15:16:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plug-ins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
```
created_at: 2025-05-09T15:19:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: Can you take another look at this? The last sentence didn't make sense to me...

```suggestion
- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The latter have five minutes to complete or Office shuts down the JavaScript runtime. But Copilot-invoked functions have only two minutes to return a result or the runtime is shut down.
```
created_at: 2025-05-09T15:23:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
    // Add any initialization code here.
```
created_at: 2025-05-09T15:25:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
      context.workbook.worksheets
```
created_at: 2025-05-09T15:26:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
      await context.sync();
```
created_at: 2025-05-09T15:26:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following:
```
created_at: 2025-05-09T15:27:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
### Create the agent and API plug-in configuration
```
created_at: 2025-05-09T15:28:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
+
+1. Create a file in the same folder where your manifest is give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
1. Create a file in the same folder where your manifest is and give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
```
created_at: 2025-05-09T15:29:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
+
+1. Create a file in the same folder where your manifest is give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2,
+                            etc.",
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
                            "description": "A cell location in the format of A1, B2, etc.",
```
created_at: 2025-05-09T15:30:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
+
+1. Create a file in the same folder where your manifest is give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2,
+                            etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["FillColor"]
+            }
+        ]
+    }
+   ```
+
+1. *With some exceptions noted later, replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2).
+
+   As you work, keep the following points in mind.
+
+   - Do *not* change the `"namespace"`, `"runtimes.type"`, or `"runtimes.spec.local_endpoint"` values.
+   - The `"functions.name"` must be an exact match for both of the following.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - The `"functions.name"` must be an exact match for both of the following:
```
created_at: 2025-05-09T15:31:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
+
+1. Create a file in the same folder where your manifest is give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2,
+                            etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["FillColor"]
+            }
+        ]
+    }
+   ```
+
+1. *With some exceptions noted later, replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2).
+
+   As you work, keep the following points in mind.
+
+   - Do *not* change the `"namespace"`, `"runtimes.type"`, or `"runtimes.spec.local_endpoint"` values.
+   - The `"functions.name"` must be an exact match for both of the following.
+
+      - An `"extensions.runtimes.actions.id"` property in the manifest (for an action of type "executeDataFunction")
+      - The first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file)
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
      - An `"extensions.runtimes.actions.id"` property in the manifest (for an action of type "executeDataFunction").
      - The first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
```
created_at: 2025-05-09T15:32:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
+
+1. Create a file in the same folder where your manifest is give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2,
+                            etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["FillColor"]
+            }
+        ]
+    }
+   ```
+
+1. *With some exceptions noted later, replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2).
+
+   As you work, keep the following points in mind.
+
+   - Do *not* change the `"namespace"`, `"runtimes.type"`, or `"runtimes.spec.local_endpoint"` values.
+   - The `"functions.name"` must be an exact match for both of the following.
+
+      - An `"extensions.runtimes.actions.id"` property in the manifest (for an action of type "executeDataFunction")
+      - The first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file)
+
+   - The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+   - The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+   - The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. It tells the Copilot agent to look for functions in an Office add-in instead of at a REST service URL.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. It tells the Copilot agent to look for functions in an Office Add-in instead of at a REST service URL.
```
created_at: 2025-05-09T15:34:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,243 @@
+---
+title: Combine Copilot Agents with Office Add-ins (preview)
+description: Get an overview of why and how to combine a Copilot agent with an Office Add-in.
+ms.date: 05/19/2025
+ms.topic: overview
+ms.localizationpriority: medium
+---
+
+# Combine Copilot Agents with Office Add-ins (preview)
+
+> [!NOTE]
+> This article assumes you are familiar with Copilot declarative agents. If you're not, start with the following:
+>
+> - [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+> - [Agents are apps for Microsoft 365](/microsoft-365-copilot/extensibility/agents-are-apps).
+
+Including a Microsoft 365 Copilot agent in an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+You can also think of an Office Add-in as a skill in a Copilot agent. Because Office add-ins use the [Office JavaScript Library](../develop/understanding-the-javascript-api-for-office.md) to perform read and write operations on Office documents, these operations become actions in the Copilot agent.
+
+## Scenarios
+
+The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
+
+- **Learning how to use the add-in:** When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+
+- **Content analysis:** An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
+
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
+
+- **Trusted insertion of data:** If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
+   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+
+## The relation of Copilot agents to the Add-in framework
+
+A Copilot agent is a natural language interface for an add-in.
+
+An add-in can be configured to be *only* a skill in a Copilot agent. It doesn't have to include a task pane, custom ribbon buttons, or custom menus; but it can have any of these in addition to being a Copilot skill. The best approach depends on the user scenarios that the add-in should enable.
+
+- If the add-in should provide simple, fast actions that don't need parameters passed to them, include custom ribbon buttons or menus, called [add-in commands](add-in-commands.md), in the add-in.
+- If the add-in needs a dashboard experience, needs the user to configure settings, needs to display metadata about the content of the Office document, or needs a page-like experience for any other reason, include a task pane in the add-in.
+- If the add-in needs to provide complex actions that require parameters passed at runtime or needs a natural language interface, include a Copilot agent.
+
+> [!NOTE]
+>
+> - Currently, only Excel, PowerPoint, and Word add-ins can be configured as a skill in Copilot. We're working to support Outlook.
+> - Copilot agents aren't currently supported in Office on Mac.
+> - An add-in must use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) to be configured as a skill in Copilot.
+> - A [content add-in](content-add-ins.md) cannot be a skill in Copilot.
+
+## Major tasks
+
+There are two major tasks to configuring an add-in as a Copilot skill, and they are analogous to the two tasks for configuring [function commands](add-in-commands.md#types-of-add-in-commands) for an add-in.
+
+- Create JavaScript functions that implement the agent's actions.
+- Use JSON to specify for Office and the JavaScript runtimes the names of these functions.
+
+## JSON configuration
+
+Configuration of an add-in to be a Copilot skill requires three JSON-formatted files that are described in the following subsections.
+
+### Unified manifest for Microsoft 365
+
+There are two parts of the manifest that you configure. First, create an action object that identifies the JavaScript function that is invoked by the action. The following is an example (with some extraneous markup omitted). Note the following about this code.
+
+- The "page" property specifies the URL of the web page that contains an embedded script tag that, in turn, specifies the URL of the JavaScript file where the function is defined. That same file contains an invocation of the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) method to map the function to an action ID.
+- The [`"actions.id"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#id) property in the manifest is the same action ID that is passed to the call of `associate`.
+- The [`"actions.type"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item#type) property is set to "executeDataFunction", which is the type that can accept parameters and can be invoked by Copilot.
+
+```json
+"extensions": [
+
+    ...
+
+    "runtimes": [
+        {
+            "id": "CommandsRuntime",
+            "type": "general",
+            "code": {
+                "page": "https://localhost:3000/commands.html"
+            },
+            "lifetime": "short",
+            "actions": [
+                {
+                    "id": "fillcolor",
+                    "type": "executeDataFunction",
+                }
+            ]
+        }
+    ]
+]
+```
+
+Second, create a declarative agent object that identifies the file containing the detailed configuration of the agent. The following is an example.
+
+```json
+"copilotAgents": {
+    "declarativeAgents": [
+        {
+        "id": "ContosoCopilotAgent",
+        "file": "declarativeAgent.json"
+        }
+    ]
+}
+```
+
+The reference documentation for the manifest JSON is at [Microsoft 365 app manifest schema reference](/microsoft-365/extensibility/schema/).
+
+### Declarative agent configuration
+
+The agent configuration file includes instructions for the agent and specifies one or more API plugin configuration files that will contain the detailed configuration of the agent's actions. The following is an example. Note the following about this JSON.
+
+- The conversation starter appears in the chat canvas of Copilot.
+- The `"actions.id"` property in this file is the collective ID of all the functions in the file specified in `"actions.file"`. It doesn't have to match the `"actions.id"` in the manifest.
+
+```json
+{
+    "name": "Excel Add-in + Agent",
+    "description": "Agent for working with Excel cells.",
+    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+    "conversation_starters": [
+        {
+            "title": "Change cell color",
+            "text": "I want to change the color of cell B2 to orange"
+        }
+    ],
+    "actions": [
+        {
+            "id": "localExcelPlugin",
+            "file": "Excel-API-local-plugin.json"
+        }
+    ]
+}
+```
+
+The reference documentation for declarative agents is at [Declarative agent schema 1.3 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.3).
+
+### Copilot API plugin configuration
+
+The API plugin configuration file specifies the "functions" of the plugin in the sense of agent actions, not JavaScript functions, including the instructions for the action. It also configures the JavaScript runtime for Copilot. The following is an example. About this JSON, note the following:
+
+- The `"functions.name"` must match the `"extensions.runtimes.actions.id"` property in the add-in manifest.
+- The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+- The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+- The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. In this case, it specifies that the JavaScript function that is associated with the "fillcolor" string is available in an Office add-in, rather than in some REST endpoint.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
- The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. In this case, it specifies that the JavaScript function that is associated with the "fillcolor" string is available in an Office Add-in, rather than in some REST endpoint.
```
created_at: 2025-05-09T15:34:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
+
+1. Create a file in the same folder where your manifest is give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2,
+                            etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["FillColor"]
+            }
+        ]
+    }
+   ```
+
+1. *With some exceptions noted later, replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2).
+
+   As you work, keep the following points in mind.
+
+   - Do *not* change the `"namespace"`, `"runtimes.type"`, or `"runtimes.spec.local_endpoint"` values.
+   - The `"functions.name"` must be an exact match for both of the following.
+
+      - An `"extensions.runtimes.actions.id"` property in the manifest (for an action of type "executeDataFunction")
+      - The first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file)
+
+   - The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+   - The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+   - The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. It tells the Copilot agent to look for functions in an Office add-in instead of at a REST service URL.
+
+### Create the app package
+
+> [!IMPORTANT]
+> To test the agent, as described later in this article in [Test the agent](#test-the-agent), the domain segment of any absolute URLs in the manifest must be a localhost domain; for example, `localhost:3000`. You can change these segments to a production domain later.
+
+Using any zip utility, create a zip file that contains the following files.
+
+- The manifest
+- The icon files referenced in the manifest's [`"icons.color"`](/microsoft-365/extensibility/schema/root-icons#color) and [`"icons.outline"`](/microsoft-365/extensibility/schema/root-icons#outline)
+- The two files you created in [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- Any files referenced in the [`"localizationInfo.additionalLanguages"`](/microsoft-365/extensibility/schema/root-localization-info#additionallanguages) property
+
+> [!IMPORTANT]
+> Most of these files have URLs in the manifest that are relative to the location of the manifest, so the folder structure of the zip file must maintain this structure. For example, if the `"icons.color"` value is "/assets/icon-32.png", then there must be an **/assets** folder in the zip file with the **icon-32.png** file in it.
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a subfolder named **build** in the **appPackage** folder and create the zip file in it.
+
+### Test the agent
+
+The three major steps to test the agent &mdash; sideloading, starting a server, and running the agent &mdash; are described in the following subsections.
+
+#### Sideload the agent and add-in
+
+Sideloading is done through Teams even when there's no Teams feature in the app. The steps are as follows.
+
+1. Close all Office applications, and then Clear the Office cache following the instructions at [Manually clear the cache](../testing/clear-cache.md#manually-clear-the-cache).
+1. Open Teams and select **Apps** from the app bar, then select **Manage your apps** at the bottom of the **Apps** pane.
+1. Select **Upload an app** in the **Apps** dialog, and then in the dialog that opens, select **Upload a custom app**.
+1. In the **Open** dialog, navigate to, and select, the package zip file.
+1. Select **Add** in the dialog that opens.
+1. When you're prompted that the app was added, *don't* open it in Teams. Instead, close Teams.
+
+#### Start the server
+
+Your task is to start a local web server that hosts your project's HTML and JavaScript files. How you do this depends on several factors including the folder structure of your project, the tools you use, such as a bundler, task manager, server application, and how you have configured those tools. Since you're adding an agent to an existing add-in project, you already know how to do this. The following instruction applies only to projects that meet the following conditions.
+
+- There's a **webpack.config.js** file in the root of the project that is similar to the ones in add-in projects that are created with the [Yeoman Generator for Office Add-ins](yeoman-generator-overview.md) or [Microsoft 365 Agent Toolkit](teams-toolkit-overview.md).
+- There's a **package.json** file in the root of the project similar to the ones created by the same two tools and the file has a "scripts" section with the following script in it.
+
+   ```json
+   "dev-server": "webpack serve --mode development"
+   ```
+
+In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost.
+
+#### Run the agent
+
+1. Open the Office application (Excel, PowerPoint, or Word) that your combined agent and add-in targets. Wait until the add-in has loaded. This may take as much as two minutes. Depending on your version of Office, ribbon buttons and other artifacts may appear automatically. In recent versions, you need to manually activate the add-in: Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in. It will have the name from the name from the [`"name.short"`](/microsoft-365/extensibility/schema/root-name) property in the manifest.
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. Your agent should be be in the list of agents. It must have the name specified in the `"name"` property of the declarative agent configuration file (which may not be the same as the name from the `"name.short"` property in the manifest); for example, **Excel Add-in + Agent**. You may need to select **See more** to ensure that all agents are listed. If the agent isn't listed, try the following actions.
+
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl-r</kbd>.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl</kbd>+<kbd>R</kbd>.
```
created_at: 2025-05-09T15:41:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,342 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [ Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plugins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The former have five minutes to complete or Office shuts down the JavaScript runtime. But have Copilot-invoked function have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+// Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+    context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+    await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following.
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plugin configuration
+
+1. Create a file in the same folder where your manifest is give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2,
+                            etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["FillColor"]
+            }
+        ]
+    }
+   ```
+
+1. *With some exceptions noted later, replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2).
+
+   As you work, keep the following points in mind.
+
+   - Do *not* change the `"namespace"`, `"runtimes.type"`, or `"runtimes.spec.local_endpoint"` values.
+   - The `"functions.name"` must be an exact match for both of the following.
+
+      - An `"extensions.runtimes.actions.id"` property in the manifest (for an action of type "executeDataFunction")
+      - The first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file)
+
+   - The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+   - The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+   - The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. It tells the Copilot agent to look for functions in an Office add-in instead of at a REST service URL.
+
+### Create the app package
+
+> [!IMPORTANT]
+> To test the agent, as described later in this article in [Test the agent](#test-the-agent), the domain segment of any absolute URLs in the manifest must be a localhost domain; for example, `localhost:3000`. You can change these segments to a production domain later.
+
+Using any zip utility, create a zip file that contains the following files.
+
+- The manifest
+- The icon files referenced in the manifest's [`"icons.color"`](/microsoft-365/extensibility/schema/root-icons#color) and [`"icons.outline"`](/microsoft-365/extensibility/schema/root-icons#outline)
+- The two files you created in [Create the agent and API plugin configuration](#create-the-agent-and-api-plugin-configuration)
+- Any files referenced in the [`"localizationInfo.additionalLanguages"`](/microsoft-365/extensibility/schema/root-localization-info#additionallanguages) property
+
+> [!IMPORTANT]
+> Most of these files have URLs in the manifest that are relative to the location of the manifest, so the folder structure of the zip file must maintain this structure. For example, if the `"icons.color"` value is "/assets/icon-32.png", then there must be an **/assets** folder in the zip file with the **icon-32.png** file in it.
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a subfolder named **build** in the **appPackage** folder and create the zip file in it.
+
+### Test the agent
+
+The three major steps to test the agent &mdash; sideloading, starting a server, and running the agent &mdash; are described in the following subsections.
+
+#### Sideload the agent and add-in
+
+Sideloading is done through Teams even when there's no Teams feature in the app. The steps are as follows.
+
+1. Close all Office applications, and then Clear the Office cache following the instructions at [Manually clear the cache](../testing/clear-cache.md#manually-clear-the-cache).
+1. Open Teams and select **Apps** from the app bar, then select **Manage your apps** at the bottom of the **Apps** pane.
+1. Select **Upload an app** in the **Apps** dialog, and then in the dialog that opens, select **Upload a custom app**.
+1. In the **Open** dialog, navigate to, and select, the package zip file.
+1. Select **Add** in the dialog that opens.
+1. When you're prompted that the app was added, *don't* open it in Teams. Instead, close Teams.
+
+#### Start the server
+
+Your task is to start a local web server that hosts your project's HTML and JavaScript files. How you do this depends on several factors including the folder structure of your project, the tools you use, such as a bundler, task manager, server application, and how you have configured those tools. Since you're adding an agent to an existing add-in project, you already know how to do this. The following instruction applies only to projects that meet the following conditions.
+
+- There's a **webpack.config.js** file in the root of the project that is similar to the ones in add-in projects that are created with the [Yeoman Generator for Office Add-ins](yeoman-generator-overview.md) or [Microsoft 365 Agent Toolkit](teams-toolkit-overview.md).
+- There's a **package.json** file in the root of the project similar to the ones created by the same two tools and the file has a "scripts" section with the following script in it.
+
+   ```json
+   "dev-server": "webpack serve --mode development"
+   ```
+
+In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost.
+
+#### Run the agent
+
+1. Open the Office application (Excel, PowerPoint, or Word) that your combined agent and add-in targets. Wait until the add-in has loaded. This may take as much as two minutes. Depending on your version of Office, ribbon buttons and other artifacts may appear automatically. In recent versions, you need to manually activate the add-in: Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in. It will have the name from the name from the [`"name.short"`](/microsoft-365/extensibility/schema/root-name) property in the manifest.
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. Your agent should be be in the list of agents. It must have the name specified in the `"name"` property of the declarative agent configuration file (which may not be the same as the name from the `"name.short"` property in the manifest); for example, **Excel Add-in + Agent**. You may need to select **See more** to ensure that all agents are listed. If the agent isn't listed, try the following actions.
+
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl-r</kbd>.
+   - Wait a few minutes and reload Copilot.
+   
+1. When the agent is listed, select it and the pane for the agent opens. The conversation starters you configured in the `"conversation_starters"` property of declarative agent configuration file will be displayed.
+1. Select a conversation starter, and then press the **Send** control in the conversation box at the bottom of the pane. Select **Confirm** in response to the confirmation prompt. The agent action occurs.
+1. Try entering requests the conversation box that are different from the conversation starters, but that your agent should be able to do.
+
+### Make changes in the app
+
+Live reloading and hot reloading for a combined add-in and agent aren't supported in the preview period. To make changes, first shut down the server and uninstall the agent and add-in with these steps.
+
+1. Close the Office application.
+1. If the web server is running in the Visual Studio Code **TERMINAL**, give the terminal focus and press Ctrl-C. Choose "Y" in response to the prompt to end the process. Then go to the next step. If the web server is running in a separate window skip this step and go to the next step.
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
1. If the web server is running in the Visual Studio Code **TERMINAL**, give the terminal focus and press <kbd>Ctrl</kbd>+<kbd>C</kbd>. Choose "Y" in response to the prompt to end the process. Then go to the next step. If the web server is running in a separate window, skip this step and go to the next step.
```
created_at: 2025-05-09T15:42:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   1. Press <kbd>F5</kbd>. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
```
created_at: 2025-05-09T15:44:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   > If a **WebView Stop On Load** prompt appears, select **OK**.
```
created_at: 2025-05-09T15:45:13Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
Add the agent with the following steps.
```
created_at: 2025-05-09T15:45:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
1. In the manifest file, make the following changes.
```
created_at: 2025-05-09T15:45:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
1. Open the teamsapp.yaml file in the root of project and replace its contents with the following:
```
created_at: 2025-05-09T15:47:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Triggered when 'teamsapp provision' is executed.
```
created_at: 2025-05-09T15:47:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Creates a Teams app.
```
created_at: 2025-05-09T15:48:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
       # the specified environment variables.
```
created_at: 2025-05-09T15:48:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Build Teams app package with latest env value.
```
created_at: 2025-05-09T15:48:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Extend your Teams app to Outlook and the Microsoft 365 app.
```
created_at: 2025-05-09T15:49:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
       # the specified environment variables.
```
created_at: 2025-05-09T15:49:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Triggered when 'teamsapp publish' is executed.
```
created_at: 2025-05-09T15:49:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Build Teams app package with latest env value.
```
created_at: 2025-05-09T15:49:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Validate app package using validation rules.
```
created_at: 2025-05-09T15:49:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # Will use the app ID in manifest file to determine which Teams app to update.
```
created_at: 2025-05-09T15:50:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   # for review and approval.
```
created_at: 2025-05-09T15:50:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
+     - uses: teamsApp/publishAppPackage
+       with:
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
       # the specified environment variables.
```
created_at: 2025-05-09T15:50:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
+     - uses: teamsApp/publishAppPackage
+       with:
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
+   projectId: da53b0a2-1561-415e-919a-5b870bcd2f49
+   ```
+
+1. Replace the value of `projectId` in the last line of content you pasted in the preceding step with a new randomly generated GUID.
+1. Open the **\env\.env.dev** file and add the following lines to the end of the file, right after the line "ADDIN_ENDPOINT=".
+
+   ```
+   TEAMS_APP_ID=
+   TEAMS_APP_TENANT_ID=
+   M365_TITLE_ID=
+   M365_APP_ID=
+   ```
+
+## Test the add-in and agent
+
+1. Close all Office applications.
+1. Open Microsoft 365 Agent Toolkit.
+1. In the **Lifecycle** pane, select **Provision**. Among other things, provisioning does the following:
+
+   - Set values for the four lines you added to the .env.dev file.
+   - Create a **/build** folder inside the **/appPackage** folder with the package zip file. The file contains the manifest and JSON files for the agent and plugin.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - Create a **/build** folder inside the **/appPackage** folder with the package zip file. The file contains the manifest and JSON files for the agent and plug-in.
```
created_at: 2025-05-09T15:51:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
+     - uses: teamsApp/publishAppPackage
+       with:
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
+   projectId: da53b0a2-1561-415e-919a-5b870bcd2f49
+   ```
+
+1. Replace the value of `projectId` in the last line of content you pasted in the preceding step with a new randomly generated GUID.
+1. Open the **\env\.env.dev** file and add the following lines to the end of the file, right after the line "ADDIN_ENDPOINT=".
+
+   ```
+   TEAMS_APP_ID=
+   TEAMS_APP_TENANT_ID=
+   M365_TITLE_ID=
+   M365_APP_ID=
+   ```
+
+## Test the add-in and agent
+
+1. Close all Office applications.
+1. Open Microsoft 365 Agent Toolkit.
+1. In the **Lifecycle** pane, select **Provision**. Among other things, provisioning does the following:
+
+   - Set values for the four lines you added to the .env.dev file.
+   - Create a **/build** folder inside the **/appPackage** folder with the package zip file. The file contains the manifest and JSON files for the agent and plugin.
+
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost. Wait until you see a line in the server window that the app compiled successfully. This means the server is running and serving the files.
+    
+    > [!NOTE]
+    > If this is the first time inover a month you have run a local server for an Office Add-in on your computer, you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+1. The first step in testing depends on the platform.
+
+   - To test in Office on Windows, open Excel. In a few moments, the **Show Task pane** button appears on the **Home** ribbon in the Contoso Add-in group. (If it doesn't appear on the ribbon, select the **Add-ins** button on the ribbon, and then select the **Excel Add-in + Agent** app in the flyout that opens.)
+   - To test in Office on the web, in a browser, navigate to `https://excel.cloud.microsoft.com/`, and then create a new workbook.
+ 
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. **Excel Add-in + Agent** should be in the list of agents. (You may need to select **See more** to ensure that all agents are listed.) If the agent isn't, try the following actions.
+
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl-r</kbd>.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl</kbd>+<kbd>R</kbd>.
```
created_at: 2025-05-09T15:52:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
+     - uses: teamsApp/publishAppPackage
+       with:
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
+   projectId: da53b0a2-1561-415e-919a-5b870bcd2f49
+   ```
+
+1. Replace the value of `projectId` in the last line of content you pasted in the preceding step with a new randomly generated GUID.
+1. Open the **\env\.env.dev** file and add the following lines to the end of the file, right after the line "ADDIN_ENDPOINT=".
+
+   ```
+   TEAMS_APP_ID=
+   TEAMS_APP_TENANT_ID=
+   M365_TITLE_ID=
+   M365_APP_ID=
+   ```
+
+## Test the add-in and agent
+
+1. Close all Office applications.
+1. Open Microsoft 365 Agent Toolkit.
+1. In the **Lifecycle** pane, select **Provision**. Among other things, provisioning does the following:
+
+   - Set values for the four lines you added to the .env.dev file.
+   - Create a **/build** folder inside the **/appPackage** folder with the package zip file. The file contains the manifest and JSON files for the agent and plugin.
+
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost. Wait until you see a line in the server window that the app compiled successfully. This means the server is running and serving the files.
+    
+    > [!NOTE]
+    > If this is the first time inover a month you have run a local server for an Office Add-in on your computer, you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+1. The first step in testing depends on the platform.
+
+   - To test in Office on Windows, open Excel. In a few moments, the **Show Task pane** button appears on the **Home** ribbon in the Contoso Add-in group. (If it doesn't appear on the ribbon, select the **Add-ins** button on the ribbon, and then select the **Excel Add-in + Agent** app in the flyout that opens.)
+   - To test in Office on the web, in a browser, navigate to `https://excel.cloud.microsoft.com/`, and then create a new workbook.
+ 
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. **Excel Add-in + Agent** should be in the list of agents. (You may need to select **See more** to ensure that all agents are listed.) If the agent isn't, try the following actions.
+
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl-r</kbd>.
+   - Wait a few minutes and reload Copilot.
+
+1. When the agent is listed, select it. The  **Excel Add-in + Agent** pane opens.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
1. When the agent is listed, select it. The **Excel Add-in + Agent** pane opens.
```
created_at: 2025-05-09T15:52:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
+     - uses: teamsApp/publishAppPackage
+       with:
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
+   projectId: da53b0a2-1561-415e-919a-5b870bcd2f49
+   ```
+
+1. Replace the value of `projectId` in the last line of content you pasted in the preceding step with a new randomly generated GUID.
+1. Open the **\env\.env.dev** file and add the following lines to the end of the file, right after the line "ADDIN_ENDPOINT=".
+
+   ```
+   TEAMS_APP_ID=
+   TEAMS_APP_TENANT_ID=
+   M365_TITLE_ID=
+   M365_APP_ID=
+   ```
+
+## Test the add-in and agent
+
+1. Close all Office applications.
+1. Open Microsoft 365 Agent Toolkit.
+1. In the **Lifecycle** pane, select **Provision**. Among other things, provisioning does the following:
+
+   - Set values for the four lines you added to the .env.dev file.
+   - Create a **/build** folder inside the **/appPackage** folder with the package zip file. The file contains the manifest and JSON files for the agent and plugin.
+
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost. Wait until you see a line in the server window that the app compiled successfully. This means the server is running and serving the files.
+    
+    > [!NOTE]
+    > If this is the first time inover a month you have run a local server for an Office Add-in on your computer, you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+1. The first step in testing depends on the platform.
+
+   - To test in Office on Windows, open Excel. In a few moments, the **Show Task pane** button appears on the **Home** ribbon in the Contoso Add-in group. (If it doesn't appear on the ribbon, select the **Add-ins** button on the ribbon, and then select the **Excel Add-in + Agent** app in the flyout that opens.)
+   - To test in Office on the web, in a browser, navigate to `https://excel.cloud.microsoft.com/`, and then create a new workbook.
+ 
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. **Excel Add-in + Agent** should be in the list of agents. (You may need to select **See more** to ensure that all agents are listed.) If the agent isn't, try the following actions.
+
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl-r</kbd>.
+   - Wait a few minutes and reload Copilot.
+
+1. When the agent is listed, select it. The  **Excel Add-in + Agent** pane opens.
+1. Select the **Change cell color** conversation starter, and then press the **Send** control in the conversation box at the bottom of the pane. Select **Confirm** in response to the confirmation prompt. The cell's color should change.
+
+   > [!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."
+
+1. Try entering other combinations of cell and color in the conversation box, such as "Set cell G5 to the color of the sky".
+
+## Make changes in the add-in or agent
+
+Live reloading and hot reloading for a combined add-in and agent aren't supported in the preview period. To make changes, first shut down the server and uninstall the extension with these steps.
+
+1. Shutting down the server depends on what window it is running in.
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
1. Shutting down the server depends on what window it's running in.
```
created_at: 2025-05-09T15:53:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
+   provision:
+   # Creates a Teams app
+     - uses: teamsApp/create
+       with:
+        # Teams app name
+        name: Contoso Agent ${{APP_NAME_SUFFIX}}
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        teamsAppId: TEAMS_APP_ID
+
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Extend your Teams app to Outlook and the Microsoft 365 app
+     - uses: teamsApp/extendToM365
+       with:
+        # Relative path to the build app package.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        titleId: M365_TITLE_ID
+        appId: M365_APP_ID
+
+   # Triggered when 'teamsapp publish' is executed
+   publish:
+   # Build Teams app package with latest env value
+     - uses: teamsApp/zipAppPackage
+       with:
+        # Path to manifest template
+        manifestPath: ./appPackage/manifest.json
+        outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+        outputFolder: ./appPackage/build
+   # Validate app package using validation rules
+     - uses: teamsApp/validateAppPackage
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Apply the Teams app manifest to an existing Teams app in
+   # Teams Developer Portal.
+   # Will use the app id in manifest file to determine which Teams app to update.
+     - uses: teamsApp/update
+       with:
+        # Relative path to this file. This is the path for built zip file.
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+   # Publish the app to
+   # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
+   # for review and approval
+     - uses: teamsApp/publishAppPackage
+       with:
+        appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
+       # Write the information of created resources into environment file for
+       # the specified environment variable(s).
+       writeToEnvironmentFile:
+        publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
+   projectId: da53b0a2-1561-415e-919a-5b870bcd2f49
+   ```
+
+1. Replace the value of `projectId` in the last line of content you pasted in the preceding step with a new randomly generated GUID.
+1. Open the **\env\.env.dev** file and add the following lines to the end of the file, right after the line "ADDIN_ENDPOINT=".
+
+   ```
+   TEAMS_APP_ID=
+   TEAMS_APP_TENANT_ID=
+   M365_TITLE_ID=
+   M365_APP_ID=
+   ```
+
+## Test the add-in and agent
+
+1. Close all Office applications.
+1. Open Microsoft 365 Agent Toolkit.
+1. In the **Lifecycle** pane, select **Provision**. Among other things, provisioning does the following:
+
+   - Set values for the four lines you added to the .env.dev file.
+   - Create a **/build** folder inside the **/appPackage** folder with the package zip file. The file contains the manifest and JSON files for the agent and plugin.
+
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm run dev-server` to start the server on localhost. Wait until you see a line in the server window that the app compiled successfully. This means the server is running and serving the files.
+    
+    > [!NOTE]
+    > If this is the first time inover a month you have run a local server for an Office Add-in on your computer, you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+1. The first step in testing depends on the platform.
+
+   - To test in Office on Windows, open Excel. In a few moments, the **Show Task pane** button appears on the **Home** ribbon in the Contoso Add-in group. (If it doesn't appear on the ribbon, select the **Add-ins** button on the ribbon, and then select the **Excel Add-in + Agent** app in the flyout that opens.)
+   - To test in Office on the web, in a browser, navigate to `https://excel.cloud.microsoft.com/`, and then create a new workbook.
+ 
+1. Open **Copilot** from the ribbon and select the hamburger control in the **Copilot** pane. **Excel Add-in + Agent** should be in the list of agents. (You may need to select **See more** to ensure that all agents are listed.) If the agent isn't, try the following actions.
+
+   - With Copilot open to the list of agents, click the cursor on the Copilot window and press <kbd>Ctrl-r</kbd>.
+   - Wait a few minutes and reload Copilot.
+
+1. When the agent is listed, select it. The  **Excel Add-in + Agent** pane opens.
+1. Select the **Change cell color** conversation starter, and then press the **Send** control in the conversation box at the bottom of the pane. Select **Confirm** in response to the confirmation prompt. The cell's color should change.
+
+   > [!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."
+
+1. Try entering other combinations of cell and color in the conversation box, such as "Set cell G5 to the color of the sky".
+
+## Make changes in the add-in or agent
+
+Live reloading and hot reloading for a combined add-in and agent aren't supported in the preview period. To make changes, first shut down the server and uninstall the extension with these steps.
+
+1. Shutting down the server depends on what window it is running in.
+
+   - If the web server is running in the same command prompt or Visual Studio Code **TERMINAL** where you ran `npm run dev-server`, give the window focus and press Ctrl-C. Choose "Y" in response to the prompt to end the process. 
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - If the web server is running in the same command prompt or Visual Studio Code **TERMINAL** where you ran `npm run dev-server`, give the window focus and press <kbd>Ctrl</kbd>+<kbd>C</kbd>. Choose "Y" in response to the prompt to end the process. 
```
created_at: 2025-05-09T15:53:47Z
author_association: CONTRIBUTOR
diff_hunk: @@ -265,6 +265,14 @@ items:
             href: design/custom-tab-placement.md
         - name: Content add-ins
           href: design/content-add-ins.md
+        - name: Copilot agents
+          items:
+          - name: Combine Copilot Agents with Office Add-ins
+            href: design/agent-and-add-in-overview.md
+          - name: Build your first add-in as a Copilot skill
+            href: quickstarts/agent-and-add-in-quickstart.md
+          - name: Add a Copilot agent to an add-in
+            href: develop/agent-and-add-in.md
path: docs/toc.yml
user: login: ElizabethSamuel-MSFT
body: You can set the displayName to preview so users who use the search box for preview items will find them

```suggestion
          - name: Combine Copilot Agents with Office Add-ins
            href: design/agent-and-add-in-overview.md
            displayName: preview
          - name: Build your first add-in as a Copilot skill
            href: quickstarts/agent-and-add-in-quickstart.md
            displayName: preview
          - name: Add a Copilot agent to an add-in
            href: develop/agent-and-add-in.md
            displayName: preview
```
created_at: 2025-05-09T15:56:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
## Start with an Office Add-in
```
created_at: 2025-05-09T15:57:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears. Select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps:
+
+1. In the manifest file, make the following changes:
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "ms-office-addin"
+                },
+                "run_for_functions": ["fillcolor"]
+            }
+        ]
+    }
+   ```
+
+1. Open the **\src\commands\commands.ts** file and add the following code the end of it.
+
+   ```javascript
+   async function fillcolor(cell, color) {
+       await Excel.run(async (context) => {
+            context.workbook.worksheets
+                .getActiveWorksheet()
+                .getRange(cell).format.fill.color = color;
+            await context.sync();
+        })
+   }
+
+   Office.onReady((info) => {
+        Office.actions.associate("fillcolor", async (message) => {
+            const {Cell: cell, Color: color} = JSON.parse(message);
+            await fillcolor(cell, color);
+            return "Cell color changed.";
+        });
+   });
+   ```
+
+## Update project configuration files for a combined add-in and Copilot agent
+
+1. Open the teamsapp.yaml file in the root of project and replace its contents with the following.
+
+   ```yaml
+   # yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
+   # Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
+   # Visit https://aka.ms/teamsfx-actions for details on actions
+   version: v1.7
+
+   environmentFolderPath: ./env
+
+   # Triggered when 'teamsapp provision' is executed
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: Rick-Kirkham
body: This file is tool-created content. I think it should match here.
created_at: 2025-05-09T16:58:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,341 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plug-in-configuration)
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
- [Create the agent and API plug-in configuration](#create-the-agent-and-api-plug-in-configuration)
```
created_at: 2025-05-09T17:27:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,341 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plug-in-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plug-ins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The latter have five minutes to complete or Office shuts down the JavaScript runtime. But Copilot-invoked functions have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+    // Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+      context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+      await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following:
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plug-in configuration
+
+1. Create a file in the same folder where your manifest is and give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
+                            "default" : "#30d5c8"
+                        }
+                    },
+                    "required": ["Cell", "Color"]
+                },
+                "returns": {
+                    "type": "string",
+                    "description": "A string indicating the result of the action."
+                },
+                "states": {
+                    "reasoning": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
+                    },
+                    "responding": {
+                        "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
+                        "instructions": "If there is no error present, tell the user the cell location and color that was set."
+                    }
+                }
+            }
+        ],
+        "runtimes": [
+            {
+                "type": "LocalPlugin",
+                "spec": {
+                    "local_endpoint": "Microsoft.Office.Addin"
+                },
+                "run_for_functions": ["FillColor"]
+            }
+        ]
+    }
+   ```
+
+1. *With some exceptions noted later, replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [API plugin manifest schema 2.2 for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/api-plugin-manifest-2.2).
+
+   As you work, keep the following points in mind.
+
+   - Do *not* change the `"namespace"`, `"runtimes.type"`, or `"runtimes.spec.local_endpoint"` values.
+   - The `"functions.name"` must be an exact match for both of the following:
+
+      - An `"extensions.runtimes.actions.id"` property in the manifest (for an action of type "executeDataFunction").
+      - The first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+
+   - The `"runtimes.run_for_functions"` array must include either the same string as `"functions.name"` or a wildcard string that matches it.
+   - The `"reasoning.description"` and `"reasoning.instructions"` refer to a JavaScript function, not a REST API.
+   - The `"runtimes.spec.local_endpoint"` property is new and isn't yet in the main reference documentation for the API plugins schema. See below for more about it. It tells the Copilot agent to look for functions in an Office Add-in instead of at a REST service URL.
+
+### Create the app package
+
+> [!IMPORTANT]
+> To test the agent, as described later in this article in [Test the agent](#test-the-agent), the domain segment of any absolute URLs in the manifest must be a localhost domain; for example, `localhost:3000`. You can change these segments to a production domain later.
+
+Using any zip utility, create a zip file that contains the following files.
+
+- The manifest
+- The icon files referenced in the manifest's [`"icons.color"`](/microsoft-365/extensibility/schema/root-icons#color) and [`"icons.outline"`](/microsoft-365/extensibility/schema/root-icons#outline)
+- The two files you created in [Create the agent and API plugin configuration](#create-the-agent-and-api-plug-in-configuration)
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
- The two files you created in [Create the agent and API plug-in configuration](#create-the-agent-and-api-plug-in-configuration)
```
created_at: 2025-05-09T17:28:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,341 @@
+---
+title: Add a Copilot agent to an add-in
+description: Learn how to add a Copilot agent to an add-in.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: medium
+---
+
+# Add a Copilot agent to an add-in
+
+Adding a Copilot agent to an Office Add-in provides two benefits:
+
+- Copilot becomes a natural language interface for the add-in's functionality.
+- The agent can pass parameters to the JavaScript it invokes, which isn't possible when a [function command](../design/add-in-commands.md#types-of-add-in-commands) is invoked from a button or menu item.
+
+> [!NOTE]
+> This article assumes that you're familiar with the overview [Combine Copilot Agents with Office Add-ins](../design/agent-and-add-in-overview.md) and the Copilot documentation that it refers to. We also recommend that you complete the quick start [Build your first add-in as a Copilot skill](../quickstarts/agent-and-add-in-quickstart.md).
+
+> [!IMPORTANT]
+> This feature requires the [unified manifest for Microsoft 365](unified-manifest-overview.md). If your add-in uses the add-in only manifest, you must first [convert it to use the unified manifest](convert-xml-to-json-manifest.md) before you can add a Copilot agent to it. Before you continue with this article, you should know how to package the manifest and other files into an app package zip file and sideload it to an Office application for testing.
+
+## Major tasks
+
+The following are the main tasks for adding a Copilot agent to your add-in. Details are in the subsections.
+
+- [Create the functions for the agent's actions](#create-the-functions-for-the-agents-actions) that will implement the Copilot agent's actions.
+- [Update the manifest](#update-the-manifest)
+- [Create the agent and API plugin configuration](#create-the-agent-and-api-plug-in-configuration)
+- [Create the app package](#create-the-app-package)
+- [Test the agent](#test-the-agent)
+- [Make changes in the app](#make-changes-in-the-app)
+
+### Create the functions for the agent's actions
+
+If your add-in includes one or more [function commands](../design/add-in-commands.md#types-of-add-in-commands), then your project already has a JavaScript or TypeScript file that defines the functions for these commands (usually called **commands.js** or **commands.ts**) and a UI-less HTML file (usually called **commands.html**) that has a `<script>` tag to load the function file. We recommend that you use this same function file to define the functions for your agent's actions. Skip to the section [Update the function file](#update-the-function-file).
+
+#### Create the source files
+
+If your project doesn't already have such files, then create them with the following steps. The folder and file structure and names in these steps aren't mandatory, but we recommend them to minimize incompatibilities with add-in development tooling and configuration for bundlers and transpilers where applicable.
+
+1. Ensure that there's a folder **\src** off the root of the project, and that it has a child folder named **\commands**.
+1. Create a **commands.js** (or .ts) file in the **\commands** folder. You add content to it in a later step.
+1. Create a **commands.html** file in the **\commands** folder with the following content. Note the following about this markup.
+
+   - The `<body>` element is empty because the file has no UI. Its only purpose is to load JavaScript files.
+   - The Office JavaScript Library and the **commands.js** file that you created in the preceding step is explicitly loaded.
+
+       > [!NOTE]
+       > It's common in Office Add-in development to use tools like [webpack](https://webpack.js.org/) and its plug-ins to automatically inject `<script>` tags into HTML files at build time. If you use such a tool, you shouldn't include any `<script>` tags in your source file that are going to be inserted by the tool.
+
+   ```html
+   <!DOCTYPE html>
+   <html>
+       <head>
+           <meta charset="UTF-8" />
+           <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+
+           <!-- Office JavaScript Library -->
+           <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+           <!-- Function command file -->
+           <script src="commands.js" type="text/javascript"></script>
+       </head>
+       <body>
+       </body>
+   </html>
+   ```
+
+#### Update the function file
+
+Define the functions for your agent's actions with the following steps. These assume the most common folder and file structure and names.
+
+Open the function file (usually, the **\src\commands\commands.js** (or .ts)) and add the functions that implement the agent's actions. Keep the following points in mind as you work.
+
+- Like all code that calls APIs in the Office JavaScript Library, the file must [initialize the library](initialize-add-in.md), usually by calling `Office.onReady`.
+- Functions that are invoked by agents take a `message` parameter that specifies the values that Office will use when it calls functions from the Office JavaScript Library. This object can be parsed with the `JSON.parse` method. The values of the object are specified by users in natural language.
+- Unlike the functions that are invoked with add-in commands, these functions don't have an `Office.AddinCommands.Event` parameter, and they don't call the `Office.AddinCommands.Event.completed` method. Instead, functions that are invoked by agents return a result object from the JavaScript runtime back to the Copilot runtime.
+- Functions invoked from Copilot have less time to complete than functions invoked from a function command. The latter have five minutes to complete or Office shuts down the JavaScript runtime. But Copilot-invoked functions have only two minutes to return a result or the runtime is shut down.
+- For each function, there must be a call of [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) to tell Office which function in the file should be run when the agent action is invoked. The `associate` function maps the function name to an action ID that you configure in the manifest in a later step. If you define multiple functions in the same file, your code must call `associate` for each one.
+
+The following is an example.
+
+```javascript
+Office.onReady(function() {
+    // Add any initialization code here.
+});
+
+async function fillColorFromUserData(message) {
+    const {Cell: cell, Color: color} = JSON.parse(message);
+    await Excel.run(async (context) => {
+      context.workbook.worksheets
+        .getActiveWorksheet()
+        .getRange(cell).format.fill.color = color;
+      await context.sync();
+    });
+    return "Cell color changed.";
+}
+
+Office.actions.associate("FillColor", fillColorFromUserData);
+```
+
+### Update the manifest
+
+There are three major parts to configuring the manifest for the Copilot agent as described in the following subsections.
+
+#### Use the preview manifest schema
+
+Ensure that the manifest references the preview version of the manifest schema with the following steps.
+
+1. At the top of the manifest, ensure that the [`"$schema"`](/microsoft-365/extensibility/schema/root#schema-4) property is the following:
+
+   ```json
+   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+   ```
+
+1. Ensure that the [`"manifestVersion"`](/microsoft-365/extensibility/schema/root#manifestversion) property is set to "devPreview".
+
+#### Configure the runtime
+
+1. In the [`"extensions.runtimes"`](/microsoft-365/extensibility/schema/extension-runtimes-array) array, ensure that there's a runtime object that is oriented to running UI-less JavaScript functions. It's critical that the object have a [`"code.page"`](/microsoft-365/extensibility/schema/extension-runtime-code#page) property that specifies the absolute URL to the UI-less HTML file that you created (or edited) earlier in [Update the function file](#update-the-function-file).
+1. In the [`"actions"`](/microsoft-365/extensibility/schema/extension-runtimes-actions-item) array of that same runtime object, add an object whose `"type"` property is set to "executeDataFunction" and whose `"id"` property is an exact match for the first parameter of the call to `Office.actions.associate` in a function that you created in [Update the function file](#update-the-function-file).
+1. Repeat the preceding step for each function you created to implement an agent action.
+
+The runtime object should look similar to the following. There may be other properties of the runtime object, other runtime objects in the `"runtimes"` array, and other action objects in the `"actions"` array.
+
+```json
+"runtimes": [
+    {
+        "id": "CommandsRuntime",
+        "type": "general",
+        "code": {
+            "page": "https://localhost:3000/commands.html"
+        },
+        "lifetime": "short",
+        "actions": [
+            {
+                "id": "FillColor",
+                "type": "executeDataFunction",
+            }
+        ]
+    }
+]
+```
+
+#### Declare the agent
+
+1. If there isn't one already, add a ["copilotAgents"](/microsoft-365/extensibility/schema/root-copilot-agents) object to the root of the manifest and ensure that it has a child ["declarativeAgents"](/microsoft-365/extensibility/schema/declarative-agent-ref) array.
+1. Add an object to the `"declarativeAgents"` array and specify a unique and descriptive [`"id"`](/microsoft-365/extensibility/schema/declarative-agent-ref#id) for it.
+1. Assign the object's [`"file"`](/microsoft-365/extensibility/schema/declarative-agent-ref#file) property the relative URL of the declarative agent configuration file. You create that file in a later step.
+
+   The following is an example.
+
+   ```json
+   "copilotAgents": {
+       "declarativeAgents": [
+           {
+               "id": "ContosoCopilotAgent",
+               "file": "declarativeAgent.json"
+           }
+       ]
+   },
+   ```
+
+> [!TIP]
+> To maximize compatibility with Microsoft tools for add-in development, we recommend that you create a folder named **appPackage** in the root of the project and move the manifest into it.
+
+### Create the agent and API plug-in configuration
+
+1. Create a file in the same folder where your manifest is and give it the name used in the `"copilot.declarativeAgents.file"` property, such as **declarativeAgent.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Office-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. *Replace the property values with new values that are appropriate for your add-in.* For more information about these properties, see [Declarative agent manifest object](/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.2#declarative-agent-manifest-object).
+
+   > [!NOTE]
+   > You create the file that you specify in the "actions.file" property in the next step. In the example above, this is the file **Office-API-local-plugin.json**.
+
+1. Create another file in the folder with your manifest and give it the name you assigned to the "actions.file" property in the preceding step"; for example, **Office-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "FillColor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
path: docs/develop/agent-and-add-in.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
                            "description": "A color in hex format, e.g., #30d5c8",
```
created_at: 2025-05-09T17:50:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,334 @@
+---
+title: Build your first add-in as a Copilot skill
+description: Learn how to build a simple Copilot agent that has an Excel add-in as a skill.
+ms.date: 05/19/2025
+ms.topic: how-to
+ms.service: microsoft-365
+ms.localizationpriority: high
+---
+
+# Build your first add-in as a Copilot skill
+
+In this article, you'll walk through the process of building a simple Excel Copilot agent that can perform actions on the content of an Excel workbook. The app also includes an Excel 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 the following actions.
+    - Read [Declarative agents for Microsoft 365 Copilot overview](/microsoft-365-copilot/extensibility/overview-declarative-agent).
+    - Complete the tutorial that begins at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+
+## Software prerequisites
+
+- All the prerequisites listed at [Create declarative agents using Microsoft 365 Agent Toolkit](/microsoft-365-copilot/extensibility/build-declarative-agents).
+- The [Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md). 
+
+## Start with an Office Add-in
+
+Create a basic Excel add-in with the following steps. 
+
+1. Create an Office Add-in in Microsoft 365 Agent Toolkit by following the instructions in [Create Office Add-in projects with Microsoft 365 Agent Toolkit](../develop/teams-toolkit-overview.md#create-an-office-add-in-project). *Stop after the project is created. Don't carry out the steps in the sideloading section.*
+
+   > [!NOTE]
+   > When prompted to name the add-in, use "Excel Add-in + Agent".
+
+1. The project opens in a new Visual Studio Code window. Close the original Visual Studio Code window.
+1. In a command prompt or Visual Studio Code **TERMINAL** in the root of the project, run `npm install`.
+
+### Sideload and test the add-in
+
+1. Test that the add-in works by carrying out the following steps.
+
+   1. Select **View | Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select **Excel Desktop (Edge Chromium)**.
+   1. Press <kbd>F5</kbd>. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Excel opens.
+
+   > [!NOTE]
+   > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
+
+   1. Select the **Add-ins** button on the **Home** ribbon, and then in the flyout that opens, select your add-in.
+   1. A **Contoso Add-in** group with a **Show Taskpane** button will appear on the **Home** ribbon. Use the button to open the add-in's task pane.
+
+   > [!NOTE]
+   > If a **WebView Stop On Load** prompt appears, select **OK**.
+
+   1. When the task pane has opened, select **Run**. A cell in the worksheet changes to yellow.
+   1. Stop debugging and uninstall the add-in by shutting down Excel and running `npm run stop` in a command prompt or Visual Studio Code **TERMINAL** in the root of the project.
+
+      > [!IMPORTANT]
+      > Stopping debugging in the UI of Visual Studio Code doesn't work currently due to a bug. Also, neither closing Excel nor manually closing the dev server window reliably shut down the server or cause Excel to unacquire the add-in. You **must** run `npm run stop`.
+
+## Add a Copilot declarative agent
+
+Add the agent with the following steps.
+
+1. In the manifest file, make the following changes.
+
+   1. Add the following object to the root. By convention, it's put just below the "validDomains" property. You create the "declarativeAgent.json" file in a later step.
+
+      ```json
+      "copilotAgents": {
+        "declarativeAgents": [
+          {
+            "id": "ContosoCopilotAgent",
+            "file": "declarativeAgent.json"
+          }
+        ]
+      },
+      ```
+
+    1. There are multiple objects in the `"extensions.runtimes"` array. Find the one whose `"id"` is "CommandRuntime" and copy it as an additional runtime object in the array.
+    1. Make the following changes to this additional runtime object. 
+    
+       1. Change the `"id"` from "CommandRuntime" to "CopilotAgentActionsRuntime".
+       1. Change its `"actions.id"` property to "fillcolor". This is the ID of a function that you add in a later step.
+       1. Change the `"actions.type"` property to "executeDataFunction".
+
+1. Create a file in the **appPackage** folder named **declarativeAgent.json**.
+1. Paste the following content into the file. (You create the **Excel-API-local-plugin.json** file that is mentioned in this JSON in a later step.)
+
+   ```json
+   {
+        "name": "Excel Add-in + Agent",
+        "description": "Agent for working with Excel cells.",
+        "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
+        "conversation_starters": [
+            {
+                "title": "Change cell color",
+                "text": "I want to change the color of cell B2 to orange"
+            }
+        ],
+        "actions": [
+            {
+                "id": "localExcelPlugin",
+                "file": "Excel-API-local-plugin.json"
+            }
+        ]
+    }
+   ```
+
+1. Create a file in the **appPackage** folder named **Excel-API-local-plugin.json**.
+1. Paste the following content into the file.
+
+   ```json
+   {
+        "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
+        "schema_version": "v2.3",
+        "name_for_human": "Excel Add-in + Agent",
+        "description_for_human": "Add-in Actions in Agents",
+        "namespace": "addinfunction",
+        "functions": [
+            {
+                "name": "fillcolor",
+                "description": "fillcolor changes a single cell location to a specific color.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "Cell": {
+                            "type": "string",
+                            "description": "A cell location in the format of A1, B2, etc.",
+                            "default" : "B2"
+                        },
+                        "Color": {
+                            "type": "string",
+                            "description": "A color in hex format, e.g. #30d5c8",
path: docs/quickstarts/agent-and-add-in-quickstart.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
                            "description": "A color in hex format, e.g., #30d5c8",
```
created_at: 2025-05-09T17:50:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -25,17 +25,17 @@ You can also think of an Office Add-in as a skill in a Copilot agent. Because Of
 
 The following are some selected ways in which adding a Copilot agent enhances the value of an add-in to users.
 
-- **Learning how to use the add-in**: When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be asked to produce a first draft list of questions and insert them into a Word document.
+- **Learning how to use the add-in**: When a user needs to perform multiple steps or tasks with the add-in to achieve a goal, the chat interface of Copilot can ease the process of getting started with the add-in. For example, consider a legal firm that needs to have a list of questions that must be answered about each lease that it prepares. Creating this list of questions can be time-consuming and labor-intensive. But a Copilot agent that uses the Office JavaScript Library can be prompted to produce a first draft list of questions and insert them into a Word document.
 
 - **Content analysis**: An agent can be used to analyze the content of a document or spreadsheet and take action depending on what it finds. The following are examples.
 
-   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply instructs the agent to "Fill in the answers you know to the questions."
+   - An agent analyzes a Request for Proposal and then fetches the answers to questions in the RFP from a backend system. The user simply prompts the agent to "Fill in the answers you know to the questions."
    - An agent analyzes a document, or a table in a spreadsheet, for content that implies certain actions must be taken, either in the document itself or elsewhere in the customer's business systems. The user might say "Review the document for any items I missed on the audit list."
 
-- **Trusted insertion of data**: If you ask a typical AI engine a question, it will combine information it finds and compose an answer; a process that can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
+- **Trusted insertion of data**: If you prompt a typical AI engine with a question, it will combine information it finds and compose an answer; a process that can introduce inaccuracies. But a Copilot agent based on an add-in can insert data *unchanged* from a trusted source. Some examples:
 
-   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user asks the agent: "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
-   - Consider an add-in that manages the inventory of a digital assets. In the Copilot agent chat, a user requests: "Insert a table of our color photos with the name of each, the number of times it was downloaded, and it's size in megabytes, sorted in order from most downloaded." The add-in then fetches this data, unchanged, from the system of record and inserts the table into an Excel spreadsheet.
+   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user promnpts the agent: "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
path: docs/design/agent-and-add-in-overview.md
user: login: ElizabethSamuel-MSFT
body: ```suggestion
   - Consider an add-in that enables the insertion of legal research into Word where it can then be edited. A user prompts the agent: "In what circumstances can a lease of residential space in Indiana be broken unilaterally by the lessor?" The add-in then fetches content, unchanged, from precedents and statutes.
```
created_at: 2025-05-09T20:24:56Z
author_association: CONTRIBUTOR

PR comments:
user: login: learn-build-service-prod[bot]
created_at: 2025-05-03T20:37:47Z
body: Learn Build status updates of commit _[259481a](https://github.com/OfficeDev/office-js-docs-pr/commits/259481a675fd06b2f7369dc0edc82a48e652f73a)_: 

### :bulb: Validation status: suggestions


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :bulb:Suggestion | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) | [Details](#user-content-523e5c92a45c015bf0372bd78fa68190-6ce608b4)
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :bulb:Suggestion | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) | [Details](#user-content-cd22c7eeffea0bf39e04760674542953-6ce608b4)
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

<a id="523e5c92a45c015bf0372bd78fa68190-6ce608b4"></a>
### [docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md)
 - **Line 72, Column 226**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /javascript/api/office/office.actions?view=common-js-preview#office-office-actions-associate-member(1)`````
 - **Line 73, Column 7**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/extension-runtimes-actions-item?view=m365-app-prev&branch=main&tabs=syntax#id`````
 - **Line 74, Column 7**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/extension-runtimes-actions-item?view=m365-app-prev&branch=main&tabs=syntax#type`````
 - **Line 113, Column 57**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/?view=m365-app-prev`````
 - **Line 238, Column 198**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/extension-runtime-code?view=m365-app-prev&branch=main&tabs=syntax#page`````

<a id="cd22c7eeffea0bf39e04760674542953-6ce608b4"></a>
### [docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md)
 - **Line 110, Column 48**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/root?view=m365-app-prev&branch=main&tabs=syntax#schema-4`````
 - **Line 116, Column 20**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/root?view=m365-app-prev&branch=main&tabs=syntax#manifestversion`````
 - **Line 120, Column 11**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/extension-runtimes-array?view=m365-app-prev`````
 - **Line 120, Column 257**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/extension-runtime-code?view=m365-app-prev&branch=main&tabs=syntax#page`````
 - **Line 147, Column 38**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/root-copilot-agents?view=m365-app-prev`````
 - **Line 147, Column 198**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/declarative-agent-ref?view=m365-app-prev`````
 - **Line 148, Column 90**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/declarative-agent-ref?view=m365-app-prev#id`````
 - **Line 149, Column 24**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/declarative-agent-ref?view=m365-app-prev#file`````
 - **Line 278, Column 47**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/root-icons?view=m365-app-prev&branch=main&tabs=syntax#color`````
 - **Line 278, Column 166**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/root-icons?view=m365-app-prev&branch=main&tabs=syntax#outline`````
 - **Line 280, Column 31**: **[Suggestion: preserve-view-not-set - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/preserve-view-not-set)]** `````You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL.  Otherwise, remove the view parameter. URL: /microsoft-365/extensibility/schema/root-localization-info?view=m365-app-prev&branch=main&tabs=syntax#additionallanguages`````

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505032036190211-5156/BuildReport?accessString=9d606381ff51a2995e8e806f73792a6251af3be759f9f0a53d72c95808148b71).

**Note:** Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these [instructions](https://learn.microsoft.com/en-us/help/platform/faq?tabs=pr-validation-error-solution%2Cpr-merge-conflict-error-solution#build--publish) to resolve them.

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-03T20:56:13Z
body: Learn Build status updates of commit _[b496225](https://github.com/OfficeDev/office-js-docs-pr/commits/b496225b40ec8ab072c7265a0b918628c66ce1bc)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505032054473597-5156/BuildReport?accessString=c386dec87aebc6886dbda1d943e6c2ca3682a3f57e9d717e63800cc4c073cf68).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-05T18:48:34Z
body: Learn Build status updates of commit _[e189213](https://github.com/OfficeDev/office-js-docs-pr/commits/e18921350e2ea7d8b04b8a89022e488ee568799d)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505051845534431-5156/BuildReport?accessString=b60deccac2b9e618b457fd45b49bb92a8d1106d92e47f8e8360fd57b79bb6eec).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-05T20:27:16Z
body: Learn Build status updates of commit _[71695a7](https://github.com/OfficeDev/office-js-docs-pr/commits/71695a7c6653bf0e420a6fe587da889173564bdf)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505052025416912-5156/BuildReport?accessString=c1262af3aaefac848168479b4f070c2a76d8faea8d096994bc30211e3f27d03d).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-07T21:19:24Z
body: Learn Build status updates of commit _[1f5d1e1](https://github.com/OfficeDev/office-js-docs-pr/commits/1f5d1e14d31c52e7e8bf33b1c6d85fe8e7ca0f28)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505072118171324-5156/BuildReport?accessString=bf029ec82c82e691124e5caf3c0ea17e1cafa0ef8bcb48bbb37b8a8b53f97dd1).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-08T18:52:55Z
body: Learn Build status updates of commit _[b92a4ac](https://github.com/OfficeDev/office-js-docs-pr/commits/b92a4ac3caaee5825b3a92da053284ba0b678e0a)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505081851104802-5156/BuildReport?accessString=edc9c891613ea917a435345de28fb205c000e0509c446b6295fff173c5dd02e0).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-09T17:03:46Z
body: Learn Build status updates of commit _[f24a48b](https://github.com/OfficeDev/office-js-docs-pr/commits/f24a48bafef62abe0771e2a636b17cc59aa403fd)_: 

### :warning: Validation status: warnings


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :warning:Warning | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) | [Details](#user-content-cd22c7eeffea0bf39e04760674542953-b2cf1204)
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

<a id="cd22c7eeffea0bf39e04760674542953-b2cf1204"></a>
### [docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md)
 - **Line 29, Column 3**: **[Warning: bookmark-not-found - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/bookmark-not-found)]** `````Cannot find bookmark '#create-the-agent-and-api-plugin-configuration' in 'develop/agent-and-add-in.md', did you mean '#create-the-agent-and-api-plug-in-configuration'?`````
 - **Line 278, Column 32**: **[Warning: bookmark-not-found - [See documentation](https://learn.microsoft.com/help/platform/validation-ref/bookmark-not-found)]** `````Cannot find bookmark '#create-the-agent-and-api-plugin-configuration' in 'develop/agent-and-add-in.md', did you mean '#create-the-agent-and-api-plug-in-configuration'?`````

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505091701236660-5156/BuildReport?accessString=445f9bd29cea936c7a9277626e520793e3bf6215fa814d381a786bfa9f005642).


**Note:** Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these [instructions](https://learn.microsoft.com/en-us/help/platform/faq?tabs=pr-validation-error-solution%2Cpr-merge-conflict-error-solution#build--publish) to resolve them.

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-09T17:19:56Z
body: Learn Build status updates of commit _[691d266](https://github.com/OfficeDev/office-js-docs-pr/commits/691d266058b26f6198bc9de79bdffbf7d5549bee)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505091717379774-5156/BuildReport?accessString=716b93ff3309ee6fda120750458ad6cddca37d6594d71a63eea06263601842bb).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-09T18:16:32Z
body: Learn Build status updates of commit _[2358fd0](https://github.com/OfficeDev/office-js-docs-pr/commits/2358fd0a5c71cd1992d642198ac6f3a0946d2f2d)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505091814520457-5156/BuildReport?accessString=34450930203959d9a90d2c2b80966c2901e75770b3def633c81e4103e6255da3).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-09T18:57:39Z
body: Learn Build status updates of commit _[fa91fc2](https://github.com/OfficeDev/office-js-docs-pr/commits/fa91fc2e41dab85ac94bef59e2b7cfe6e95431d2)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505091856331102-5156/BuildReport?accessString=6b343fbe1c78780b6e3b9e7ca40417425262e7398bdff282bba9536139aec6d4).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-09T20:24:43Z
body: Learn Build status updates of commit _[05e805a](https://github.com/OfficeDev/office-js-docs-pr/commits/05e805a30f00f0d30e79ac142c8d203a0c72aa8f)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505092023137551-5156/BuildReport?accessString=0513273fe8cb8a725425e50ad636624dd5e764cdde2b871af1589026ea5e5656).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-09T21:04:22Z
body: Learn Build status updates of commit _[f21e019](https://github.com/OfficeDev/office-js-docs-pr/commits/f21e019c8478347736f3c1c9cd9e9a88814c952b)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505092102312121-5156/BuildReport?accessString=12f7b7271740546741394ed2d3f2f27d55c19bbdb9859584f48b3c774ebe88e6).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-12T20:48:11Z
body: Learn Build status updates of commit _[ca532c3](https://github.com/OfficeDev/office-js-docs-pr/commits/ca532c31f6ec6d342ffcb58ec3874deb80a6b6a2)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/images/copilot-agent-list.png](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/images/copilot-agent-list.png) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505122046420243-5156/BuildReport?accessString=32271f6fe832476c89b33d85b49732d9da580b04006af371948cc95a72b860a8).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-13T21:07:00Z
body: Learn Build status updates of commit _[8eafdd5](https://github.com/OfficeDev/office-js-docs-pr/commits/8eafdd54d14dce606ad3a5f4c5c6167d4b20d3a3)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/images/copilot-agent-list.png](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/images/copilot-agent-list.png) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505132105046800-5156/BuildReport?accessString=1d0f2b07e9e0bc908b7a28125b2713b18ca84d04c243a5e2da07b8567d09bade).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR
user: login: learn-build-service-prod[bot]
created_at: 2025-05-15T00:19:13Z
body: Learn Build status updates of commit _[7474423](https://github.com/OfficeDev/office-js-docs-pr/commits/7474423dcc31548e86ba151e3b07d35994a0902d)_: 

### :white_check_mark: Validation status: passed


File | Status | Preview URL | Details
---- | ------ | ----------- | -------
[docs/design/add-in-commands.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/add-in-commands.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |
[docs/design/agent-and-add-in-overview.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/design/agent-and-add-in-overview.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/agent-and-add-in-overview?branch=pr-en-us-5156) |
[docs/develop/agent-and-add-in.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/develop/agent-and-add-in.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/images/copilot-agent-list.png](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/images/copilot-agent-list.png) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/develop/agent-and-add-in?branch=pr-en-us-5156) |
[docs/quickstarts/agent-and-add-in-quickstart.md](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/quickstarts/agent-and-add-in-quickstart.md) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/agent-and-add-in-quickstart?branch=pr-en-us-5156) |
[docs/toc.yml](https://github.com/OfficeDev/office-js-docs-pr/blob/agent-addin/docs/toc.yml) | :white_check_mark:Succeeded | [View](https://review.learn.microsoft.com/en-us/office/dev/add-ins/design/add-in-commands?branch=pr-en-us-5156) |

For more details, please refer to the [build report](https://buildapi.docs.microsoft.com/Output/PullRequest/57856ef7-e8cf-54ca-0d12-df5f42d1e8bb/202505150018155626-5156/BuildReport?accessString=1b404c79998854707650b9c6f5fb5d5a51f6c7d993d6907e584817685cb9a286).

For any questions, please:<ul><li>Try searching the learn.microsoft.com <a href="https://learn.microsoft.com/en-us/help/">contributor guides</a></li><li>Post your question in the <a href="https://teams.microsoft.com/l/channel/19%3a7ecffca1166a4a3986fed528cf0870ee%40thread.skype/General?groupId=de9ddba4-2574-4830-87ed-41668c07a1ca&amp;tenantId=72f98bf-86f1-41af-91ab-2d7cd011db47">Learn support channel</a></li></ul>

author_association: CONTRIBUTOR