Add mcs policy agent topics

samples/mcs-policy-agent-topics/README.md

@@ -0,0 +1,131 @@
+# Policy Agent - Topic-Based Grounding
+
+A Custom Engine Agent built in Microsoft Copilot Studio that uses topic-based folder structure in SharePoint for deterministic, precise policy responses.
+
+## Demo
+
+https://github.com/user-attachments/assets/e6c3d7d3-015e-4f67-ac9e-2f5d4a6c8294
+
+## Problem Statement
+
+Organizations with policies spread across multiple departments need precise, targeted responses. Common challenges include:
+- Generic responses that don't address specific departmental policies
+- Difficulty routing queries to the right knowledge source
+- Lack of precision when policies overlap across departments
+- Need for deterministic behavior in policy lookups
+
+## Solution Overview
+
+This solution uses a **Custom Engine Agent (CEA)** in Copilot Studio with topic-based SharePoint folder mapping:
+
+| Component | Description |
+|-----------|-------------|
+| **Custom Engine Agent** | Provides targeted responses based on topic classification |
+| **Topic-Based Grounding** | SharePoint folders organized by department/topic |
+| **Folder-to-Topic Mapping** | Each SharePoint folder maps to a specific agent topic |
+| **Deterministic Routing** | Structured approach ensures precise, relevant answers |
+
+## Architecture
+
+```
+                    ┌─────────────────────────┐
+                    │      User Query         │
+                    │  "What's the expense    │
+                    │   claim process?"       │
+                    └───────────┬─────────────┘
+                                │
+                    ┌───────────▼─────────────┐
+                    │   Custom Engine Agent   │
+                    │   (Topic Classifier)    │
+                    └───────────┬─────────────┘
+                                │
+              ┌─────────────────┼─────────────────┐
+              │                 │                 │
+    ┌─────────▼─────┐  ┌───────▼───────┐  ┌─────▼─────────┐
+    │  HR Topic     │  │ Finance Topic │  │  IT Topic     │
+    │               │  │               │  │               │
+    │  SharePoint   │  │  SharePoint   │  │  SharePoint   │
+    │  /HR Folder   │  │  /Finance     │  │  /IT Folder   │
+    └───────────────┘  └───────┬───────┘  └───────────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │  Targeted Response  │
+                    │  from Finance       │
+                    │  Policy Documents   │
+                    └─────────────────────┘
+```
+
+## Technical Details
+
+| Aspect | Details |
+|--------|---------|
+| **Platform** | Microsoft Copilot Studio |
+| **Agent Type** | Custom Engine Agent (CEA) |
+| **Knowledge Sources** | SharePoint folders organized by topic (Finance, HR, IT, etc.) |
+| **Integration Logic** | Topic folders mapped to specific agent topics for targeted responses |
+| **Routing Method** | Deterministic topic-based classification |
+
+## Sample Prompts
+
+- "What's the code of conduct policy for new employees?"
+- "Explain the step-by-step process for submitting expense claims"
+- "What are the IT security guidelines for remote work?"
+- "How do I request time off according to HR policy?"
+
+## Business Value
+
+| Metric | Value |
+|--------|-------|
+| **Faster Info Retrieval** | Direct routing to relevant policy folder |
+| **Better Resolution Rate** | Improved user query resolution percentage |
+| **Enhanced Precision** | Deterministic systems provide accurate, targeted answers |
+| **Structured Organization** | Clear folder structure makes maintenance easier |
+
+## Deployment
+
+### Prerequisites
+- Microsoft Copilot Studio license
+- SharePoint site with topic-organized folder structure
+- VS Code with Copilot Studio extension (optional, for source control)
+
+### SharePoint Setup
+Create folders for each policy domain:
+```
+/Policies
+  ├── /Finance
+  │   ├── expense-policy.docx
+  │   └── travel-reimbursement.docx
+  ├── /HR
+  │   ├── code-of-conduct.docx
+  │   └── leave-policy.docx
+  └── /IT
+      ├── security-guidelines.docx
+      └── acceptable-use.docx
+```
+
+### Import Steps
+1. Open Microsoft Copilot Studio
+2. Import the agent source from the `src/` folder using the Copilot Studio extension for VS Code
+3. Configure SharePoint knowledge sources with your topic folders (update the `site` URLs in `src/knowledge/`)
+4. Map each folder to corresponding agent topics
+5. Test the agent with sample prompts across different topics
+6. Publish to your desired channel
+
+## Folder Structure
+
+```
+mcs-policy-agent-topics/
+├── README.md                    # This file
+├── assets/
+│   └── sample.json              # PnP sample gallery metadata
+└── src/
+    ├── agent.mcs.yml            # Agent definition
+    ├── settings.mcs.yml         # Agent settings
+    ├── knowledge/               # Topic-organized knowledge config
+    └── topics/                  # Topic definitions (mapped to folders)
+```
+
+## Related Resources
+
+- [Copilot Studio Documentation](https://learn.microsoft.com/en-us/microsoft-copilot-studio/)
+- [VS Code Copilot Studio Extension](https://marketplace.visualstudio.com/items?itemName=ms-CopilotStudio.vscode-copilotstudio)

samples/mcs-policy-agent-topics/assets/sample.json

@@ -0,0 +1,73 @@
+[
+    {
+        "name": "pnp-copilot-pro-dev-mcs-policy-agent-topics",
+        "source": "pnp",
+        "title": "Policy Agent (Topic-Based Grounding) for Copilot Studio",
+        "shortDescription": "A Custom Engine Agent in Copilot Studio that maps each policy domain (HR, Finance, IT, Legal, Operations) to its own SharePoint folder and topic for deterministic, precise routing.",
+        "url": "https://github.com/pnp/copilot-pro-dev-samples/tree/main/samples/mcs-policy-agent-topics",
+        "downloadUrl": "https://pnp.github.io/download-partial/?url=https://github.com/pnp/copilot-pro-dev-samples/tree/main/samples/mcs-policy-agent-topics",
+        "longDescription": [
+            "A Custom Engine Agent built in Microsoft Copilot Studio that uses a topic-based grounding pattern: each policy domain maps to a dedicated SharePoint folder and a dedicated agent topic, giving deterministic routing and per-domain precision."
+        ],
+        "creationDateTime": "2026-06-25",
+        "updateDateTime": "2026-06-25",
+        "products": [
+            "Microsoft 365 Copilot",
+            "Microsoft Copilot Studio",
+            "SharePoint"
+        ],
+        "metadata": [
+            {
+                "key": "PLATFORM",
+                "value": "Copilot Studio"
+            },
+            {
+                "key": "LANGUAGE",
+                "value": "None"
+            },
+            {
+                "key": "AGENT-TYPE",
+                "value": "Custom Engine Agent"
+            },
+            {
+                "key": "EXTENSION-TYPE",
+                "value": "Knowledge"
+            },
+            {
+                "key": "API-PLUGIN",
+                "value": "No"
+            },
+            {
+                "key": "GRAPH-CONNECTOR",
+                "value": "No"
+            }
+        ],
+        "thumbnails": [
+            {
+                "type": "video",
+                "order": 101,
+                "url": "https://github.com/user-attachments/assets/e6c3d7d3-015e-4f67-ac9e-2f5d4a6c8294",
+                "alt": "Demo - Policy Agent with topic-based SharePoint grounding"
+            }
+        ],
+        "authors": [
+            {
+                "gitHubAccount": "keshavk-msft",
+                "pictureUrl": "https://github.com/keshavk-msft.png",
+                "name": "Keshav"
+            }
+        ],
+        "references": [
+            {
+                "name": "Microsoft 365 Copilot extensibility",
+                "description": "Learn more about Microsoft 365 Copilot and how you can extend it.",
+                "url": "https://learn.microsoft.com/microsoft-365-copilot/extensibility/"
+            },
+            {
+                "name": "Microsoft Copilot Studio",
+                "description": "Build AI-driven agents and workflows with Microsoft Copilot Studio.",
+                "url": "https://learn.microsoft.com/en-us/microsoft-copilot-studio/"
+            }
+        ]
+    }
+]

samples/mcs-policy-agent-topics/src/agent.mcs.yml

@@ -0,0 +1,77 @@
+mcs.metadata:
+  componentName: KK Policy Agent(Topic)
+kind: GptComponentMetadata
+displayName: KK Policy Agent(Topic)
+instructions: |+
+  ### 🧭 **Agent Instruction for KK Policy Agent**
+
+  #### 🎯 **Purpose**
+
+  You are the **KK Policy Agent**, designed to assist employees in understanding, locating, and complying with organizational policies across various domains such as Finance, HR, IT & Security, Legal & Compliance, and more.
+
+  #### 💬 **Your Role**
+
+  Your role is to:
+
+  * Provide **clear, accurate, and concise** responses regarding company policies.
+  * Reference the **correct topic** (Finance, HR, IT, etc.) based on user intent.
+  * Maintain a **professional and supportive tone**, ensuring users feel guided and confident in following organizational policies.
+  * Avoid speculation — only provide verified or documented policy information.
+  * Redirect users to **official resources or policy documents** where applicable.
+
+  ---
+
+  ### 🧩 **Behavior Guidelines**
+
+  1. **Policy Understanding**
+
+     * When a user asks about any policy, identify the relevant category (e.g., HR, IT, Finance, Legal).
+     * Retrieve or summarize the applicable policy clearly.
+     * If multiple policies are relevant, summarize each briefly and provide guidance on which applies.
+
+  2. **Response Format**
+     Your answers should be:
+
+     * **Concise and factual** (avoid long paragraphs).
+     * **Action-oriented** when the policy includes procedures (e.g., “To raise a reimbursement claim, submit the form via HR Portal → Reimbursements”).
+     * **Friendly yet formal**, ensuring clarity and confidence in communication.
+
+  3. **Escalation and Limitations**
+
+     * If the question is outside your scope or unclear, respond with:
+
+       > “I recommend contacting the respective department or reviewing the official policy document for the most accurate guidance.”
+     * Avoid providing personal opinions or assumptions.
+
+  ---
+
+  ### 🗂️ **Topic-Specific Instructions**
+
+  | **Topic Name**                                  | **Purpose / Coverage**                                                                                   | **Example Queries**                                                      |
+  | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+  | **Finance**                                     | Covers policies on reimbursements, travel allowance, expense approvals, and budgeting.                   | “How can I claim travel expenses?” / “What’s the reimbursement limit?”   |
+  | **HR**                                          | Handles employee onboarding, leave, attendance, performance reviews, and employee relations.             | “How many paid leaves do I get?” / “What’s the process for resignation?” |
+  | **IT & Security**                               | Provides information about cybersecurity, data access, password policies, and acceptable use of devices. | “What’s the password reset policy?” / “Can I use personal USB drives?”   |
+  | **Legal & Compliance**                          | Details compliance, data privacy, confidentiality, and company code of conduct policies.                 | “What’s the non-disclosure policy?” / “How is data privacy handled?”     |
+  | **Operations & Administration**                 | Includes office procedures, facilities, procurement, and travel logistics.                               | “How do I book a meeting room?” / “What’s the office visitor policy?”    |
+  | **Greeting / Goodbye / Thank You / Start Over** | Manage conversational flow and user experience.                                                          | “Hi”, “Thanks”, “Bye”, “Restart chat”                                    |
+
+  ---
+
+  ### ⚙️ **Tone and Style**
+
+  * Maintain a **calm, confident, and informative** tone.
+  * Always show empathy and professionalism.
+  * Avoid jargon unless explicitly defined.
+  * Example tone:
+
+    > “Sure, I can help with that. The IT & Security policy states that all devices must be encrypted before connecting to the corporate network.”
+
+  ---
+
+  ### 📚 **Fallback / Default Response**
+
+  If the topic or query does not match any known policy:
+
+  > “I couldn’t find a specific policy on that topic. You may refer to the HR or IT policy section on the intranet for detailed guidance, or contact the relevant department.”
+

samples/mcs-policy-agent-topics/src/knowledge/cred8_agent_Ai98b3.topic.Finance_Policies_G5mmFrCLhDJsNuXKYu4Yz.mcs.yml

@@ -0,0 +1,7 @@
+mcs.metadata:
+  componentName: Finance_Policies
+  description: This knowledge source provides information found in Finance_Policies SharePoint.
+kind: KnowledgeSourceConfiguration
+source:
+  kind: SharePointSearchSource
+  site: https://contoso.sharepoint.com/sites/PolicyHub/Shared%20Documents/Policies/Finance_Policies

samples/mcs-policy-agent-topics/src/knowledge/cred8_agent_Ai98b3.topic.HR_Policies_zwEbU9jckf88nCSmlyMXG.mcs.yml

@@ -0,0 +1,7 @@
+mcs.metadata:
+  componentName: HR_Policies
+  description: This knowledge source provides information found in HR_Policies SharePoint.
+kind: KnowledgeSourceConfiguration
+source:
+  kind: SharePointSearchSource
+  site: https://contoso.sharepoint.com/sites/PolicyHub/Shared%20Documents/Policies/HR_Policies

samples/mcs-policy-agent-topics/src/knowledge/cred8_agent_Ai98b3.topic.IT_Security_Policies_cPBSzc5DjJr0gVgfvJnMF.mcs.yml

@@ -0,0 +1,7 @@
+mcs.metadata:
+  componentName: IT_Security_Policies
+  description: This knowledge source provides information found in IT_Security_Policies SharePoint.
+kind: KnowledgeSourceConfiguration
+source:
+  kind: SharePointSearchSource
+  site: https://contoso.sharepoint.com/sites/PolicyHub/Shared%20Documents/Policies/IT_Security_Policies

samples/mcs-policy-agent-topics/src/settings.mcs.yml

@@ -0,0 +1,29 @@
+displayName: KK Policy Agent(Topic)
+schemaName: cred8_agent_Ai98b3
+accessControlPolicy: ChatbotReaders
+authenticationMode: Integrated
+authenticationTrigger: Always
+configuration:
+  channels:
+    - channelId: MsTeams
+
+  settings:
+    GenerativeActionsEnabled: true
+
+  isAgentConnectable: true
+  gPTSettings:
+    defaultSchemaName: cred8_agent_Ai98b3.gpt.default
+
+  isLightweightBot: false
+  aISettings:
+    useModelKnowledge: true
+    isFileAnalysisEnabled: true
+    isSemanticSearchEnabled: true
+    optInUseLatestModels: false
+
+  recognizer:
+    kind: GenerativeAIRecognizer
+
+publishedOn: 2025-10-07T06:09:13.0000000Z
+template: default-2.1.0
+language: 1033

samples/mcs-policy-agent-topics/src/topics/ConversationStart.mcs.yml

@@ -0,0 +1,15 @@
+mcs.metadata:
+  componentName: Conversation Start
+  description: This system topic triggers when the agent receives an Activity indicating the beginning of a new conversation. If you do not want the agent to initiate the conversation, disable this topic.
+kind: AdaptiveDialog
+beginDialog:
+  kind: OnConversationStart
+  id: main
+  actions:
+    - kind: SendActivity
+      id: sendMessage_M0LuhV
+      activity:
+        text:
+          - Hello, I'm {System.Bot.Name}, a virtual assistant. Just so you are aware, I sometimes use AI to answer your questions. If you provided a website during creation, try asking me about it! Next try giving me some more knowledge by setting up generative AI.
+        speak:
+          - Hello and thank you for calling {System.Bot.Name}. Please note that some responses are generated by AI and may require verification for accuracy. How may I help you today?