Skip to content

Commit f19463a

Browse files
author
grjoseph
committed
SPE copilot documentation
1 parent a306437 commit f19463a

27 files changed

+704
-0
lines changed

‎docs/embedded/development/declarative-agent/spe-da-adv.md

+183
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: SharePoint Embedded copilots Advanced Topics
3+
description: Details copilots Advanced Topics
4+
ms.date: 3/03/2025
5+
ms.localizationpriority: high
6+
---
7+
8+
# SharePoint Embedded copilot Advanced Topics Overview
9+
10+
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.
11+
12+
## Advanced Topics
13+
14+
### Semantic index
15+
16+
[Learn more about semantic index for Microsoft 365 Copilot here](/microsoftsearch/semantic-index-for-copilot)
17+
18+
The semantic index allows for quick and accurate searches based on the similarity of data. This means it can find the most relevant information not just by exact matches, but also by understanding the context and meaning.
19+
20+
### RAG ( Retrieval-Augmented Generation )
21+
22+
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 LLM​:
23+
24+
- Lets you treat data sources as knowledge without having to train your model​
25+
- Uses search (retrieval) results as additional context in your prompt​
26+
- Generates the output using the prompt and the supplied context
27+
28+
The data is used by the LLM to inform and construct the response​
29+
30+
​![The flow of a RAG query](../../images/speco-ragquery.png)
31+
32+
### Grounding
33+
34+
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)
35+
36+
### Scoping your copilot to specific content
37+
38+
SPE copilot has the ability to restrict the datasources 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) show's how to configure the SDK
39+
40+
```typescript
41+
export type IDataSourcesProps =
42+
| IFileDataSource
43+
| IFolderDataSource
44+
| IDocumentLibraryDataSource
45+
| ISiteDataSource
46+
| IWorkingSetDataSource
47+
| IMeetingDataSource;
48+
49+
export enum DataSourceType {
50+
File = 'File',
51+
Folder = 'Folder',
52+
DocumentLibrary = 'DocumentLibrary',
53+
Site = 'Site',
54+
WorkingSet = 'WorkingSet',
55+
Meeting = 'Meeting'
56+
}
57+
```
58+
59+
#### Supported document types for scoping
60+
61+
[Reference - File Formats Support By copilot](https://support.microsoft.com/topic/file-formats-supported-by-copilot-1afb9a70-2232-4753-85c2-602c422af3a8)
62+
63+
**Documents**: PDF, DOCX, XLSX, PPTX
64+
65+
**Text-based Files**: RTF, TXT, CSV, LOG, INI, CONFIG
66+
67+
**Audio**: WAV
68+
69+
**Programming Languages**: PY, JS, JSX, JAVA, PHP, CS, C, CPP, CXX, H, HPP, M, COFFEE, DART, LUA, PL, PM, RB, RS, SWIFT, GO, KT, KTS, R, SCALA, T, TS, TSX
70+
71+
**Shell Scripts**: BASH, SH, ZSH
72+
73+
**Markup and Documentation**: HTML, CSS, MD, RMD, TEX, LATEX
74+
75+
**Database Languages**: SQL
76+
77+
**Data Serialization Formats**: IPYNB, JSON, TOML, YAML, YML
78+
79+
##### Language/Locale
80+
81+
An additional locale option can be passed in through the `ChatLaunchConfig` to further set the language the Copilot will respond in:
82+
83+
```typescript
84+
const [chatConfig] = React.useState<ChatLaunchConfig>({
85+
header: ChatController.instance.header,
86+
theme: ChatController.instance.theme,
87+
zeroQueryPrompts: ChatController.instance.zeroQueryPrompts,
88+
suggestedPrompts: ChatController.instance.suggestedPrompts,
89+
instruction: ChatController.instance.pirateMetaPrompt,
90+
locale: "en",
91+
});
92+
```
93+
94+
###### Locale Options
95+
96+
Here are some examples of locale options you can use:
97+
98+
| Locale Code | Common Name |
99+
|--------------|------------------------------------------|
100+
| af | Afrikaans |
101+
| en-gb | English (UK) |
102+
| he | Hebrew |
103+
| kok | Konkani |
104+
| nn-no | Norwegian (Nynorsk) |
105+
| sr-latn-rs | Serbian (Latin, Serbia) |
106+
| am-et | Amharic |
107+
| es | Spanish |
108+
| hi | Hindi |
109+
| lb-lu | Luxembourgish |
110+
| or-in | Odia (India) |
111+
| sv | Swedish |
112+
| ar | Arabic |
113+
| es-mx | Spanish (Mexico) |
114+
| hr | Croatian |
115+
| lo | Lao |
116+
| pa | Punjabi |
117+
| ta | Tamil |
118+
| as-in | Assamese |
119+
| et | Estonian |
120+
| hu | Hungarian |
121+
| lt | Lithuanian |
122+
| pl | Polish |
123+
| te | Telugu |
124+
| az-latn-az | Azerbaijani (Latin, Azerbaijan) |
125+
| eu | Basque |
126+
| hy | Armenian |
127+
| lv | Latvian |
128+
| pt-br | Portuguese (Brazil) |
129+
| th | Thai |
130+
| bg | Bulgarian |
131+
| fa | Persian |
132+
| id | Indonesian |
133+
| mi-nz | Maori (New Zealand) |
134+
| pt-pt | Portuguese (Portugal) |
135+
| tr | Turkish |
136+
| bs-latn-ba | Bosnian (Latin, Bosnia and Herzegovina) |
137+
| fi | Finnish |
138+
| is | Icelandic |
139+
| mk | Macedonian |
140+
| quz-pe | Quechua (Peru) |
141+
| tt | Tatar |
142+
| ca-es-valencia | Catalan (Valencian) |
143+
| fil-ph | Filipino (Philippines) |
144+
| it | Italian |
145+
| ml | Malayalam |
146+
| ro | Romanian |
147+
| ug | Uyghur |
148+
| ca | Catalan |
149+
| fr-ca | French (Canada) |
150+
| ja | Japanese |
151+
| mr | Marathi |
152+
| ru | Russian |
153+
| uk | Ukrainian |
154+
| cs | Czech |
155+
| fr | French |
156+
| ka | Georgian |
157+
| ms | Malay |
158+
| sk | Slovak |
159+
| ur | Urdu |
160+
| cy-gb | Welsh (UK) |
161+
| ga-ie | Irish (Ireland) |
162+
| kk | Kazakh |
163+
| mt-mt | Maltese (Malta) |
164+
| sl | Slovenian |
165+
| uz-latn-uz | Uzbek (Latin, Uzbekistan) |
166+
| da | Danish |
167+
| gd | Scottish Gaelic |
168+
| km-kh | Khmer (Cambodia) |
169+
| nb-no | Norwegian (Bokmål) |
170+
| sq | Albanian |
171+
| vi | Vietnamese |
172+
| de | German |
173+
| gl | Galician |
174+
| kn | Kannada |
175+
| ne-np | Nepali (Nepal) |
176+
| sr-cyrl-ba | Serbian (Cyrillic, Bosnia and Herzegovina)|
177+
| zh-cn | Chinese (Simplified) |
178+
| el | Greek |
179+
| gu | Gujarati |
180+
| ko | Korean |
181+
| nl | Dutch |
182+
| sr-cyrl-rs | Serbian (Cyrillic, Serbia) |
183+
| zh-tw | Chinese (Traditional) |

‎docs/embedded/development/declarative-agent/spe-da.md

+155
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: SharePoint Embedded copilots
3+
description: Details copilots Integration with SharePoint Embedded Applications
4+
ms.date: 02/19/2025
5+
ms.localizationpriority: high
6+
---
7+
8+
# Overview
9+
10+
> [!NOTE]
11+
>
12+
> SharePoint Embedded copilots is currently in private preview, the API surface and SDK are expected to change frequently.
13+
14+
SharePoint Embedded copilots is a powerful tool designed to enhance the functionality of SharePoint Embedded applications by integrating advanced Microsoft 365 features (Purview, Protection, etc.)
15+
16+
![Diagram illustrating SPE copilot is AI ready](../../images/speco-apparch.png)
17+
18+
## Billing/Licensing
19+
20+
Currently, to use SPE copilot , the consuming tenant user of the application is required to have an [Microsfot 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.
21+
22+
## Why use SharePoint Embedded copilots
23+
24+
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.
25+
26+
![Showcasing how SPE content gets AI from M365 Copilot](../../images/speco-aivalue.png)
27+
28+
### Application Scoping
29+
30+
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.
31+
32+
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.
33+
34+
![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)
35+
36+
### Information Architecture
37+
38+
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.
39+
40+
![How RAG works in SPE](../../images/speco-ragm365.png)
41+
42+
With SharPoint Embedded copilots , you can further ground the LLMs reponses on [specific files or drive items.](spe-da-adv.md#scoping-your-copilot-to-specific-content).
43+
44+
### Microsoft 365 Boundary
45+
46+
Data is kept secure: data never leaves the tenant boundary and storage respects data residency settings​.
47+
48+
Each container instance of a container type in the SPE partition is its own security and compliance boundary.
49+
50+
![M365 Storage Partitions](../../images/speco-bound.png)
51+
52+
## How to use SharePoint Embedded copilots
53+
54+
### How to build your copilot
55+
56+
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.
57+
58+
#### SPE TypeScript React Application
59+
60+
Follow the [quick start guide](../../tutorials/spe-da-vscode.md) to get started with a prebuilt sample application.
61+
62+
### API Documentation
63+
64+
The SharePoint Embedded React TypeScript NPM Package, available at [here](https://github.com/microsoft/SharePoint-Embedded-Samples/spe-react-npm-package/api-extractor), provides the SDK for integrating SharePoint Embedded copilots into your client applications.
65+
66+
## Frequently Asked Questions
67+
68+
### Is consumption-based billing available for SPE copilot?
69+
70+
Currently you need a M365 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.
71+
72+
***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.***
73+
74+
### Should I use a standard or trial container type?
75+
76+
Once consumption-based billing is enabled, we will be disabling using this feature with Trial Container types and it will only be enabled on Standard container types going forward. Please follow this [guide](../../getting-started/containertypes.md) to get started on creating your Standard Container type.
77+
78+
## SharePoint Embedded copilot Support
79+
80+
### Chat Control Feedback Dialog
81+
82+
If you encounter any issues with the chat control, please use the thumbs up and down feedback buttons to report the problem. This method is preferred for sending feedback because it provides us with telemetry data that helps us diagnose and troubleshoot the issue more effectively.
83+
84+
When you click the thumbs down button, a feedback dialog will appear. Please include any relevant information in this dialog.
85+
86+
![SPE copilot Feedback Modal preview](../../images/speco-feedbackcombined.png)
87+
88+
## Caveats
89+
90+
### Configuration
91+
92+
#### Required ContainerType Configuration
93+
94+
##### DiscoverabilityDisabled
95+
96+
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.
97+
98+
Here is an example of setting the flag to false with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples)
99+
100+
```powershell
101+
Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $false
102+
```
103+
104+
Discoverability can also be disabled using the Visual Studio Code SharePoint Embedded extension
105+
106+
![Using the VS Code extension for SPE to set DiscoverabilityDisabled to false](../../images/speco-vscodeextensiondisablediscovery.png)
107+
108+
##### CSP Policies
109+
110+
The Content-Security-Policy (CSP) for embedded chat hosts, ensures that only specified hosts can load the `chatembedded.aspx` page. This helps in securing the application by restricting which domains can embed the chat component.
111+
112+
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.
113+
114+
> [!NOTE]
115+
>
116+
> 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
117+
> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): ‘none’ which means no one can embed the copilot.
118+
119+
Below are example commands to use the [Connect to SharePoint Online using PowerShell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online) commands:
120+
121+
- [Set-SPOApplication](/powershell/module/SharePoint-online/set-spoapplication) to set the `CopilotEmbeddedChatHosts` property.
122+
- [Get-SPOApplication](/powershell/module/SharePoint-online/get-spoapplication) to get the `CopilotEmbeddedChatHosts` property.
123+
124+
```powershell
125+
# Note this MUST be run in Windows PowerShell. It will not work in PowerShell.
126+
Import-Module -Name "Microsoft.Online.SharePoint.PowerShell"
127+
Connect-SPOService "https://<domain>-admin.sharepoint.com"
128+
# Login with your admin account.
129+
...
130+
131+
Set-SPOApplication -OwningApplicationId 423poi45 -CopilotEmbeddedChatHosts "http://localhost:3000 https://contoso.sharepoint.com https://fabrikam.com"
132+
133+
# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly.
134+
...
135+
136+
Get-SPOApplication -OwningApplicationId <OwningApplicationId> | Select-Object CopilotEmbeddedChatHosts
137+
138+
OwningApplicationId : <OwningApplicationId>
139+
OwningApplicationName : SharePoint Embedded App
140+
Applications : {<OwningApplicationId>}
141+
SharingCapability : ExternalUserAndGuestSharing
142+
OverrideTenantSharingCapability : False
143+
CopilotEmbeddedChatHosts : {http://localhost:*}
144+
145+
```
146+
147+
#### Optional Configuration
148+
149+
##### Authentication and 3P Cookies
150+
151+
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.
152+
153+
## Advanced Topics Overview
154+
155+
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.

0 commit comments

Comments
 (0)