From 1f8996ec6faed9386d6f1f5e5802942d11393db7 Mon Sep 17 00:00:00 2001 From: ReidCarlberg Date: Tue, 22 Apr 2025 14:42:53 -0600 Subject: [PATCH 1/5] Update spe-da-adv.md The -OwningApplicationId is a UUID format, and in the example it was just 8 random characters, which wasn't clear. --- docs/embedded/development/declarative-agent/spe-da-adv.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md index 2a04298bd7..4453943486 100644 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -52,7 +52,7 @@ Connect-SPOService "https://-admin.sharepoint.com" # Login with your admin account. ... -Set-SPOApplication -OwningApplicationId 423poi45 -CopilotEmbeddedChatHosts "http://localhost:3000 https://contoso.sharepoint.com https://fabrikam.com" +Set-SPOApplication -OwningApplicationId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CopilotEmbeddedChatHosts "http://localhost:3000 https://contoso.sharepoint.com https://fabrikam.com" # This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly. ... From 8c98aa9ef8f5918af0d559be5456a020be6bf977 Mon Sep 17 00:00:00 2001 From: ReidCarlberg Date: Tue, 22 Apr 2025 21:40:17 -0600 Subject: [PATCH 2/5] Update spe-da-adv.md Syntax for an array of hosts was wrong. --- docs/embedded/development/declarative-agent/spe-da-adv.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md index 2a04298bd7..459f9a09bb 100644 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -52,7 +52,7 @@ Connect-SPOService "https://-admin.sharepoint.com" # Login with your admin account. ... -Set-SPOApplication -OwningApplicationId 423poi45 -CopilotEmbeddedChatHosts "http://localhost:3000 https://contoso.sharepoint.com https://fabrikam.com" +Set-SPOApplication -OwningApplicationId 423poi45 -CopilotEmbeddedChatHosts @("http://localhost:3000", "https://contoso.sharepoint.com", "https://fabrikam.com") # This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly. ... From d7346f6a1508f895a5df255341218cb6e041b851 Mon Sep 17 00:00:00 2001 From: Andrew Connell Date: Thu, 15 May 2025 10:44:56 -0400 Subject: [PATCH 3/5] update timestamp, fix grammatical issues & typos --- .../declarative-agent/spe-da-adv.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md index 8364cdc725..0ac9901ee4 100644 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -1,11 +1,11 @@ --- title: SharePoint Embedded copilot Advanced Topics description: Learn how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses in SharePoint Embedded copilot. -ms.date: 3/03/2025 +ms.date: 05/15/2025 ms.localizationpriority: high --- -# SharePoint Embedded copilot Advanced Topics Overview +# SharePoint Embedded Copilot Advanced Topics Overview This advanced guide covers how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses. We’ll explore how these concepts work together to ensure your copilot retrieves relevant information from your data and returns grounded answers. @@ -33,12 +33,12 @@ Discoverability can also be disabled using the Visual Studio Code SharePoint Emb The Content-Security-Policy (CSP) for embedded chat hosts ensures that only specified hosts can load the chat component. This helps in securing the application by restricting which domains can embed the chat component. -It is intended to allow consuming tenant SPE admins to set an allowlist of hosts that they will allow to embed the SPE copilot in an iFrame. Specifically, the value they set here will be used in a Content-Security-Policy header as a frame-ancestors value. +It is intended to allow consuming tenant SPE admins to set an allowlist of hosts that they will allow to embed the SPE copilot in an `iframe`. Specifically, the value they set here will be used in a Content-Security-Policy header as a frame-ancestors value. > [!NOTE] > > If this configuration is not set, the [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) will default be set to -> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): ‘none’ which means no one can embed the copilot. +> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): ‘none’, which means no one can embed the copilot. Below are example commands to use the [Connect to SharePoint Online using PowerShell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online) commands: @@ -71,7 +71,7 @@ CopilotEmbeddedChatHosts : {http://localhost:*} ##### Authentication and 3P Cookies -The iFrame used by SharePoint Embedded copilot attempts to authenticate using third-party cookies. If third-party cookies are disabled in the user's browser, the iFrame will not be able to authenticate automatically. In such cases, a popup will be displayed prompting the end user to log in manually. This ensures that the authentication process can still be completed even when third-party cookies are not available. +The `iframe` used by SharePoint Embedded copilot attempts to authenticate using third-party cookies. If third-party cookies are disabled in the user's browser, the `iframe` will not be able to authenticate automatically. In such cases, a pop-up will be displayed prompting the end user to log in manually. This ensures that the authentication process can still be completed even when third-party cookies are not available. ## Advanced Topics @@ -79,27 +79,27 @@ The iFrame used by SharePoint Embedded copilot attempts to authenticate using th Application scoping in SharePoint Embedded copilot (SPE copilot) involves defining the boundaries and context within which the tool operates, ensuring its features and capabilities are tailored to meet the specific needs of different applications. This process helps customize the copilot's functionality, making it more effective and relevant for various use cases. -When SPE copilot users query the LLM, it will only have access to files that the **User+Application** have access to. The effective permissions for the copilot session will be the intersection of your SharePoint Embedded application's permissions and the user's permissions. +When SPE copilot users query the LLM, it will only have access to files that the **User+Application** has access to. The effective permissions for the copilot session will be the intersection of your SharePoint Embedded application's permissions and the user's permissions. ![Venn Diagram with SPE application access on left, SPE copilot in middle and consuming tenant user on right, overlapped area is what copilot can access](../../images/speco-appscopingvenn.png) ### Information Architecture -Files in SharePoint Embedded are naturally [semantic indexed](spe-da-adv.md#semantic-index). This semantic index underpins retrieval augmented generation [(RAG)](spe-da-adv.md#rag--retrieval-augmented-generation-) workflows by providing relevant context from your stored content at query time. In essence, it [grounds](spe-da-adv.md#grounding) the AI responses, ensuring they directly reference accurate information in your containers rather than relying on general knowledge alone. +Files in SharePoint Embedded are naturally [semantically indexed](spe-da-adv.md#semantic-index). This semantic index underpins retrieval augmented generation [(RAG)](spe-da-adv.md#rag--retrieval-augmented-generation-) workflows by providing relevant context from your stored content at query time. In essence, it [grounds](spe-da-adv.md#grounding) the AI responses, ensuring they directly reference accurate information in your containers rather than relying on general knowledge alone. ![How RAG works in SPE](../../images/speco-ragm365.png) -With SharePoint Embedded copilot, you can further ground the large language models (LLM) reponses on [specific files or drive items.](spe-da-adv.md#scoping-your-copilot-to-specific-content). +With SharePoint Embedded copilot, you can further ground the large language models (LLM) responses on [specific files or drive items](spe-da-adv.md#scoping-your-copilot-to-specific-content). ### Semantic index -[Learn more about semantic index for Microsoft 365 Copilot here](/microsoftsearch/semantic-index-for-copilot) +[Learn more about the semantic index for Microsoft 365 Copilot here](/microsoftsearch/semantic-index-for-copilot) The semantic index allows for quick and accurate searches based on data similarity. This means it can find the most relevant information not just by exact matches, but also by understanding the context and meaning. ### Retrieval-Augmented Generation (RAG) -RAG relies on having relevant source materials stored in a repository, which can be queried at runtime​, data is retrieved from the index and is used to augment the prompt sent to the large language model (LLM)​: +RAG relies on having relevant source materials stored in a repository, which can be queried at runtime. Data is retrieved from the index and is used to augment the prompt sent to the large language model (LLM)​: - Treat data sources as knowledge without having to train your model​ - Uses search (retrieval) results as additional context in your prompt​ @@ -111,11 +111,11 @@ The LLM uses the data to inform and construct the response. ### Grounding -Grounding in the context of SPE copilot refers to the process of providing input sources to the large language model (LLM) related to the user's prompt. This helps improve the specificity of the prompt and ensures that the responses are relevant and actionable to the user's specific task. The data the copilot is grounded on will be on the contents of the container type in the copilot application. Behind the scenes SPE copilot uses M365 Copilot, [learn more about it's architecture here](/copilot/microsoft-365/microsoft-365-copilot-architecture) +Grounding in the context of SPE copilot refers to the process of providing input sources to the large language model (LLM) related to the user's prompt. This helps improve the specificity of the prompt and ensures that the responses are relevant and actionable to the user's specific task. The data the copilot is grounded on will be based on the contents of the container type in the copilot application. Behind the scenes SPE copilot uses M365 Copilot, [learn more about it's architecture here](/copilot/microsoft-365/microsoft-365-copilot-architecture). ### Scoping your copilot to specific content -SharePoint Embedded (SPE) copilot has the ability to restrict the data sources it has access to, below are provided types, and this [example](https://github.com/microsoft/SharePoint-Embedded-Samples/blob/main/Samples/spe-typescript-react-azurefunction/react-client/src/providers/ChatController.ts#L15) shows how to configure the SDK +SharePoint Embedded (SPE) copilot can restrict the data sources it has access to. Below are provided types, and this [example](https://github.com/microsoft/SharePoint-Embedded-Samples/blob/main/Samples/spe-typescript-react-azurefunction/react-client/src/providers/ChatController.ts#L15) shows how to configure the SDK: ```typescript export type IDataSourcesProps = @@ -158,9 +158,9 @@ export enum DataSourceType { ##### Language/Locale -The copilot iframe dynamically loads localization settings to ensure that the chat interface is displayed in the appropriate language. These settings are derived from SharePoint, which provides a comprehensive set of localization options. +The copilot `iframe` dynamically loads localization settings to ensure that the chat interface is displayed in the appropriate language. These settings are derived from SharePoint, which provides a comprehensive set of localization options. -When the copilot iframe is initialized, it retrieves the current localization settings from SharePoint. These settings dictate the language and regional preferences for the chat interface, ensuring that all UI elements, messages, and interactions are presented in the user's preferred language. This seamless integration with SharePoint's localization framework allows copilot to provide a consistent an +When the copilot `iframe` is initialized, it retrieves the current localization settings from SharePoint. These settings dictate the language and regional preferences for the chat interface, ensuring that all UI elements, messages, and interactions are presented in the user's preferred language. This seamless integration with SharePoint's localization framework allows copilot to provide a consistent an You can have this localized by setting your language options in the SharePoint account settings: [Change your personal language and region settings - Microsoft Support](https://support.microsoft.com/en-us/office/change-your-personal-language-and-region-settings-caa1fccc-bcdb-42f3-9e5b-45957647ffd7) note, if your M365 setting is different from your Sharepoint account langauge settings it will take precedence, you can change your M365 language settings here: [Change your display language in Microsoft 365](https://support.microsoft.com/en-us/topic/change-your-display-language-and-time-zone-in-microsoft-365-for-business-6f238bff-5252-441e-b32b-655d5d85d15b) From 30a4537ce17432925a8aba7e30544df92243e6da Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Tue, 20 May 2025 09:40:21 -0700 Subject: [PATCH 4/5] change date, check access rights --- docs/embedded/development/declarative-agent/spe-da-adv.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md index 8364cdc725..14eca2bcef 100644 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -1,7 +1,7 @@ --- title: SharePoint Embedded copilot Advanced Topics description: Learn how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses in SharePoint Embedded copilot. -ms.date: 3/03/2025 +ms.date: 5/20/2025 ms.localizationpriority: high --- From fc6049ec4230031d4824ee52cb0548724542bd7c Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Tue, 20 May 2025 10:09:25 -0700 Subject: [PATCH 5/5] get acrolinx score from 62 to 70.... --- .../declarative-agent/spe-da-adv.md | 34 ++++++++++++------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md index 14eca2bcef..39fff9f909 100644 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -7,19 +7,27 @@ ms.localizationpriority: high # SharePoint Embedded copilot Advanced Topics Overview -This advanced guide covers how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses. We’ll explore how these concepts work together to ensure your copilot retrieves relevant information from your data and returns grounded answers. +This advanced guide covers how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses. We explore how these concepts work together to ensure your copilot retrieves relevant information from your data and returns grounded answers. ## Caveats ### Configuration -#### Required ContainerType Configuration +#### Required Container Type Configuration ##### DiscoverabilityDisabled -This [flag](../../administration/developer-admin/dev-admin.md#container-type-configuration-properties) prevents copilot from discovering [drive items](/graph/api/resources/driveitem) in the specified container type. If you have an existing container type and are setting this value to false, please wait 24 hours to ensure the container type configuration is fully propagated before creating a new container, uploading files there, and trying out copilot on folders/files of that new container. +The [`discoverabilityDisabled`](../../administration/developer-admin/dev-admin.md#container-type-configuration-properties) property controls whether [copilot](https://learn.microsoft.com/en-us/microsoft-365-copilot/) can discover [drive items](/graph/api/resources/driveitem) within a specific container type. -The following is an example of how to set the flag to false with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples) +If you’re updating an existing container type to set this property to `false`, allow up to **24 hours** for the configuration change to fully propagate before: + +- Creating new containers, +- Uploading files to containers, or +- Using copilot to interact with folders or files. + +This ensures copilot can correctly access and surface the content. + +Here is an example of how to set `discoverabilityDisabled` to false with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples) ```powershell Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $false @@ -33,14 +41,14 @@ Discoverability can also be disabled using the Visual Studio Code SharePoint Emb The Content-Security-Policy (CSP) for embedded chat hosts ensures that only specified hosts can load the chat component. This helps in securing the application by restricting which domains can embed the chat component. -It is intended to allow consuming tenant SPE admins to set an allowlist of hosts that they will allow to embed the SPE copilot in an iFrame. Specifically, the value they set here will be used in a Content-Security-Policy header as a frame-ancestors value. +It's intended to allow consuming tenant SPE admins to set an allowlist of hosts that are permitted to embed the SPE copilot in an iFrame. Specifically, the value they set here is used in a Content-Security-Policy header as a frame-ancestors value. > [!NOTE] > -> If this configuration is not set, the [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) will default be set to -> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): ‘none’ which means no one can embed the copilot. +> If this configuration isn't set, the [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) is default set to +> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): "none" which means no one can embed the copilot. -Below are example commands to use the [Connect to SharePoint Online using PowerShell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online) commands: +Here are example commands to use the [Connect to SharePoint using PowerShell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online) commands: - [Set-SPOApplication](/powershell/module/SharePoint-online/set-spoapplication) to set the `CopilotEmbeddedChatHosts` property. - [Get-SPOApplication](/powershell/module/SharePoint-online/get-spoapplication) to get the `CopilotEmbeddedChatHosts` property. @@ -71,7 +79,7 @@ CopilotEmbeddedChatHosts : {http://localhost:*} ##### Authentication and 3P Cookies -The iFrame used by SharePoint Embedded copilot attempts to authenticate using third-party cookies. If third-party cookies are disabled in the user's browser, the iFrame will not be able to authenticate automatically. In such cases, a popup will be displayed prompting the end user to log in manually. This ensures that the authentication process can still be completed even when third-party cookies are not available. +The iFrame used by SharePoint Embedded Copilot authenticates users using third-party cookies. If third-party cookies are disabled in the user's browser, the iFrame can't authenticate automatically. In this case, a popup prompts the user to sign in manually, ensuring that authentication can still be completed. ## Advanced Topics @@ -89,7 +97,7 @@ Files in SharePoint Embedded are naturally [semantic indexed](spe-da-adv.md#sema ![How RAG works in SPE](../../images/speco-ragm365.png) -With SharePoint Embedded copilot, you can further ground the large language models (LLM) reponses on [specific files or drive items.](spe-da-adv.md#scoping-your-copilot-to-specific-content). +With SharePoint Embedded copilot, you can further ground the large language models (LLM) response on [specific files or drive items.](spe-da-adv.md#scoping-your-copilot-to-specific-content). ### Semantic index @@ -111,7 +119,7 @@ The LLM uses the data to inform and construct the response. ### Grounding -Grounding in the context of SPE copilot refers to the process of providing input sources to the large language model (LLM) related to the user's prompt. This helps improve the specificity of the prompt and ensures that the responses are relevant and actionable to the user's specific task. The data the copilot is grounded on will be on the contents of the container type in the copilot application. Behind the scenes SPE copilot uses M365 Copilot, [learn more about it's architecture here](/copilot/microsoft-365/microsoft-365-copilot-architecture) +Grounding in the context of SPE copilot refers to the process of providing input sources to the large language model (LLM) related to the user's prompt. This helps improve the specificity of the prompt and ensures that the responses are relevant and actionable to the user's specific task. The data the copilot is grounded on will be on the contents of the container type in the copilot application. Behind the scenes SPE copilot uses Microsoft 365 Copilot, [learn more about it's architecture here](/copilot/microsoft-365/microsoft-365-copilot-architecture) ### Scoping your copilot to specific content @@ -162,9 +170,9 @@ The copilot iframe dynamically loads localization settings to ensure that the ch When the copilot iframe is initialized, it retrieves the current localization settings from SharePoint. These settings dictate the language and regional preferences for the chat interface, ensuring that all UI elements, messages, and interactions are presented in the user's preferred language. This seamless integration with SharePoint's localization framework allows copilot to provide a consistent an -You can have this localized by setting your language options in the SharePoint account settings: [Change your personal language and region settings - Microsoft Support](https://support.microsoft.com/en-us/office/change-your-personal-language-and-region-settings-caa1fccc-bcdb-42f3-9e5b-45957647ffd7) note, if your M365 setting is different from your Sharepoint account langauge settings it will take precedence, you can change your M365 language settings here: [Change your display language in Microsoft 365](https://support.microsoft.com/en-us/topic/change-your-display-language-and-time-zone-in-microsoft-365-for-business-6f238bff-5252-441e-b32b-655d5d85d15b) +You can have this localized by setting your language options in the SharePoint account settings: [Change your personal language and region settings - Microsoft Support](https://support.microsoft.com/en-us/office/change-your-personal-language-and-region-settings-caa1fccc-bcdb-42f3-9e5b-45957647ffd7) note, if your M365 setting is different from your Sharepoint account langauge settings it takes precedence, you can change your M365 language settings here: [Change your display language in Microsoft 365](https://support.microsoft.com/en-us/topic/change-your-display-language-and-time-zone-in-microsoft-365-for-business-6f238bff-5252-441e-b32b-655d5d85d15b) -An additional locale option can be passed in through the `ChatLaunchConfig` to further set the language the copilot will respond in: +An additional locale option can be passed in through the `ChatLaunchConfig` to further set the language the copilot responds in: ```typescript const [chatConfig] = React.useState({