diff --git a/samples/da-sharepoint-data-manager/.gitignore b/samples/da-sharepoint-data-manager/.gitignore new file mode 100644 index 000000000..e56779951 --- /dev/null +++ b/samples/da-sharepoint-data-manager/.gitignore @@ -0,0 +1,13 @@ +# TeamsFx files +env/.env.*.user +env/.env.local +.localConfigs +appPackage/build + +# dependencies +node_modules/ + +# misc +.env +.deployment +.DS_Store diff --git a/samples/da-sharepoint-data-manager/.vscode/extensions.json b/samples/da-sharepoint-data-manager/.vscode/extensions.json new file mode 100644 index 000000000..aac0a6e34 --- /dev/null +++ b/samples/da-sharepoint-data-manager/.vscode/extensions.json @@ -0,0 +1,5 @@ +{ + "recommendations": [ + "TeamsDevApp.ms-teams-vscode-extension" + ] +} diff --git a/samples/da-sharepoint-data-manager/.vscode/launch.json b/samples/da-sharepoint-data-manager/.vscode/launch.json new file mode 100644 index 000000000..a4d4fb37d --- /dev/null +++ b/samples/da-sharepoint-data-manager/.vscode/launch.json @@ -0,0 +1,35 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Preview in Copilot (Edge)", + "type": "msedge", + "request": "launch", + "url": "https://m365.cloud.microsoft/chat/entity1-d870f6cd-4aa5-4d42-9626-ab690c041429/${agent-hint}?auth=2&developerMode=Basic", + "presentation": { + "group": "remote", + "order": 1 + }, + "internalConsoleOptions": "neverOpen", + "runtimeArgs": [ + "--remote-debugging-port=9222", + "--no-first-run" + ] + }, + { + "name": "Preview in Copilot (Chrome)", + "type": "chrome", + "request": "launch", + "url": "https://m365.cloud.microsoft/chat/entity1-d870f6cd-4aa5-4d42-9626-ab690c041429/${agent-hint}?auth=2&developerMode=Basic", + "presentation": { + "group": "remote", + "order": 2 + }, + "internalConsoleOptions": "neverOpen", + "runtimeArgs": [ + "--remote-debugging-port=9223", + "--no-first-run" + ] + } + ] +} diff --git a/samples/da-sharepoint-data-manager/.vscode/settings.json b/samples/da-sharepoint-data-manager/.vscode/settings.json new file mode 100644 index 000000000..429962025 --- /dev/null +++ b/samples/da-sharepoint-data-manager/.vscode/settings.json @@ -0,0 +1,11 @@ +{ + "debug.onTaskErrors": "abort", + "json.schemas": [ + { + "fileMatch": [ + "/aad.*.json" + ], + "schema": {} + } + ] +} diff --git a/samples/da-sharepoint-data-manager/README.md b/samples/da-sharepoint-data-manager/README.md new file mode 100644 index 000000000..875ddb013 --- /dev/null +++ b/samples/da-sharepoint-data-manager/README.md @@ -0,0 +1,61 @@ +# Data Manager + +## Summary + +A declarative agent for Microsoft 365 Copilot that helps users manage and organize their SharePoint sites and OneDrive content. The agent leverages OneDrive and SharePoint access, Microsoft Learn MCP integration for official documentation, and GraphicArt for visual diagrams to provide document search, organization guidance, and best practices for content management. + +![Data Manager in action](./assets/example_response.png) + +## Contributors + +* [Kateryna Turuntseva](https://github.com/KatT-AI) + +## Version history + +Version|Date|Author|Comments +-------|----|----|-------- +1.0|May 19, 2025|Kateryna Turuntseva|Initial release + +## Prerequisites + +* [Microsoft 365 tenant with Microsoft 365 Copilot](https://learn.microsoft.com/microsoft-365-copilot/extensibility/prerequisites#prerequisites) +* [Node.js](https://nodejs.org/), supported versions: 18, 20, 22 +* [Microsoft 365 Agents Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) + +## Minimal path to awesome + +* Clone this repository (or [download this solution as a .ZIP file](https://pnp.github.io/download-partial/?url=https://github.com/pnp/copilot-pro-dev-samples/tree/main/samples/da-sharepoint-data-manager) then unzip it) +* Open the `samples/da-sharepoint-data-manager` folder with Visual Studio Code +* Select the **Microsoft 365 Agents Toolkit** icon on the left in the VS Code toolbar +* In the **Account** section, sign in with your [Microsoft 365 account](https://docs.microsoft.com/microsoftteams/platform/toolkit/accounts) if you haven't already +* Create Teams app by selecting **Provision** in the **Lifecycle** section +* Select **Preview in Copilot (Edge)** or **Preview in Copilot (Chrome)** from the launch configuration dropdown +* Once the Copilot app is loaded in the browser, select the "..." menu and select **Copilot chats**. You will see your Data Manager agent on the right rail. Selecting it will change the experience to showcase the logo and name of your data management agent +* Ask questions about your SharePoint content, and the agent will help you manage and organize your data + +## Features + +This declarative agent illustrates the following concepts: + +* **Document Search** - Search across SharePoint sites and libraries, filter by content and metadata, discover relevant documents +* **File Organization** - Smart folder structure suggestions, metadata tagging and classification advice, content type recommendations +* **Document Management Guidance** - Best practices for document organization, SharePoint organization strategies, content classification recommendations +* **Microsoft Learn MCP Integration** - Search and fetch official Microsoft documentation via the Model Context Protocol (MCP) for accurate, up-to-date SharePoint and Microsoft 365 guidance with source citations +* **Visual Diagrams** - Generate diagrams and visual representations of site structures, folder hierarchies, and information architecture using GraphicArt +* **Grounded Responses** - Uses `discourage_model_knowledge` behavior override to prioritize user data and official documentation over general model knowledge + +## Help + +We do not support samples, but this community is always willing to help, and we want to improve these samples. We use GitHub to track issues, which makes it easy for community members to volunteer their time and help resolve issues. + +You can try looking at [issues related to this sample](https://github.com/pnp/copilot-pro-dev-samples/issues?q=label%3A%22sample%3A%20da-sharepoint-data-manager%22) to see if anybody else is having the same issues. + +If you encounter any issues using this sample, [create a new issue](https://github.com/pnp/copilot-pro-dev-samples/issues/new). + +Finally, if you have an idea for improvement, [make a suggestion](https://github.com/pnp/copilot-pro-dev-samples/issues/new). + +## Disclaimer + +**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.** + +![](https://m365-visitor-stats.azurewebsites.net/copilot-pro-dev-samples/samples/da-sharepoint-data-manager) diff --git a/samples/da-sharepoint-data-manager/appPackage/ai-plugin.json b/samples/da-sharepoint-data-manager/appPackage/ai-plugin.json new file mode 100644 index 000000000..03bba7336 --- /dev/null +++ b/samples/da-sharepoint-data-manager/appPackage/ai-plugin.json @@ -0,0 +1,55 @@ +{ + "$schema": "https://aka.ms/json-schemas/copilot-extensions/v2.1/plugin.schema.json", + "schema_version": "v2.4", + "name_for_human": "Microsoft Learn Search", + "description_for_human": "Search official Microsoft documentation for SharePoint and Microsoft 365 guidance", + "contact_email": "publisher-email@example.com", + "namespace": "microsoftlearnsearch", + "functions": [ + { + "name": "microsoft_docs_search", + "description": "Search official Microsoft documentation to find relevant content about SharePoint, OneDrive, Microsoft 365, and content management. Returns up to 10 content chunks from Microsoft Learn and other official sources. Use this tool when the user asks about SharePoint features, best practices, or Microsoft 365 capabilities.", + "parameters": { + "type": "object", + "properties": { + "query": { + "description": "A query about Microsoft 365, SharePoint, OneDrive, or content management topics", + "type": "string" + } + }, + "required": [ + "query" + ] + } + }, + { + "name": "microsoft_docs_fetch", + "description": "Fetch and convert a Microsoft Learn documentation page to markdown format. Use this tool after microsoft_docs_search when you identify a specific page that needs complete content for a detailed answer.", + "parameters": { + "type": "object", + "properties": { + "url": { + "description": "URL of the Microsoft documentation page to read", + "type": "string" + } + }, + "required": [ + "url" + ] + } + } + ], + "runtimes": [ + { + "type": "RemoteMCPServer", + "spec": { + "url": "https://learn.microsoft.com/api/mcp", + "enable_dynamic_discovery": false + }, + "run_for_functions": [ + "microsoft_docs_search", + "microsoft_docs_fetch" + ] + } + ] +} diff --git a/samples/da-sharepoint-data-manager/appPackage/color.png b/samples/da-sharepoint-data-manager/appPackage/color.png new file mode 100644 index 000000000..01aa37e34 Binary files /dev/null and b/samples/da-sharepoint-data-manager/appPackage/color.png differ diff --git a/samples/da-sharepoint-data-manager/appPackage/declarativeAgent.json b/samples/da-sharepoint-data-manager/appPackage/declarativeAgent.json new file mode 100644 index 000000000..24c531d66 --- /dev/null +++ b/samples/da-sharepoint-data-manager/appPackage/declarativeAgent.json @@ -0,0 +1,55 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json", + "version": "v1.5", + "name": "DataManager", + "description": "A declarative agent that helps users manage and organize SharePoint and OneDrive content with document search, organization guidance, and access to official Microsoft documentation via MCP.", + "instructions": "$[file('instruction.txt')]", + "behavior_overrides": { + "special_instructions": { + "discourage_model_knowledge": true + } + }, + "capabilities": [ + { + "name": "OneDriveAndSharePoint" + }, + { + "name": "GraphicArt" + } + ], + "disclaimer": { + "text": "This declarative agent is provided as is without warranty of any kind, either express or implied, including any implied warranties of fitness for a particular purpose, merchantability, or non-infringement." + }, + "conversation_starters": [ + { + "title": "Organize files", + "text": "Help me organize my files in SharePoint" + }, + { + "title": "Folder structure", + "text": "Suggest a folder structure for my documents" + }, + { + "title": "Naming conventions", + "text": "What are best practices for document naming in SharePoint?" + }, + { + "title": "Metadata tips", + "text": "Show me how to use metadata in SharePoint" + }, + { + "title": "Search docs", + "text": "Search Microsoft documentation for SharePoint content types" + }, + { + "title": "Visualize structure", + "text": "Create a diagram of a recommended SharePoint site structure" + } + ], + "actions": [ + { + "id": "action_1", + "file": "ai-plugin.json" + } + ] +} diff --git a/samples/da-sharepoint-data-manager/appPackage/instruction.txt b/samples/da-sharepoint-data-manager/appPackage/instruction.txt new file mode 100644 index 000000000..66530a301 --- /dev/null +++ b/samples/da-sharepoint-data-manager/appPackage/instruction.txt @@ -0,0 +1,41 @@ +You are a Microsoft 365 Data Management Agent, specialized in helping users organize and find information in their SharePoint sites and Microsoft 365 content. + +# Skills and capabilities: +- Search for documents across SharePoint sites and libraries based on content and metadata +- Suggest organization strategies for files and document libraries +- Provide best practices for metadata tagging and classification +- Suggest appropriate folder structures and content organization +- Offer guidance on document naming conventions and organization +- Help users find specific content in their SharePoint environment +- Search official Microsoft documentation via Microsoft Learn for accurate, up-to-date guidance +- Generate diagrams and visual representations of site structures and information architecture + +# Tool usage: +- Use microsoft_docs_search to find official Microsoft guidance on SharePoint features, best practices, content types, or Microsoft 365 capabilities +- When the user's M365 files do not contain enough information to answer the question — use microsoft_docs_search as a fallback instead of stopping or apologizing +- After microsoft_docs_search returns results, use microsoft_docs_fetch on the most relevant page URLs to retrieve full content and exact source links +- When you get results from Microsoft Learn, use them to enrich and optimize your response: + - Structure your recommendations based on official Microsoft guidance + - Adapt general best practices to the user's specific scenario and their existing SharePoint content + - Provide step-by-step instructions grounded in official documentation rather than general knowledge + - Include a "Sources" section at the end of your response with direct clickable URLs to the Microsoft Learn pages you used (e.g. https://learn.microsoft.com/sharepoint/...) +- Use GraphicArt to create diagrams when the user needs visual representations of site structures, folder hierarchies, or information architecture + +# Guidelines: +- Always prioritize information security and data privacy in your recommendations +- When helping with file organization, focus on best practices for document management in SharePoint +- Provide clear, step-by-step instructions when explaining SharePoint operations +- Leverage SharePoint's metadata and content type capabilities for advanced organization +- Always respect organizational content management policies +- Remember that you cannot modify permissions, create reports on site usage, or implement data governance policies - only provide guidance and best practices +- Always ground your answers in official Microsoft documentation rather than relying on general knowledge +- When the user's M365 files do not contain relevant information, do NOT apologize and stop — instead, proactively search Microsoft Learn to provide best-practice guidance + +# Response format: +- Provide concise, actionable responses +- When listing documents or sites, format as a clear table with relevant metadata +- For complex processes, break down into numbered steps +- When appropriate, suggest both immediate actions and long-term strategies +- If additional context is needed to assist the user, ask clarifying questions first +- Include links to specific documents, sites, or settings when available +- When providing information from Microsoft Learn, always end your response with a "Sources" section listing the direct URLs to the pages you referenced diff --git a/samples/da-sharepoint-data-manager/appPackage/manifest.json b/samples/da-sharepoint-data-manager/appPackage/manifest.json new file mode 100644 index 000000000..21e85a1cf --- /dev/null +++ b/samples/da-sharepoint-data-manager/appPackage/manifest.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.24/MicrosoftTeams.schema.json", + "manifestVersion": "1.24", + "version": "1.0.0", + "id": "${{TEAMS_APP_ID}}", + "developer": { + "name": "Teams App, Inc.", + "websiteUrl": "https://www.example.com", + "privacyUrl": "https://www.example.com/privacy", + "termsOfUseUrl": "https://www.example.com/termofuse" + }, + "icons": { + "color": "color.png", + "outline": "outline.png" + }, + "name": { + "short": "DataManager${{APP_NAME_SUFFIX}}", + "full": "Microsoft 365 Data Management Agent" + }, + "description": { + "short": "A content organization assistant for Microsoft 365", + "full": "This agent helps users organize and find documents in their SharePoint sites and Microsoft 365 content. It provides search assistance, organization suggestions, and best practices. The agent can search the web for reference information but cannot modify permissions, create analytics reports, or implement governance policies - it only provides guidance and recommendations." + }, + "accentColor": "#FFFFFF", + "composeExtensions": [], + "permissions": [ + "identity", + "messageTeamMembers" + ], + "copilotAgents": { + "declarativeAgents": [ + { + "id": "declarativeAgent", + "file": "declarativeAgent.json" + } + ] + }, + "validDomains": [] +} diff --git a/samples/da-sharepoint-data-manager/appPackage/outline.png b/samples/da-sharepoint-data-manager/appPackage/outline.png new file mode 100644 index 000000000..f7a4c8644 Binary files /dev/null and b/samples/da-sharepoint-data-manager/appPackage/outline.png differ diff --git a/samples/da-sharepoint-data-manager/assets/example_response.png b/samples/da-sharepoint-data-manager/assets/example_response.png new file mode 100644 index 000000000..d610416e9 Binary files /dev/null and b/samples/da-sharepoint-data-manager/assets/example_response.png differ diff --git a/samples/da-sharepoint-data-manager/assets/prompts.png b/samples/da-sharepoint-data-manager/assets/prompts.png new file mode 100644 index 000000000..c9dbbf870 Binary files /dev/null and b/samples/da-sharepoint-data-manager/assets/prompts.png differ diff --git a/samples/da-sharepoint-data-manager/assets/sample.json b/samples/da-sharepoint-data-manager/assets/sample.json new file mode 100644 index 000000000..0deaf0b87 --- /dev/null +++ b/samples/da-sharepoint-data-manager/assets/sample.json @@ -0,0 +1,63 @@ +[ + { + "name": "pnp-copilot-pro-dev-da-sharepoint-data-manager", + "source": "pnp", + "title": "Data Manager - Declarative Agent for SharePoint", + "shortDescription": "A declarative agent that helps users manage and organize SharePoint and OneDrive content with document search, organization guidance, and access to official Microsoft documentation via MCP.", + "url": "https://github.com/pnp/copilot-pro-dev-samples/tree/main/samples/da-sharepoint-data-manager", + "downloadUrl": "https://pnp.github.io/download-partial/?url=https://github.com/pnp/copilot-pro-dev-samples/tree/main/samples/da-sharepoint-data-manager", + "longDescription": [ + "A declarative agent that helps users manage and organize SharePoint and OneDrive content with document search, organization guidance, and access to official Microsoft documentation via MCP. Features include Microsoft Learn search and fetch via Model Context Protocol, GraphicArt diagram generation, and grounded responses using behavior overrides." + ], + "creationDateTime": "2025-05-19", + "updateDateTime": "2025-05-20", + "products": [ + "Microsoft 365 Copilot" + ], + "metadata": [ + { + "key": "PLATFORM", + "value": "Copilot" + }, + { + "key": "LANGUAGE", + "value": "JSON" + }, + { + "key": "API-PLUGIN", + "value": "Yes" + }, + { + "key": "GRAPH-CONNECTOR", + "value": "No" + } + ], + "thumbnails": [ + { + "type": "image", + "order": 100, + "url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/refs/heads/main/samples/da-sharepoint-data-manager/assets/example_response.png", + "alt": "Data Manager agent helping organize SharePoint content" + } + ], + "authors": [ + { + "gitHubAccount": "KatT-AI", + "pictureUrl": "https://github.com/KatT-AI.png", + "name": "Kateryna Turuntseva" + } + ], + "references": [ + { + "name": "Microsoft 365 Copilot extensibility", + "description": "Learn more about what Microsoft 365 Copilot and how you can extend it.", + "url": "https://learn.microsoft.com/microsoft-365-copilot/extensibility/" + }, + { + "name": "Build declarative agents for Microsoft 365 Copilot", + "description": "Learn more about declarative agents for Microsoft 365 Copilot.", + "url": "https://learn.microsoft.com/microsoft-365-copilot/extensibility/overview-declarative-agent" + } + ] + } +] diff --git a/samples/da-sharepoint-data-manager/env/.env.dev b/samples/da-sharepoint-data-manager/env/.env.dev new file mode 100644 index 000000000..426aafa60 --- /dev/null +++ b/samples/da-sharepoint-data-manager/env/.env.dev @@ -0,0 +1,11 @@ +# This file includes environment variables that will be committed to git by default. + +# Built-in environment variables +TEAMSFX_ENV=dev +APP_NAME_SUFFIX=dev + +# Generated during provision, you can also add your own variables. +TEAMS_APP_ID= +TEAMS_APP_TENANT_ID= +M365_TITLE_ID= +M365_APP_ID= diff --git a/samples/da-sharepoint-data-manager/teamsapp.yml b/samples/da-sharepoint-data-manager/teamsapp.yml new file mode 100644 index 000000000..dbd6b9ee9 --- /dev/null +++ b/samples/da-sharepoint-data-manager/teamsapp.yml @@ -0,0 +1,81 @@ +# yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.8/yaml.schema.json +# Visit https://aka.ms/teamsfx-v5.0-guide for details on this file +# Visit https://aka.ms/teamsfx-actions for details on actions +version: v1.8 + +environmentFolderPath: ./env + +# Triggered when 'teamsapp provision' is executed +provision: + # Creates a Teams app + - uses: teamsApp/create + with: + # Teams app name + name: DataManager${{APP_NAME_SUFFIX}} + # Write the information of created resources into environment file for + # the specified environment variable(s). + writeToEnvironmentFile: + teamsAppId: TEAMS_APP_ID + + # Build Teams app package with latest env value + - uses: teamsApp/zipAppPackage + with: + # Path to manifest template + manifestPath: ./appPackage/manifest.json + outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + outputFolder: ./appPackage/build + # Validate app package using validation rules + - uses: teamsApp/validateAppPackage + with: + # Relative path to this file. This is the path for built zip file. + appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + # Apply the Teams app manifest to an existing Teams app in + # Teams Developer Portal. + # Will use the app id in manifest file to determine which Teams app to update. + - uses: teamsApp/update + with: + # Relative path to this file. This is the path for built zip file. + appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + # Extend your Teams app to Outlook and the Microsoft 365 app + - uses: teamsApp/extendToM365 + with: + # Relative path to the build app package. + appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + # Write the information of created resources into environment file for + # the specified environment variable(s). + writeToEnvironmentFile: + titleId: M365_TITLE_ID + appId: M365_APP_ID + +# Triggered when 'teamsapp publish' is executed +publish: + # Build Teams app package with latest env value + - uses: teamsApp/zipAppPackage + with: + # Path to manifest template + manifestPath: ./appPackage/manifest.json + outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + outputFolder: ./appPackage/build + # Validate app package using validation rules + - uses: teamsApp/validateAppPackage + with: + # Relative path to this file. This is the path for built zip file. + appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + # Apply the Teams app manifest to an existing Teams app in + # Teams Developer Portal. + # Will use the app id in manifest file to determine which Teams app to update. + - uses: teamsApp/update + with: + # Relative path to this file. This is the path for built zip file. + appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + # Publish the app to + # Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps) + # for review and approval + - uses: teamsApp/publishAppPackage + with: + appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip + # Write the information of created resources into environment file for + # the specified environment variable(s). + writeToEnvironmentFile: + publishedAppId: TEAMS_APP_PUBLISHED_APP_ID +projectId: 6e4e05ca-4d39-4b0d-b769-61340e6468f3