Merge pull request #796 from LeonArmston/LeonArmston-SPAgents-Config-…

…Creation New Sample: Dynamically Create .agent file for SharePoint Agents
pnp · Jan 15, 2025 · 2ba3a98 · 2ba3a98
2 parents 604f8ae + eb7f08b
commit 2ba3a98
Show file tree

Hide file tree

Showing 4 changed files with 309 additions and 0 deletions.
diff --git a/scripts/spo-dev-agent-config-creation/README.md b/scripts/spo-dev-agent-config-creation/README.md
@@ -0,0 +1,250 @@
+---
+plugin: add-to-gallery
+---
+
+# Creating SharePoint Agents (.agent Files) with PowerShell
+
+## Summary
+
+I have written a script to automate the creation of .agent files which you can then add to your sites & libraries. In the script you can then specify the details for the copilot i.e. name, welcome message, starter prompts & sources for the agent i.e. specific files, folders, libraries or sites that the agent is then grounded on. The script uses search to find the site ids, web ids and unique Ids of documents.
+
+![Example Screenshot](assets/preview.png)
+
+
+**Minimum Steps To Success**
+
+* Enter a URL of a SharePoint site you have access to.
+* Run the script (you will be asked for the following:)
+  * Name of the SharePoint Agent
+  * Description of the Agent
+  * Custom welcome message for the Agent
+  * Instructions for the Agent
+  * Enter at least one Starter Prompt i.e "How can you help me?"
+  * Enter at least one SharePoint source (File, Folder, Library or Site)
+* Add created <Agent Name>.agent file to /SiteAssets/Copilots folder.
+
+Further details on my [blog article](https://www.leonarmston.com/2025/01/creating-sharepoint-agents-with-powershell/) (External Site)
+
+### Prerequisites
+
+Account that runs the script needs access to all of the locations where the files, folders, libraries or sites to be used in the agent are located.
+
+# [PnP PowerShell](#tab/pnpps)
+
+```powershell
+$url = "https://contoso.sharepoint.com/sites/Syntex"
+
+
+Connect-PnPOnline -Url $url -Interactive
+
+# Function to prompt user for conversation starters
+function Get-ConversationStarters {
+    $conversationStarters = @()
+    while ($true) {
+        $text = Read-Host "Enter a starter prompt (or press Enter to finish)"
+        if ($text -eq "" -and $conversationStarters.Count -eq 0) {
+            Write-Host "You must enter at least one starter prompt."
+        } elseif ($text -eq "") {
+            break
+        } else {
+            $conversationStarters += @{ text = $text }
+        }
+    }
+    return $conversationStarters
+}
+
+# Function to prompt user for capabilities
+function Get-Capabilities {
+    $items_by_sharepoint_ids = @()
+    $items_by_url = @()
+    while ($true) {
+        $type = Read-Host "Enter capability type (File, Site, Library, Folder) (or press Enter to finish)"
+        $path = Read-Host "Enter path (or press Enter to finish)"
+        if ($type -eq "" -or $path -eq "") { break }
+
+        switch ($type) {
+            "File" {
+
+                <#{
+                    "list_id": "50f033bf-f372-48ac-8bd6-6af3f421a1c6",
+                    "name": "PnP Recognition Letter - Leon.pdf",
+                    "site_id": "18dfc66a-2fa5-4b83-adf5-8726b62a6861",
+                    "type": "File",
+                    "unique_id": "9328a5ca-dd8e-4e46-a51e-782e53d7275d",
+                    "url": "https://leonarmstonmvp.sharepoint.com/sites/Syntex/Shared%20Documents/PnP%20Recognition%20Letter%20-%20Leon.pdf",
+                    "web_id": "b0224f93-49be-4957-8e22-edbb489c937e"
+                }#>
+
+                $searchQuery = Submit-PnPSearchQuery -Query "Path:`"$path`"" -All -SelectProperties "ListId","FileType","SiteTitle","IdentityListItemId","Path","IdentityWebId"
+
+
+                $capability = @{
+                    list_id = $searchQuery.ResultRows[0].ListId
+                    name = $searchQuery.ResultRows[0].OriginalPath.Split("/")[-1]
+                    site_id = $searchQuery.ResultRows[0].IdentitySiteCollectionId
+                    type = $type
+                    unique_id = $searchQuery.ResultRows[0].IdentityListItemId
+                    url = $searchQuery.ResultRows[0].Path
+                    web_id = $searchQuery.ResultRows[0].IdentityWebId
+                }
+                $items_by_sharepoint_ids += $capability
+            }
+            "Site" {
+                <#{
+                    "list_id": "00000000-0000-0000-0000-000000000000",
+                    "name": "Projects Hub",
+                    "site_id": "171f7026-6c47-45ce-a734-21f0ee741965",
+                    "type": "Site",
+                    "unique_id": "00000000-0000-0000-0000-000000000000",
+                    "url": "https://leonarmstonmvp.sharepoint.com/sites/ProjectsHub",
+                    "web_id": "b0224f93-49be-4957-8e22-edbb489c937e"
+                }#>
+
+                $searchQuery = Submit-PnPSearchQuery -Query "Path:`"$path`" contentclass:`"STS_Site`"" -All -SelectProperties "ListId","FileType","SiteTitle","IdentityListItemId","Path","IdentityWebId","IdentitySiteId"
+
+                $capability = @{
+                    list_id = "00000000-0000-0000-0000-000000000000"
+                    name = $searchQuery.ResultRows[0].SiteTitle
+                    site_id = $searchQuery.ResultRows[0].IdentitySiteCollectionId
+                    type = $type
+                    unique_id = "00000000-0000-0000-0000-000000000000"
+                    url = $searchQuery.ResultRows[0].SPWebUrl
+                    web_id = $searchQuery.ResultRows[0].IdentityWebId
+                }
+                $items_by_url += $capability
+            }
+            "Folder" {
+                <#      
+                        {
+                            "list_id": "a1ed0c2f-aa4c-4a4f-a3ce-23c745fe17d0",
+                            "name": "NORR",
+                            "site_id": "18dfc66a-2fa5-4b83-adf5-8726b62a6861",
+                            "type": "Folder",
+                            "unique_id": "057676b7-9212-44cb-8321-d5df359be4d7",
+                            "url": "https://leonarmstonmvp.sharepoint.com/sites/Syntex/DrawingPlansDiffCompanies/NORR",
+                            "web_id": "b0224f93-49be-4957-8e22-edbb489c937e"
+                        }
+                #>
+                $searchQuery = Submit-PnPSearchQuery -Query "Path:`"$path`" IsContainer:true" -All -SelectProperties "ListId","FileType","SiteTitle","IdentityListItemId","Path","IdentityWebId","IdentitySiteId"
+
+                $capability = @{
+                    list_id = $searchQuery.ResultRows[0].ListId
+                    name = $searchQuery.ResultRows[0].Title
+                    site_id = $searchQuery.ResultRows[0].SiteId
+                    type = $type
+                    unique_id = $searchQuery.ResultRows[0].UniqueId -replace "{","" -replace "}","".Trim()
+                    url = $searchQuery.ResultRows[0].OriginalPath
+                    web_id = $searchQuery.ResultRows[0].WebId
+                }
+                $items_by_url += $capability
+            }
+            "Library" {
+                <#      {
+                            "list_id": "e042afcd-15d9-4790-a125-264e3b80cdaf",
+                            "name": "Autofill",
+                            "site_id": "18dfc66a-2fa5-4b83-adf5-8726b62a6861",
+                            "type": "Folder",
+                            "unique_id": "00000000-0000-0000-0000-000000000000",
+                            "url": "https://leonarmstonmvp.sharepoint.com/sites/Syntex/Autofill",
+                            "web_id": "b0224f93-49be-4957-8e22-edbb489c937e"
+                        }
+                #>
+                $searchQuery = Submit-PnPSearchQuery -Query "Path:`"$path`" contentclass:`"STS_List_DocumentLibrary`"" -All -SelectProperties "ListId","FileType","SiteTitle","IdentityListItemId","Path","IdentityWebId","IdentitySiteId"
+
+                $capability = @{
+                    list_id = $searchQuery.ResultRows[0].ListId
+                    name = $searchQuery.ResultRows[0].Title
+                    site_id = $searchQuery.ResultRows[0].SiteId
+                    type = "Folder"
+                    unique_id = "00000000-0000-0000-0000-000000000000"
+                    url = $searchQuery.ResultRows[0].OriginalPath.Split("/Forms")[0]
+                    web_id = $searchQuery.ResultRows[0].WebId
+                }
+                $items_by_url += $capability
+            }
+            default {
+                Write-Host "Invalid type entered. Please enter either File, Site, or Folder."
+            }
+        }
+    }
+    return @{ items_by_sharepoint_ids = $items_by_sharepoint_ids; items_by_url = $items_by_url }
+}
+
+# Prompt user for name
+$name = Read-Host "Enter a custom name for the SharePoint Agent (or press Enter to use the default `"Leon's Agent`")"
+if($name -eq "") 
+{
+    $name = "Leon's Agent"
+}
+Write-Host "     Name: $name"
+
+
+$description = Read-Host "Enter a custom description for the SharePoint Agent (or press Enter to use the default 'This is an agent curated based on the content from the selected file sources.')"
+if($description -eq "") 
+{
+    $description = "This is an agent curated based on the content from the selected file sources."
+}
+Write-Host "     Description: $description"
+
+$welcomeMessageText = Read-Host "Enter a custom welcome message for the SharePoint Agent (or press Enter to use the default 'Welcome! Enhance your productivity with this Copilot agent. Start a conversation by asking a question or selecting one of the suggested prompts.')"
+if($welcomeMessageText -eq "") 
+{
+    $welcomeMessageText = "Welcome! Enhance your productivity with this Copilot agent. Start a conversation by asking a question or selecting one of the suggested prompts."
+}
+Write-Host "     Welcome Message: $welcomeMessageText"
+
+$instructions = Read-Host "Enter custom instructions for the agent (or press Enter to use the default 'Provide helpful, accurate, and relevant information while maintaining a professional and courteous tone.')"
+if($instructions -eq "") 
+{
+    $instructions = "Provide helpful, accurate, and relevant information while maintaining a professional and courteous tone."
+}
+Write-Host "     Instructions: $instructions"
+
+# Get user input
+$conversationStarters = Get-ConversationStarters
+$capabilities = Get-Capabilities
+
+# Create JSON structure
+$json = @{
+    customCopilotConfig = @{
+        conversationStarters = @{
+            conversationStarterList = @($conversationStarters)
+            welcomeMessage = @{
+                text = $welcomeMessageText
+            }
+        }
+        gptDefinition = @{
+            capabilities = @(
+                @{
+                    items_by_sharepoint_ids = $capabilities.items_by_sharepoint_ids
+                    items_by_url = $capabilities.items_by_url
+                    name = "OneDriveAndSharePoint"
+                }
+            )
+            description = $description
+            instructions = $instructions
+            name = $name
+        }
+        icon = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
+    }
+    schemaVersion = "0.2.0"
+}
+
+# Convert to JSON and save to file
+$json | ConvertTo-Json -Depth 10 | Out-File "$($name).agent"
+
+Write-Host "JSON file generated: $($name).agent"
+
+```
+[!INCLUDE [More about PnP PowerShell](../../docfx/includes/MORE-PNPPS.md)]
+***
+
+
+## Contributors
+
+| Author(s) |
+|-----------|
+| Leon Armston |
+
+[!INCLUDE [DISCLAIMER](../../docfx/includes/DISCLAIMER.md)]
+<img src="https://m365-visitor-stats.azurewebsites.net/script-samples/scripts/spo-dev-agent-config-creation" aria-hidden="true" />
diff --git a/scripts/spo-dev-agent-config-creation/assets/example.png b/scripts/spo-dev-agent-config-creation/assets/example.png
diff --git a/scripts/spo-dev-agent-config-creation/assets/preview.png b/scripts/spo-dev-agent-config-creation/assets/preview.png
diff --git a/scripts/spo-dev-agent-config-creation/assets/sample.json b/scripts/spo-dev-agent-config-creation/assets/sample.json
@@ -0,0 +1,59 @@
+[
+  {
+    "name": "spo-dev-agent-config-creation",
+    "source": "pnp",
+    "title": "Creating SharePoint Agents (.agent Files) with PowerShell",
+    "shortDescription": "Dyanmic creation of SharePoint Agents (.agent files) using PowerShell. Specify instructions, sample prompts and ground on files, folder, libraries or sites.",
+    "url": "https://pnp.github.io/script-samples/spo-dev-agent-config-creation/README.html",
+    "longDescription": [
+      "This script sample demonstrates how to create SharePoint Agents (.agent files) using PnP PowerShell. The script allows you to specifyfor the Agent instructions, sample prompts, and ground on files, folders, libraries, or sites. All of the JSON is then created and then a .copilot file is created with all the configuration of the Agent ready to be deployed on your sites. Alternatively use the pattern and deploy your own customised SharePoint agents as part of your provisioning solution."
+    ],
+    "creationDateTime": "2025-01-10",
+    "updateDateTime": "2025-01-10",
+    "products": [
+      "SharePoint",
+      "Microsoft 365 Copilot"
+    ],
+    "metadata": [
+      {
+        "key": "PNP-POWERSHELL",
+        "value": "2.99.90"
+      }
+    ],
+    "categories": [
+      "Deploy",
+      "Provision",
+      "Configure",
+      "AI",
+      "Microsoft 365 Copilot"
+    ],
+    "tags": [
+      "Connect-PnPOnline",
+      "Submit-PnPSearchQuery",
+      "ConvertTo-Json"
+    ],
+    "thumbnails": [
+      {
+        "type": "image",
+        "order": 100,
+        "url": "https://raw.githubusercontent.com/pnp/script-samples/main/scripts/spo-dev-agent-config-creation/assets/preview.png",
+        "alt": "Preview of the sample Creating SharePoint Agents (.agent Files) with PowerShell"
+      }
+    ],
+    "authors": [
+      {
+        "gitHubAccount": "Leon Armston",
+        "company": "",
+        "pictureUrl": "https://avatars.githubusercontent.com/u/12968962?v=4",
+        "name": "Leon Armston"
+      }
+    ],
+    "references": [
+      {
+        "name": "Want to learn more about PnP PowerShell and the cmdlets",
+        "description": "Check out the PnP PowerShell site to get started and for the reference to the cmdlets.",
+        "url": "https://aka.ms/pnp/powershell"
+      }
+    ]
+  }
+]