diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md index d240fd56e..2a04298bd 100644 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -1,6 +1,6 @@ --- -title: SharePoint Embedded copilots Advanced Topics -description: Learn how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses in SharePoint Embedded copilots. +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.localizationpriority: high --- @@ -9,15 +9,95 @@ ms.localizationpriority: high 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. +## Caveats + +### Configuration + +#### Required ContainerType 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 following is an example of how to set the flag to false with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples) + +```powershell +Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $false +``` + +Discoverability can also be disabled using the Visual Studio Code SharePoint Embedded extension + +![Using the VS Code extension for SPE to set DiscoverabilityDisabled to false](../../images/speco-vscodeextensiondisablediscovery.png) + +##### CSP Policies + +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. + +> [!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. + +Below are example commands to use the [Connect to SharePoint Online 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. + +```powershell +# Note this MUST be run in Windows PowerShell. It will not work in PowerShell. +Import-Module -Name "Microsoft.Online.SharePoint.PowerShell" +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" + +# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly. +... + +Get-SPOApplication -OwningApplicationId | Select-Object CopilotEmbeddedChatHosts + +OwningApplicationId : +OwningApplicationName : SharePoint Embedded App +Applications : {} +SharingCapability : ExternalUserAndGuestSharing +OverrideTenantSharingCapability : False +CopilotEmbeddedChatHosts : {http://localhost:*} +``` + +#### Optional Configuration + +##### 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. + ## Advanced Topics +### Application Scoping + +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. + +![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. + +![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). + ### Semantic index [Learn more about 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. -### RAG ( Retrieval-Augmented Generation ) +### 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)​: diff --git a/docs/embedded/development/declarative-agent/spe-da.md b/docs/embedded/development/declarative-agent/spe-da.md index d56f758d4..805461488 100644 --- a/docs/embedded/development/declarative-agent/spe-da.md +++ b/docs/embedded/development/declarative-agent/spe-da.md @@ -1,6 +1,6 @@ --- -title: SharePoint Embedded copilots -description: Details copilots integration with SharePoint Embedded applications +title: SharePoint Embedded copilot +description: Details copilot integration with SharePoint Embedded applications ms.date: 02/19/2025 ms.localizationpriority: high --- @@ -9,51 +9,31 @@ ms.localizationpriority: high > [!NOTE] > -> SharePoint Embedded copilots is currently in private preview, the API surface and SDK are expected to change frequently. - -SharePoint Embedded copilots is a powerful tool designed to enhance the functionality of SharePoint Embedded (SPE) applications by integrating advanced Microsoft 365 features (Purview, Protection, etc.) - -![Diagram illustrating SPE copilot is AI ready](../../images/speco-apparch.png) - -## Billing/Licensing - -Currently, to use SPE copilot, the consuming tenant user of the application is required to have a [Microsoft 365 Copilot license](/copilot/microsoft-365/microsoft-365-copilot-licensing). In the future, the license-based model will be replaced with a consumption-based model. The usage of SPE copilots will be charged on a pay-as-you-go basis to your SharePoint Embedded application (that is, to the owning tenant). Stay tuned for billing model announcements during the preview period. - -## Why use SharePoint Embedded copilots - -SharePoint Embedded copilots harness a semantic index to power Retrieval-Augmented Generation (RAG), securely referencing your data within the Microsoft 365 boundary at query time. This ensures accurate, grounded AI responses while reducing reliance on broad knowledge models. A pay-as-you-go billing model is on the horizon, aligning costs with actual usage. - -![Showcasing how SPE content gets AI from M365 Copilot](../../images/speco-aivalue.png) - -### Application Scoping - -Application scoping in SharePoint Embedded copilots (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. - -![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 +> SharePoint Embedded copilot is currently in private preview. Stay tuned for latest API and SDK changes on this page. +> +> Currently, to use SPE copilot, the consuming tenant user of the application is required to have a [Microsoft 365 Copilot license](/copilot/microsoft-365/microsoft-365-copilot-licensing). In the future, the license-based model will be replaced with a consumption-based model. Stay tuned for billing model announcements during the preview period. -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. +SharePoint Embedded copilot enables you to build Microsoft 365 Copilot functionality into your application through a simple SDK. This copilot chat control offers the following features: -![How RAG works in SPE](../../images/speco-ragm365.png) +- Reason over documents in SharePoint Embedded containers using RAG. +- Developers can configure the application code to limit the search scope to files, folders, and containers. +- Developers can customize and configure chat control including starter prompts, suggested prompts, colors and more. -With SharePoint Embedded copilots, 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). +Watch this demo to learn more about how to configure this functionality. -### Microsoft 365 Boundary +> [!VIDEO https://www.youtube.com/embed/30i7q09EtQo?si=MwLtbrGKnzv7a6My] -Data is kept secure: data never leaves the tenant boundary and storage respects data residency settings. +## Why use SharePoint Embedded copilot -Each container instance of a container type in the SPE partition is its own security and compliance boundary. +SharePoint Embedded copilot harness a semantic index to power Retrieval-Augmented Generation (RAG), securely referencing your data within the Microsoft 365 boundary at query time. This ensures accurate, grounded AI responses while reducing reliance on broad knowledge models. A pay-as-you-go billing model is on the horizon, aligning costs with actual usage. -![M365 Storage Partitions](../../images/speco-bound.png) +![Diagram illustrating SPE copilot is AI ready](../../images/speco-apparch.png) -## How to use SharePoint Embedded copilots +## How to use SharePoint Embedded copilot ### How to build your copilot -Currently, we offer a way to incorporate this feature into your custom application is through our React SDK library written in TypeScript. Plans to support additional frameworks and environments will be announced. The SDK is configured with the containerId instance of your containerType, as well as the authorization and authentication token logic you provide through a callback. It will embed itself as an iFrame into your host application. By default, the iFrame is given a `frame-ancestors` property that prevents it from being embedded by any host until configured. Details are provided below. +Currently, you can use the React SDK library written in TypeScript to build your application. Plans to support additional frameworks and environments will be announced. The SDK is configured with the containerId instance of your containerType, as well as the authorization and authentication token logic you provide through a callback. It will embed itself as an iFrame into your host application. By default, the iFrame is given a `frame-ancestors` property that prevents it from being embedded by any host until configured. Details are provided below. #### SPE TypeScript React Application @@ -61,13 +41,13 @@ Follow the [quick start guide](../tutorials/spe-da-vscode.md) to get started wit ### API Documentation -The SharePoint Embedded React TypeScript NPM Package, available at [here](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/feature/copilot-react-sdk/sharepointembedded-chatembedded-react/docs), provides the SDK for integrating SharePoint Embedded copilots into your client applications. +The SharePoint Embedded React TypeScript NPM Package, available at [here](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/feature/copilot-react-sdk/sharepointembedded-chatembedded-react/docs/index.md), provides the SDK for integrating SharePoint Embedded copilot into your client applications. ## Frequently Asked Questions ### Is consumption-based billing available for SPE copilot? -Currently you need a Microsoft 365 Copilot license enabled for your user to use SharePoint Embedded copilots. When consumption-based billing is enabled, you will no longer require a license, however, you will be required to use a Standard Container type. +Currently you need a Microsoft 365 Copilot license enabled for your user to use SharePoint Embedded copilot. When consumption-based billing is enabled, you will no longer require a license, however, you will be required to use a Standard Container type. ***Trial Container Types expire after 30 days, for this reason we recommend starting off with Standard Container types. Currently there is no upgrade path from Trial to Standard container types.*** @@ -85,71 +65,6 @@ When you click the thumbs down button, a feedback dialog will appear. Please inc ![SPE copilot Feedback Modal preview](../../images/speco-feedbackcombined.png) -## Caveats - -### Configuration - -#### Required ContainerType 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 following is an example of how to set the flag to false with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples) - -```powershell -Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $false -``` - -Discoverability can also be disabled using the Visual Studio Code SharePoint Embedded extension - -![Using the VS Code extension for SPE to set DiscoverabilityDisabled to false](../../images/speco-vscodeextensiondisablediscovery.png) - -##### CSP Policies - -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. - -> [!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. - -Below are example commands to use the [Connect to SharePoint Online 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. - -```powershell -# Note this MUST be run in Windows PowerShell. It will not work in PowerShell. -Import-Module -Name "Microsoft.Online.SharePoint.PowerShell" -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" - -# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly. -... - -Get-SPOApplication -OwningApplicationId | Select-Object CopilotEmbeddedChatHosts - -OwningApplicationId : -OwningApplicationName : SharePoint Embedded App -Applications : {} -SharingCapability : ExternalUserAndGuestSharing -OverrideTenantSharingCapability : False -CopilotEmbeddedChatHosts : {http://localhost:*} - -``` - -#### Optional Configuration - -##### Authentication and 3P Cookies - -The iFrame used by SharePoint Embedded copilots 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. - ## Advanced Topics Overview -The [advanced topics](spe-da-adv.md) delve into how SharePoint Embedded copilots use a semantic index to facilitate Retrieval-Augmented Generation (RAG), ensuring responses are accurately grounded in your stored content. You’ll also learn how to scope your copilot to specific data sources, set up various file formats, and configure locale options to tailor the copilot experience. By exploring concepts like grounding, semantic indexing, and RAG workflows, you can optimize your copilot’s effectiveness and maintain security within the Microsoft 365 boundary. +The [advanced topics](spe-da-adv.md) delve into how SharePoint Embedded copilot use a semantic index to facilitate Retrieval-Augmented Generation (RAG), ensuring responses are accurately grounded in your stored content. You’ll also learn how to scope your copilot to specific data sources, set up various file formats, and configure locale options to tailor the copilot experience. By exploring concepts like grounding, semantic indexing, and RAG workflows, you can optimize your copilot’s effectiveness and maintain security within the Microsoft 365 boundary. diff --git a/docs/embedded/development/tutorials/spe-da-vscode.md b/docs/embedded/development/tutorials/spe-da-vscode.md index 9c76f66f9..eab3339f8 100644 --- a/docs/embedded/development/tutorials/spe-da-vscode.md +++ b/docs/embedded/development/tutorials/spe-da-vscode.md @@ -11,11 +11,12 @@ ms.localizationpriority: high > [!NOTE] > +> 1. You will need to create create a SharePoint Embedded application. If you don't have one, you can easily build a sample application using the instructions [here](#getting-started-using-the-sharepoint-embedded-visual-studio-code-extension). > 1. You must specify a standard container type at creation time. Depending on the purpose, you may or may not need to provide your Azure Subscription ID. A container type set for trial purposes can't be converted for production; or vice versa. > 1. You must use the latest version of SharePoint PowerShell to configure a container type. For permissions and the most current information about Windows PowerShell for SharePoint Embedded, see the documentation at [Intro to SharePoint Embedded Management Shell](/powershell/SharePoint/SharePoint-online/introduction-SharePoint-online-management-shell). > -> - Set the **ChatEmbeddedHosts** property of your container type configuration to `http://localhost:8080` to be able to work through the quick start below, refer to [the CSP section above for more information](../declarative-agent/spe-da.md#csp-policies) -> - Set the **DiscoverabilityDisabled** property of your container type configuration to `false` so that copilot can find the files in your created container refer to the [Discoverability Disabled section above for more information](../declarative-agent/spe-da.md#discoverabilitydisabled) +> - Set the **ChatEmbeddedHosts** property of your container type configuration to `http://localhost:8080` to be able to work through the quick start below, refer to [the CSP section above for more information](../declarative-agent/spe-da-adv.md#csp-policies) +> - Set the **DiscoverabilityDisabled** property of your container type configuration to `false` so that copilot can find the files in your created container refer to the [Discoverability Disabled section above for more information](../declarative-agent/spe-da-adv.md#discoverabilitydisabled) > - Ensure that copilot for Microsoft 365 is available for your organization. You have two ways to get a developer environment for copilot: > - A sandbox Microsoft 365 tenant with M365 Copilot (available in limited preview through [TAP membership](https://developer.microsoft.com/microsoft-365/tap)). > - An [eligible Microsoft 365 or Office 365 production environment](/microsoft-365-copilot/extensibility/prerequisites#customers-with-existing-microsoft-365-and-copilot-licenses) with a M365 Copilot license. @@ -292,7 +293,7 @@ function App() { ### Quick Start > [!NOTE] -> When using standard container types with the VS Code extension, [DisableDiscoverability](../declarative-agent/spe-da.md#discoverabilitydisabled) and [Grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal) features are currently not supported. This will need to be done using the [SPO Admin Powershell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online). +> When using standard container types with the VS Code extension, [DisableDiscoverability](../declarative-agent/spe-da-adv.md#discoverabilitydisabled) and [Grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal) features are currently not supported. This will need to be done using the [SPO Admin Powershell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online). 1. Follow this guide up to the [Load Sample App section](../../getting-started/spembedded-for-vscode.md#load-sample-app) with the Visual Studio Code Extension 1. Within the extension, right click on the owning application, and select `Run sample apps -> Typescript + React + Azure Functions` diff --git a/docs/embedded/images/speco-aivalue.png b/docs/embedded/images/speco-aivalue.png deleted file mode 100644 index 6021c9407..000000000 Binary files a/docs/embedded/images/speco-aivalue.png and /dev/null differ diff --git a/docs/toc.yml b/docs/toc.yml index 3c530d30a..f3493e61d 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -588,8 +588,6 @@ href: embedded/development/tutorials/using-webhooks.md - name: Migrate ABS to SPE href: embedded/development/tutorials/migrate-abs-to-spe.md - - name: Sharepoint Embedded copilot Tutorial - href: embedded/development/tutorials/spe-da-vscode.md - name: Administration items: - name: Billing @@ -618,11 +616,13 @@ href: /training/modules/sharepoint-embedded-setup - name: SharePoint Embedded - building applications href: /training/modules/sharepoint-embedded-create-app - - name: Sharepoint Embedded copilot ( Private Preview ) + - name: SharePoint Embedded copilot ( Private Preview ) items: - - name: Sharepoint Embedded copilot ( Private Preview ) + - name: SharePoint Embedded copilot Overview href: embedded/development/declarative-agent/spe-da.md - - name: Sharepoint Embedded copilot Advanced Topics + - name: SharePoint Embedded copilot Tutorial + href: embedded/development/tutorials/spe-da-vscode.md + - name: SharePoint Embedded copilot Advanced Topics href: embedded/development/declarative-agent/spe-da-adv.md - name: Microsoft Teams items: