Merge branch 'main' into user/srdeshpande/Workday-EmergencyContact-Update

Author: dsrikanthiowa

extensibility/mcp/order-management-enhanced-tc/README.md

@@ -0,0 +1,160 @@
+---
+title: Order Management with Enhanced Task Completion
+parent: MCP
+grand_parent: Extensibility
+nav_order: 3
+---
+
+# Order Management with Enhanced Task Completion
+
+{: .warning }
+> **Experimental feature.** Enhanced Task Completion is an experimental capability in Copilot Studio. See the [official documentation](https://github.com/microsoft/Agents/blob/main/docs/enhanced-task-completion.md) for current status and limitations.
+
+An end-to-end sample demonstrating Copilot Studio agents with [**Enhanced Task Completion**](https://github.com/microsoft/Agents/blob/main/docs/enhanced-task-completion.md) calling MCP servers for e-commerce order management and warehouse fulfillment, with a **Gradio chat UI** that renders tool calls, reasoning, and file attachments inline.
+
+## What is Enhanced Task Completion?
+
+Enhanced Task Completion shifts Copilot Studio from a "plan-then-execute" model to an adaptive, conversational approach. Instead of selecting all tools upfront, the agent:
+
+- **Reasons before acting** — asks clarifying questions and gathers context before calling tools
+- **Orchestrates tools dynamically** — recognizes dependencies between tool outputs, parallelizes independent calls, and adjusts strategy based on intermediate results
+- **Interleaves conversation and actions** — fluidly mixes questions, tool calls, and responses across multiple turns
+- **Recovers from failures** — retries or finds alternative approaches when tool calls fail
+
+This sample demonstrates all of these capabilities through a realistic e-commerce customer service scenario where the agent chains 9 tools across two MCP servers and a connected agent to answer complex multi-part questions.
+
+![Gradio Chat UI](./assets/gradio-ui.png)
+
+## What's Included
+
+### Orders Agent (Copilot Studio)
+
+The primary agent with Enhanced Task Completion enabled. Handles customer inquiries by dynamically chaining tools from the Order Management MCP server. When a question involves inventory or fulfillment, it delegates to the Warehouse Agent as a connected agent.
+
+### Warehouse Agent (Copilot Studio)
+
+A connected agent invoked by the Orders Agent for warehouse and fulfillment queries. Calls tools from the Warehouse MCP server to check stock levels, track fulfillment pipeline stages, find alternative products, and look up restock dates.
+
+### Order Management MCP Server (5 tools)
+
+Node.js [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) server with interdependent tools for e-commerce order operations:
+
+| Tool | Input | Purpose |
+|---|---|---|
+| `search_orders` | Customer name/email/order# | Entry point — find orders |
+| `get_order` | order_id | Full order details + line items |
+| `get_shipment` | order_id | Tracking info (shipped/delivered only) |
+| `request_return` | order_id, item_skus[], reason | Initiate a return |
+| `get_return_status` | return_id | Check return progress |
+
+### Warehouse MCP Server (4 tools)
+
+Node.js Streamable HTTP server with interdependent tools for warehouse and fulfillment:
+
+| Tool | Input | Purpose |
+|---|---|---|
+| `check_stock` | SKU | Inventory levels + warehouse location |
+| `get_fulfillment_status` | order_id | Pipeline stage (received → shipped) |
+| `find_alternatives` | SKU | Similar products in stock |
+| `get_restock_date` | SKU | Next inbound shipment date |
+
+### Gradio Chat UI
+
+Python frontend that connects to the Orders Agent via the [Microsoft Agents SDK](https://github.com/microsoft/Agents-for-python) and renders the full Enhanced Task Completion activity protocol inline:
+
+- **Reasoning steps** — agent thinking displayed as collapsible accordions
+- **Tool calls** — grouped with parameters, duration, and results
+- **Intermediate messages** — agent narration between tool call batches
+- **File upload/download** — CSV/text files sent as base64 attachments, agent-generated files offered for download
+- **MSAL auth** — interactive login with persisted token cache (sign in once)
+
+### Custom Connectors
+
+Power Platform connector definitions (Swagger + apiProperties) that expose each MCP server as an action in Copilot Studio. The connectors use the `x-ms-agentic-protocol: mcp-streamable-1.0` extension to enable native MCP tool discovery.
+
+## Prerequisites
+
+- Node.js 18+
+- Python 3.12+
+- [Dev Tunnels CLI](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started) (`devtunnel`)
+- A Power Platform environment with Copilot Studio
+- An Entra ID app registration with `CopilotStudio.Copilots.Invoke` permission
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+node scripts/setup.mjs
+```
+
+### 2. Import agents (first time only)
+
+Import `agents/solution/OrderManagementMCPDemo.zip` into your environment via **make.powerapps.com > Solutions > Import**. After import, create connections for each MCP connector from the **Custom connectors** page (no auth — just click **Create**). See [Importing the Agent Solutions](./agents/IMPORT) for details.
+
+### 3. Start MCP servers + tunnels
+
+```bash
+node scripts/start.mjs
+```
+
+This starts both MCP servers and creates anonymous dev tunnels. Note the tunnel URLs printed:
+
+```
+Order Management MCP endpoint: https://xxxxx-3000.uks1.devtunnels.ms/mcp
+Warehouse MCP endpoint: https://xxxxx-3001.uks1.devtunnels.ms/mcp
+```
+
+### 4. Update connector URLs
+
+Each time you restart (tunnels get new URLs), update the custom connector hosts:
+
+1. Go to **make.powerapps.com** > **Custom connectors**
+2. Find **"orders mcp"** > click **Edit** > update the **Host** field with the order tunnel host (e.g., `xxxxx-3000.uks1.devtunnels.ms`) > click **Update connector**
+3. Find **"warehouse server 3"** > click **Edit** > update the **Host** field with the warehouse tunnel host (e.g., `xxxxx-3001.uks1.devtunnels.ms`) > click **Update connector**
+
+No need to republish the agents — the connectors are referenced dynamically.
+
+### 5. Start the chat UI
+
+Configure the `.env` file with your agent details (requires an Entra ID App Registration). See [Chat UI Setup](./SETUP) for step-by-step instructions.
+
+```bash
+cp chat-ui/.env.sample chat-ui/.env
+# Edit chat-ui/.env — see SETUP.md for details
+node scripts/start-ui.mjs
+```
+
+Open http://localhost:7860 and try one of these:
+
+**Basic order lookup:**
+> Hi, I'm Sarah Mitchell. I ordered some Sony headphones recently but they arrived with a crackling sound in the left ear. I'd like to return them.
+
+**Cross-server (orders + warehouse):**
+> I'm James Rivera. My Nintendo Switch order hasn't shipped yet. When can I expect it? If it's not available, what are my options?
+
+**File upload — populate a CSV:**
+> Upload `chat-ui/data/demo-orders.csv` and ask: "Fill in all the empty columns for each order and return the completed CSV."
+
+## Architecture
+
+```mermaid
+graph TB
+    User([fa:fa-user User]) -->|chat| GradioUI
+
+    subgraph Local Machine
+        GradioUI["Gradio Chat UI<br/>Port 7860<br/><i>Reasoning, tool calls,<br/>file upload/download</i>"]
+        OrderMCP["Order Management<br/>MCP Server<br/><b>5 tools</b> · Port 3000"]
+        WarehouseMCP["Warehouse<br/>MCP Server<br/><b>4 tools</b> · Port 3001"]
+    end
+
+    subgraph Copilot Studio
+        OrdersAgent["Orders Agent<br/><i>Enhanced Task Completion</i>"]
+        WarehouseAgent["Warehouse Agent<br/><i>connected agent</i>"]
+        OrdersAgent -->|invokes| WarehouseAgent
+    end
+
+    GradioUI -->|"Agents SDK<br/>(streaming)"| OrdersAgent
+    OrdersAgent -->|"MCP Action<br/>(via connector)"| OrderMCP
+    WarehouseAgent -->|"MCP Action<br/>(via connector)"| WarehouseMCP
+```

extensibility/mcp/order-management-enhanced-tc/SETUP.md

@@ -0,0 +1,39 @@
+---
+title: Chat UI Setup
+parent: Order Management with Enhanced Task Completion
+grand_parent: MCP
+nav_exclude: true
+---
+
+# Chat UI Setup
+
+The Gradio chat UI authenticates against Copilot Studio using MSAL interactive login. You need an Entra ID App Registration and a `.env` file with your agent details.
+
+## App Registration
+
+1. Go to **portal.azure.com** > **App registrations** > **New registration**
+2. Name: e.g., "MCP Demo Chat Client"
+3. Supported account types: **Single tenant**
+4. Redirect URI: **Public client/native** > `http://localhost`
+5. After creation, go to **API permissions** > **Add a permission** > **APIs my organization uses**
+6. Search for **CopilotStudio** > select **CopilotStudio.Copilots.Invoke** (delegated)
+7. Click **Grant admin consent**
+8. Copy the **Application (client) ID** — this is your `AGENTAPPID` below
+
+## Configure `.env`
+
+Copy `chat-ui/.env.sample` to `chat-ui/.env` and fill in:
+
+```env
+COPILOTSTUDIOAGENT__ENVIRONMENTID=<your-environment-id>
+COPILOTSTUDIOAGENT__SCHEMANAME=<agent-schema-name>
+COPILOTSTUDIOAGENT__TENANTID=<your-tenant-id>
+COPILOTSTUDIOAGENT__AGENTAPPID=<app-registration-client-id>
+```
+
+| Variable | Where to find it |
+|---|---|
+| `ENVIRONMENTID` | The GUID in your Power Platform URL, or **Settings** > **Session details** in Copilot Studio |
+| `SCHEMANAME` | Copilot Studio > open the Orders Agent > **Settings** > **Advanced** > **Schema name** |
+| `TENANTID` | Your Entra ID tenant ID (Azure Portal > **Microsoft Entra ID** > **Overview**) |
+| `AGENTAPPID` | The Application (client) ID from the App Registration above |

extensibility/mcp/order-management-enhanced-tc/agents/IMPORT.md

@@ -0,0 +1,38 @@
+---
+title: Importing the Agent Solutions
+parent: Order Management with Enhanced Task Completion
+grand_parent: MCP
+nav_exclude: true
+---
+
+# Importing the Agent Solutions
+
+## Prerequisites
+
+- A Power Platform environment with Copilot Studio
+- Admin or Maker role in the target environment
+
+## Steps
+
+### 1. Import the solution
+
+The solution zip contains both agents, their custom connectors, and connection references — all in one package.
+
+1. Go to [make.powerapps.com](https://make.powerapps.com)
+2. Select your target environment
+3. Navigate to **Solutions** > **Import solution**
+4. Upload `solution/OrderManagementMCPDemo.zip`
+5. Click **Next** through the details page
+6. If the import wizard shows a **Connections** page, click **New connection** for each connector (no auth needed — just click **Create**), then select the connections you just created
+7. Click **Import**
+
+### 2. Create connections
+
+After import, go to **Custom connectors** in the left nav. For each MCP connector (**orders mcp** and **warehouse server 3**), click **Create connection**. The MCP connectors have no authentication — just click **Create** with no credentials.
+
+{: .note }
+> In a clean environment the import wizard may skip the Connections step entirely. Creating connections from the Custom connectors page ensures the agents can reach the MCP servers.
+
+### 3. Publish agents
+
+In Copilot Studio, open each agent and click **Publish** to make the latest version live.

extensibility/mcp/order-management-enhanced-tc/agents/solution/OrderManagementMCPDemo.zip

@@ -0,0 +1,8 @@
+<botcomponent_connectionreferenceset>
+  <botcomponent_connectionreference botcomponentid.schemaname="cr26e_OrdersAgent.topic.ordersmcp" connectionreferenceid.connectionreferencelogicalname="cr26e_OrdersAgent.shared_new-5forders-20mcp-5fee08b8354fad177a.6be7a421f5184b9ebb376965cf6cd8b8">
+    <iscustomizable>1</iscustomizable>
+  </botcomponent_connectionreference>
+  <botcomponent_connectionreference botcomponentid.schemaname="cr26e_Warehouseagent.topic.warehouseserver3" connectionreferenceid.connectionreferencelogicalname="cr26e_Warehouseagent.shared_new-5fwarehouse-20server-203-5fee08b8354fad177a.726ca1c1522e492082b8e68667e2267e">
+    <iscustomizable>1</iscustomizable>
+  </botcomponent_connectionreference>
+</botcomponent_connectionreferenceset>

extensibility/mcp/order-management-enhanced-tc/agents/sourcecode/OrderManagementMCPDemo/Assets/botcomponent_connectionreferenceset.xml

@@ -0,0 +1 @@
+{}

extensibility/mcp/order-management-enhanced-tc/agents/sourcecode/OrderManagementMCPDemo/Connector/new_5Forders-20mcp_connectionparameters.json

@@ -0,0 +1 @@
+{"swagger":"2.0","info":{"title":"orders mcp","description":"my orders mcp server connector","version":"1.0.0"},"host":"x1kv1q93-3000.uks1.devtunnels.ms","basePath":"/","schemes":["https"],"paths":{"/mcp":{"post":{"responses":{"200":{"description":"Immediate Response"}},"x-ms-agentic-protocol":"mcp-streamable-1.0","operationId":"InvokeServer","summary":"orders mcp","description":"my orders mcp server connector"}}},"securityDefinitions":{},"security":[]}

extensibility/mcp/order-management-enhanced-tc/agents/sourcecode/OrderManagementMCPDemo/Connector/new_5Forders-20mcp_iconblob.Png

@@ -0,0 +1 @@
+[]

extensibility/mcp/order-management-enhanced-tc/agents/sourcecode/OrderManagementMCPDemo/Connector/new_5Forders-20mcp_openapidefinition.json

@@ -0,0 +1 @@
+{}