diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md new file mode 100644 index 000000000..d240fd56e --- /dev/null +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -0,0 +1,189 @@ +--- +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. +ms.date: 3/03/2025 +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. + +## Advanced Topics + +### 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 ) + +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​ +- Generates the output using the prompt and the supplied context + +The LLM uses the data to inform and construct the response. + +​![The flow of a RAG query](../../images/speco-ragquery.png) + +### 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) + +### 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 + +```typescript +export type IDataSourcesProps = + | IFileDataSource + | IFolderDataSource + | IDocumentLibraryDataSource + | ISiteDataSource + | IWorkingSetDataSource + | IMeetingDataSource; + +export enum DataSourceType { + File = 'File', + Folder = 'Folder', + DocumentLibrary = 'DocumentLibrary', + Site = 'Site', + WorkingSet = 'WorkingSet', + Meeting = 'Meeting' +} +``` + +#### Supported document types for scoping + +[Reference - File Formats Support By copilot](https://support.microsoft.com/topic/file-formats-supported-by-copilot-1afb9a70-2232-4753-85c2-602c422af3a8) + +**Documents**: PDF, DOCX, XLSX, PPTX + +**Text-based Files**: RTF, TXT, CSV, LOG, INI, CONFIG + +**Audio**: WAV + +**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 + +**Shell Scripts**: BASH, SH, ZSH + +**Markup and Documentation**: HTML, CSS, MD, RMD, TEX, LATEX + +**Database Languages**: SQL + +**Data Serialization Formats**: IPYNB, JSON, TOML, YAML, YML + +##### 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. + +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) + +An additional locale option can be passed in through the `ChatLaunchConfig` to further set the language the copilot will respond in: + +```typescript + const [chatConfig] = React.useState({ + header: ChatController.instance.header, + theme: ChatController.instance.theme, + zeroQueryPrompts: ChatController.instance.zeroQueryPrompts, + suggestedPrompts: ChatController.instance.suggestedPrompts, + instruction: ChatController.instance.pirateMetaPrompt, + locale: "en", + }); +``` + +###### Locale Options + +Here are some examples of locale options you can use: + +| Locale Code | Common Name | +|--------------|------------------------------------------| +| af | Afrikaans | +| en-gb | English (UK) | +| he | Hebrew | +| kok | Konkani | +| nn-no | Norwegian (Nynorsk) | +| sr-latn-rs | Serbian (Latin, Serbia) | +| am-et | Amharic | +| es | Spanish | +| hi | Hindi | +| lb-lu | Luxembourgish | +| or-in | Odia (India) | +| sv | Swedish | +| ar | Arabic | +| es-mx | Spanish (Mexico) | +| hr | Croatian | +| lo | Lao | +| pa | Punjabi | +| ta | Tamil | +| as-in | Assamese | +| et | Estonian | +| hu | Hungarian | +| lt | Lithuanian | +| pl | Polish | +| te | Telugu | +| az-latn-az | Azerbaijani (Latin, Azerbaijan) | +| eu | Basque | +| hy | Armenian | +| lv | Latvian | +| pt-br | Portuguese (Brazil) | +| th | Thai | +| bg | Bulgarian | +| fa | Persian | +| id | Indonesian | +| mi-nz | Maori (New Zealand) | +| pt-pt | Portuguese (Portugal) | +| tr | Turkish | +| bs-latn-ba | Bosnian (Latin, Bosnia and Herzegovina) | +| fi | Finnish | +| is | Icelandic | +| mk | Macedonian | +| quz-pe | Quechua (Peru) | +| tt | Tatar | +| ca-es-valencia | Catalan (Valencian) | +| fil-ph | Filipino (Philippines) | +| it | Italian | +| ml | Malayalam | +| ro | Romanian | +| ug | Uyghur | +| ca | Catalan | +| fr-ca | French (Canada) | +| ja | Japanese | +| mr | Marathi | +| ru | Russian | +| uk | Ukrainian | +| cs | Czech | +| fr | French | +| ka | Georgian | +| ms | Malay | +| sk | Slovak | +| ur | Urdu | +| cy-gb | Welsh (UK) | +| ga-ie | Irish (Ireland) | +| kk | Kazakh | +| mt-mt | Maltese (Malta) | +| sl | Slovenian | +| uz-latn-uz | Uzbek (Latin, Uzbekistan) | +| da | Danish | +| gd | Scottish Gaelic | +| km-kh | Khmer (Cambodia) | +| nb-no | Norwegian (Bokmål) | +| sq | Albanian | +| vi | Vietnamese | +| de | German | +| gl | Galician | +| kn | Kannada | +| ne-np | Nepali (Nepal) | +| sr-cyrl-ba | Serbian (Cyrillic, Bosnia and Herzegovina)| +| zh-cn | Chinese (Simplified) | +| el | Greek | +| gu | Gujarati | +| ko | Korean | +| nl | Dutch | +| sr-cyrl-rs | Serbian (Cyrillic, Serbia) | +| zh-tw | Chinese (Traditional) | diff --git a/docs/embedded/development/declarative-agent/spe-da.md b/docs/embedded/development/declarative-agent/spe-da.md new file mode 100644 index 000000000..d56f758d4 --- /dev/null +++ b/docs/embedded/development/declarative-agent/spe-da.md @@ -0,0 +1,155 @@ +--- +title: SharePoint Embedded copilots +description: Details copilots integration with SharePoint Embedded applications +ms.date: 02/19/2025 +ms.localizationpriority: high +--- + +# Overview + +> [!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 + +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 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). + +### Microsoft 365 Boundary + +Data is kept secure: data never leaves the tenant boundary and storage respects data residency settings. + +Each container instance of a container type in the SPE partition is its own security and compliance boundary. + +![M365 Storage Partitions](../../images/speco-bound.png) + +## How to use SharePoint Embedded copilots + +### 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. + +#### SPE TypeScript React Application + +Follow the [quick start guide](../tutorials/spe-da-vscode.md) to get started with a prebuilt sample application. + +### 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. + +## 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. + +***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.*** + +### Should I use a standard or trial container type? + +Once consumption-based billing is enabled, we will be disabling the use of 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. + +## SharePoint Embedded copilot Support + +### Chat Control Feedback Dialog + +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. + +When you click the thumbs down button, a feedback dialog will appear. Please include any relevant information in this dialog. + +![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. diff --git a/docs/embedded/development/tutorials/spe-da-vscode.md b/docs/embedded/development/tutorials/spe-da-vscode.md new file mode 100644 index 000000000..9c76f66f9 --- /dev/null +++ b/docs/embedded/development/tutorials/spe-da-vscode.md @@ -0,0 +1,354 @@ +--- +title: Sharepoint Embedded copilot Tutorial +description: Sharepoint Embedded copilot Tutorial with the SDK and the VS Code SharePoint Embedded Extension +ms.date: 02/27/2025 +ms.localizationpriority: high +--- + +# Tutorial for getting started with SharePoint Embedded copilot + +## Prerequisites + +> [!NOTE] +> +> 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) +> - 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. + +## Getting started using the SharePoint Embedded SDK + +### 1. Install the SDK into your React repo + +```console +# Install the SDK with npm + +npm install "https://download.microsoft.com/download/27d10531-b158-40c9-a146-af376c0e7f2a/microsoft-sharepointembedded-copilotchat-react-1.0.7.tgz" +``` + +#### If you want to verify checksums + +In MacOS/Linux + +```console +version="1.0.7"; + +url="https://download.microsoft.com/download/27d10531-b158-40c9-a146-af376c0e7f2a/microsoft-sharepointembedded-copilotchat-react-1.0.7.tgz"; + +expected_checksum="A87FF410E8684A3C16456B2092564422BF80DA9FAFF3A684821DACEAEEA23D22"; + +package_path="microsoft-sharepointembedded-copilotchat-react-$version.tgz"; + +curl -o $package_path $url && [ "$(sha256sum $package_path | awk '{ print $1 }')" == "$expected_checksum" ] && npm install $package_path || { echo "Checksum does not match. Aborting installation."; rm $package_path; } +``` + +In Windows: + +```powershell +$version = "1.0.7" +$url = "https://download.microsoft.com/download/27d10531-b158-40c9-a146-af376c0e7f2a/microsoft-sharepointembedded-copilotchat-react-1.0.7.tgz" +$expected_checksum = "A87FF410E8684A3C16456B2092564422BF80DA9FAFF3A684821DACEAEEA23D22" +$package_path = "microsoft-sharepointembedded-copilotchat-react-$version.tgz" + +Invoke-WebRequest -Uri $url -OutFile $package_path + +$calculated_checksum = Get-FileHash -Path $package_path -Algorithm SHA256 | Select-Object -ExpandProperty Hash + +if ($calculated_checksum -eq $expected_checksum) { + Write-Output "Checksum matches. Installing the package..." + npm install $package_path +} else { + Write-Output "Checksum does not match. Aborting installation." +} +Remove-Item $package_path +``` + +### 2. Create an `authProvider` object + +This is an object that matches this interface: + +```typescript +export interface IChatEmbeddedApiAuthProvider { + // The hostname for your tenant. Example: https://m365x10735106.sharepoint.com + hostname: string; + // This function will be called when an SPO token is required + // Scope needed: ${hostname}/Container.Selected + getToken(): Promise; +} +``` + +Example usage in app: + +```typescript +// In your app: +import { IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; + +const authProvider: IChatEmbeddedApiAuthProvider = { + hostname: 'https://m365x10735106.sharepoint.com', + getToken: requestSPOAccessToken, +}; +``` + +Example implementation of `getToken` (you need to customize it): + +```typescript +// +async function requestSPOAccessToken() { + // Use your app's actual msalConfig + const msalConfig = { + auth: { + clientId: "{Your Entra client ID}", // this can likely point to process.env.REACT_APP_CLIENT_ID if you have set it in your .env file + }, + cache: { + // https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/caching.md + /* + Cache Location | Cleared on | Shared between windows/tabs | Redirect flow supported + ----------------- ---------- ------------------------- ------------------------ + sessionStorage | window/tab close | No | Yes + localStorage | browser close | Yes | Yes + memoryStorage | page | refresh/navigation | No | No + */ + cacheLocation: 'localStorage', + storeAuthStateInCookie: false, + }, + }; + + const containerScopes = { + scopes: [`${authProvider.hostname}/Container.Selected`], + redirectUri: '/' + }; + + const pca = new msal.PublicClientApplication(msalConfig); + let containerTokenResponse; + + // Consent FileStorageContainer.Selected scope + try { + // attempt silent acquisition first + containerTokenResponse = await pca.acquireTokenSilent(containerScopes); + return containerTokenResponse.accessToken; + } catch (error) { + if (error instanceof InteractionRequiredAuthError) { + // fallback to interaction when silent call fails + containerTokenResponse = await pca.acquireTokenPopup(containerScopes); + return containerTokenResponse.accessToken; + } + else { + console.log(error); + } + } +} +``` + +### 3. Create a React state to store your `chatApi` in + +```typescript +const [chatApi, setChatApi] = React.useState(null); +``` + +Example: + +```typescript +import React from 'react'; +import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; + +//... +async function requestSPOAccessToken() { + //... +} + +const authProvider: IChatEmbeddedApiAuthProvider = { + hostname: 'https://m365x10735106.sharepoint.com', + getToken: requestSPOAccessToken, +}; + +function App() { + const [chatApi, setChatApi] = React.useState(null); + + return ( + //... + ); +} +``` + +### 4. Add the `ChatEmbedded` component into your react app + +```typescript +import React from 'react'; +import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; + +//... +async function requestSPOAccessToken() { + //... +} + +const authProvider: IChatEmbeddedApiAuthProvider = { + hostname: 'https://m365x10735106.sharepoint.com', + getToken: requestSPOAccessToken, +}; + +function App() { + const [chatApi, setChatApi] = React.useState(null); + + return ( + //... + + //... + ); +} +``` + +### 5. Use the `chatApi` object in your state to open the chat and run it + +In the example above, call it this way to open the chat. + +```typescript +await chatApi.openChat(); +``` + +You may choose to pass in launch configurations + +```typescript +import { IconName, IconStyle } from './sdk/types'; + +//... +const zeroQueryPrompts = { + headerText: "This is my Starter Prompt", + promptSuggestionList: [{ + suggestionText: 'Hello', + iconRegular: { name: IconName.ChatBubblesQuestion, style: IconStyle.Regular }, + iconHover: { name: IconName.ChatBubblesQuestion, style: IconStyle.Filled }, + }] +}; + +const launchConfig: ChatLaunchConfig = { + header: 'My Awesome Chat', + zeroQueryPrompts, + suggestedPrompts: ["What are my files?",], + instruction: "Response must be in the tone of a pirate", + locale: "en", +}; + +await chatApi.openChat(launchConfig); +``` + +Full example: + +```typescript +import React from 'react'; +import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; + +//... +async function requestSPOAccessToken() { + //... +} + +const authProvider: IChatEmbeddedApiAuthProvider = { + hostname: 'https://m365x10735106.sharepoint.com', + getToken: requestSPOAccessToken, +}; + +function App() { + const [chatApi, setChatApi] = React.useState(null); + + React.useEffect(() => { + const openChat = async () => { + if (!chatApi) { + return; + } + + await chatApi.openChat(); + }; + + openChat(); + }, [chatApi]); + + + return ( + //... + setChatApi(api)} + authProvider={authProvider} + containerId={container.id} + style={{ width: 'calc(100% - 4px)', height: 'calc(100vh - 8px)' }} + /> + //... + ); +} +``` + +### 6. Your AI chat should be loaded successfully + +## Getting started using the SharePoint Embedded Visual Studio Code Extension + +### 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). + +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` + + ![Using the SPE VS Code extension to create a TypeScript React Azure Functions project](../../images/speco-runsampleapp.png) + +1. Allow for the extension to copy and create client secrets + + > [!CAUTION] + > Caution for production environments, storing secrets in plain text poses a security risk. + + ![SPE VS Code notification alerting it will copy app secrets in plain text on local machine](../../images/speco-createappsecret.png) + + If the application does not already have a client secret, the extension will ask to create one for you. + + ![SPE VS Code notification prompting user to allow it to create a secret for the application if it does not exist.](../../images/speco-createclientsecret.png) + +1. Select a folder to host the application, this will clone the following [repository for SharePoint Embedded Samples](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Samples/spe-typescript-react-azurefunction) into the folder + + ![windows File Explorer folder to save project on local machine](../../images/speco-cloneproject.png) + + Next, when prompted, open the folder + + ![VS Code extension with the SPE React Typescript + Azure Functions sample application cloned on local machine and open in VS Code](../../images/speco-vscodeclonedproject.png) + +1. Navigate to `react-client\src\components\ChatSideBar.tsx` and uncomment this section + + ![VS Code file explorer with ChatSideBar.tsx in open window with relevant code to uncomment highlighted](../../images/speco-uncommentchatsidebar.png) + +1. Navigate to `react-client\src\routes\App.tsx` and set the react state of the showSidebar variable to `true` + + ![VS Code file explorer with App.tsx open with line of showSidebar variable useState function input changed from false to true to enable showing chat side bar](../../images/speco-setshowsidebartrue.png) + +1. You can follow the instructions of the `README.md` file in the root of the project for further npm commands. Run `npm run start` in the root of the project to start your application with the SPE copilot functionality enabled. + + > [!NOTE] + > `npm run start` Should be done in the root folder of the sample project. `\SharePoint-Embedded-Samples\Samples\spe-typescript-react-azurefunction` + + ![VS Code terminal in root folder of SPE Typescript project cloned earlier and npm run start command typed in](../../images/speco-runnpmrunstart.png) + +1. Sign in with a user who has an M365 Copilot license enabled. + + ![SPE Typescript App running in Edge with sign in buttons](../../images/speco-reacttypescripthomepage.png) + +1. Navigate to the `containers` page, create one if you do not have any yet + + ![SPE Typescript App running in edge in /containers sub page with modal of user c reatign a container called ContosoCompanyContainer](../../images/speco-createcontosocontainer2.png) + + After it has been created, you will see it here: + + ![SPE Typescript App running in edge with a created container from above ContosoCompanyContainer](../../images/speco-createdcontainer.png) + +1. Click the container and upload your files. Once a container has been created and you have navigated inside it, your copilot chat experience will become enabled. + + ![SPE Typescript App running in edge inside a created container page of ContosoCompanyContainer](../../images/speco-spechatenabled.png) + +### Examples + +The [SharePoint Embedded Samples](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Samples/spe-typescript-react-azurefunction) repository has examples for how to use SharePoint Embedded in your custom applications. diff --git a/docs/embedded/images/speco-aivalue.png b/docs/embedded/images/speco-aivalue.png new file mode 100644 index 000000000..6021c9407 Binary files /dev/null and b/docs/embedded/images/speco-aivalue.png differ diff --git a/docs/embedded/images/speco-apparch.png b/docs/embedded/images/speco-apparch.png new file mode 100644 index 000000000..ec05874da Binary files /dev/null and b/docs/embedded/images/speco-apparch.png differ diff --git a/docs/embedded/images/speco-appscopingvenn.png b/docs/embedded/images/speco-appscopingvenn.png new file mode 100644 index 000000000..d5727486a Binary files /dev/null and b/docs/embedded/images/speco-appscopingvenn.png differ diff --git a/docs/embedded/images/speco-bound.png b/docs/embedded/images/speco-bound.png new file mode 100644 index 000000000..8f3cff455 Binary files /dev/null and b/docs/embedded/images/speco-bound.png differ diff --git a/docs/embedded/images/speco-cloneproject.png b/docs/embedded/images/speco-cloneproject.png new file mode 100644 index 000000000..4573bdc74 Binary files /dev/null and b/docs/embedded/images/speco-cloneproject.png differ diff --git a/docs/embedded/images/speco-createappsecret.png b/docs/embedded/images/speco-createappsecret.png new file mode 100644 index 000000000..b283b8259 Binary files /dev/null and b/docs/embedded/images/speco-createappsecret.png differ diff --git a/docs/embedded/images/speco-createclientsecret.png b/docs/embedded/images/speco-createclientsecret.png new file mode 100644 index 000000000..37cf20e57 Binary files /dev/null and b/docs/embedded/images/speco-createclientsecret.png differ diff --git a/docs/embedded/images/speco-createcontosocontainer2.png b/docs/embedded/images/speco-createcontosocontainer2.png new file mode 100644 index 000000000..995cd7f88 Binary files /dev/null and b/docs/embedded/images/speco-createcontosocontainer2.png differ diff --git a/docs/embedded/images/speco-createdcontainer.png b/docs/embedded/images/speco-createdcontainer.png new file mode 100644 index 000000000..e429321c4 Binary files /dev/null and b/docs/embedded/images/speco-createdcontainer.png differ diff --git a/docs/embedded/images/speco-feedbackcombined.png b/docs/embedded/images/speco-feedbackcombined.png new file mode 100644 index 000000000..c3d95ef63 Binary files /dev/null and b/docs/embedded/images/speco-feedbackcombined.png differ diff --git a/docs/embedded/images/speco-feedbackmodal.png b/docs/embedded/images/speco-feedbackmodal.png new file mode 100644 index 000000000..ef3b9ab51 Binary files /dev/null and b/docs/embedded/images/speco-feedbackmodal.png differ diff --git a/docs/embedded/images/speco-feedbackthumbsdown.png b/docs/embedded/images/speco-feedbackthumbsdown.png new file mode 100644 index 000000000..d9e3bd0f5 Binary files /dev/null and b/docs/embedded/images/speco-feedbackthumbsdown.png differ diff --git a/docs/embedded/images/speco-ragai.png b/docs/embedded/images/speco-ragai.png new file mode 100644 index 000000000..28b3f3eac Binary files /dev/null and b/docs/embedded/images/speco-ragai.png differ diff --git a/docs/embedded/images/speco-ragm365.png b/docs/embedded/images/speco-ragm365.png new file mode 100644 index 000000000..17a016ff8 Binary files /dev/null and b/docs/embedded/images/speco-ragm365.png differ diff --git a/docs/embedded/images/speco-ragquery.png b/docs/embedded/images/speco-ragquery.png new file mode 100644 index 000000000..b8a52311b Binary files /dev/null and b/docs/embedded/images/speco-ragquery.png differ diff --git a/docs/embedded/images/speco-reacttypescripthomepage.png b/docs/embedded/images/speco-reacttypescripthomepage.png new file mode 100644 index 000000000..b25861791 Binary files /dev/null and b/docs/embedded/images/speco-reacttypescripthomepage.png differ diff --git a/docs/embedded/images/speco-runnpmrunstart.png b/docs/embedded/images/speco-runnpmrunstart.png new file mode 100644 index 000000000..1f26f6395 Binary files /dev/null and b/docs/embedded/images/speco-runnpmrunstart.png differ diff --git a/docs/embedded/images/speco-runsampleapp.png b/docs/embedded/images/speco-runsampleapp.png new file mode 100644 index 000000000..3d3341eaf Binary files /dev/null and b/docs/embedded/images/speco-runsampleapp.png differ diff --git a/docs/embedded/images/speco-setshowsidebartrue.png b/docs/embedded/images/speco-setshowsidebartrue.png new file mode 100644 index 000000000..2b73eac96 Binary files /dev/null and b/docs/embedded/images/speco-setshowsidebartrue.png differ diff --git a/docs/embedded/images/speco-spechatenabled.png b/docs/embedded/images/speco-spechatenabled.png new file mode 100644 index 000000000..87f35bb1b Binary files /dev/null and b/docs/embedded/images/speco-spechatenabled.png differ diff --git a/docs/embedded/images/speco-uncommentchatsidebar.png b/docs/embedded/images/speco-uncommentchatsidebar.png new file mode 100644 index 000000000..ccc7cfd46 Binary files /dev/null and b/docs/embedded/images/speco-uncommentchatsidebar.png differ diff --git a/docs/embedded/images/speco-vscodeclonedproject.png b/docs/embedded/images/speco-vscodeclonedproject.png new file mode 100644 index 000000000..c88e78db4 Binary files /dev/null and b/docs/embedded/images/speco-vscodeclonedproject.png differ diff --git a/docs/embedded/images/speco-vscodeextensiondisablediscovery.png b/docs/embedded/images/speco-vscodeextensiondisablediscovery.png new file mode 100644 index 000000000..d1c9d63d2 Binary files /dev/null and b/docs/embedded/images/speco-vscodeextensiondisablediscovery.png differ diff --git a/docs/toc.yml b/docs/toc.yml index 40a5952cd..3c530d30a 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -588,6 +588,8 @@ 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 @@ -616,6 +618,12 @@ href: /training/modules/sharepoint-embedded-setup - name: SharePoint Embedded - building applications href: /training/modules/sharepoint-embedded-create-app + - name: Sharepoint Embedded copilot ( Private Preview ) + items: + - name: Sharepoint Embedded copilot ( Private Preview ) + href: embedded/development/declarative-agent/spe-da.md + - name: Sharepoint Embedded copilot Advanced Topics + href: embedded/development/declarative-agent/spe-da-adv.md - name: Microsoft Teams items: - name: Overview