|
| 1 | +--- |
| 2 | +title: Assistant UI |
| 3 | +parent: Custom UI |
| 4 | +grand_parent: UI |
| 5 | +nav_order: 3 |
| 6 | +--- |
| 7 | +# Copilot Studio + Assistant UI Integration Sample |
| 8 | + |
| 9 | +This project demonstrates how to integrate Copilot Studio with Assistant UI to create a modern, responsive chat interface with AI capabilities. |
| 10 | + |
| 11 | +## Overview |
| 12 | + |
| 13 | +This sample showcases: |
| 14 | +- Integration between Copilot Studio and the Assistant UI framework |
| 15 | +- Single sign-on authentication using Microsoft Authentication Library (MSAL) |
| 16 | +- Multiple conversation threads |
| 17 | + |
| 18 | +<p align="center"> |
| 19 | + <img src="./assistant-ui-mcs/docs/images/screenshot.png" alt="Screenshot of the Assistant UI with Copilot Studio"> |
| 20 | +</p> |
| 21 | + |
| 22 | +## Prerequisites |
| 23 | + |
| 24 | +- A Copilot Studio agent with "Authenticate with Microsoft" enabled |
| 25 | +- Microsoft Entra ID app registration with appropriate permissions |
| 26 | +- Node.js (v18 or later) |
| 27 | +- npm, yarn, pnpm, or bun package manager |
| 28 | + |
| 29 | +## Setup Instructions |
| 30 | + |
| 31 | +### 1. Microsoft Entra ID App Registration |
| 32 | + |
| 33 | +1. Create an App Registration in the Microsoft Entra admin center |
| 34 | +2. Configure authentication: |
| 35 | + - Click on **Add a platform** |
| 36 | + - Select **Single-page application (SPA)** |
| 37 | + - Enter the redirect URI where your application will be hosted (e.g., `http://localhost:3000` for local testing) |
| 38 | + - Click **Configure** |
| 39 | +3. Configure API permissions: |
| 40 | + - Navigate to **API permission** > **Add permissions** |
| 41 | + - Select **APIs my organization uses**, and search for **Power Platform API** |
| 42 | + - Select **Delegated permissions** > **Copilot Studio** > **Copilot Studio.Copilots.Invoke** permission |
| 43 | + - Click **Add Permissions** |
| 44 | + - Grant admin consent for your directory |
| 45 | +4. Navigate to **Overview** and record your app registration's **client ID** and **tenant ID** |
| 46 | + |
| 47 | +### 2. Get Copilot Studio Agent Metadata |
| 48 | + |
| 49 | +1. In Copilot Studio, select your agent |
| 50 | +2. Navigate to **Settings** > **Advanced** |
| 51 | +3. Under **Metadata**, locate the **Schema name** and **Environment ID** |
| 52 | +4. Record these values for configuration |
| 53 | + |
| 54 | +### 3. Configure the React Application |
| 55 | + |
| 56 | +1. Clone this repository and navigate to the project directory: |
| 57 | + ```bash |
| 58 | + git clone https://github.com/microsoft/CopilotStudioSamples |
| 59 | + cd CopilotStudioSamples/ui/custom-ui/assistant-ui/assistant-ui-mcs |
| 60 | + ``` |
| 61 | + |
| 62 | +2. Install dependencies: |
| 63 | + ```bash |
| 64 | + npm install |
| 65 | + ``` |
| 66 | +3. Create a `.env.local` file in the root of the project and add the following environment variables: |
| 67 | + ```env |
| 68 | + NEXT_PUBLIC_CLIENT_ID=<your-client-id-from-app-registration> |
| 69 | + NEXT_PUBLIC_TENANT_ID=<your-tenant-id-from-app-registration> |
| 70 | + NEXT_PUBLIC_AGENT_SCHEMA=<your-schema-name-from-copilot-studio> |
| 71 | + NEXT_PUBLIC_ENVIRONMENT_ID=<your-environment-id-from-copilot-studio> |
| 72 | + NEXT_PUBLIC_CLOUD_ENVIRONMENT=<optional-cloud-environment> |
| 73 | + ``` |
| 74 | + Replace the placeholders with the values obtained from the previous steps. |
| 75 | +4. Start the development server: |
| 76 | + ```bash |
| 77 | + npm run dev |
| 78 | + ``` |
| 79 | +5. Open your browser and navigate to `http://localhost:3000` to see the application in action. |
| 80 | +6. You will be prompted to sign in with Microsoft credentials |
| 81 | +7. After successful authentication, the chat interface will connect to your Copilot Studio agent |
| 82 | +8. Start chatting with your agent! |
| 83 | + |
| 84 | +## Project Structure |
| 85 | + |
| 86 | +- **/app** - Next.js application routes |
| 87 | +- **/components** - React components including: |
| 88 | + - **/components/assistant-ui** - Assistant UI integration components |
| 89 | + - **/components/copilot-studio-runtime-provider.tsx** - Core integration logic between Copilot Studio and Assistant UI |
| 90 | + - **/components/citation-link-handler.tsx** - Handler for citation links to open in new tabs |
| 91 | +- **/lib** - Utility functions for authentication and settings |
| 92 | +- **/public** - Static assets |
| 93 | + |
| 94 | +## Troubleshooting |
| 95 | + |
| 96 | +- **Authentication issues**: Ensure your app registration has the correct permissions and admin consent |
| 97 | + - Check browser developer tools (F12) for specific error messages - most Azure authentication errors will appear here |
| 98 | + - Look for environment variable loading issues in the console logs, which will show the exact values being used |
| 99 | +- **Connection issues**: Verify your environment ID and agent schema values are correct in your .env.local file |
| 100 | +- **Silent authentication failures**: If you encounter iframe-related errors in the console, check that third-party cookies are not being blocked by your browser |
| 101 | + |
| 102 | +## Additional Resources |
| 103 | + |
| 104 | +- [Assistant UI Documentation](https://github.com/assistant-ui/assistant-ui) |
| 105 | +- [Copilot Studio Documentation](https://learn.microsoft.com/en-us/microsoft-copilot-studio/) |
| 106 | +- [Microsoft 365 Agents SDK - NodeJS /TypeScript](https://github.com/Microsoft/Agents-for-js) |
| 107 | +- [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/en-us/entra/identity-platform/msal-overview) |
| 108 | + |
| 109 | +## License |
| 110 | + |
| 111 | +This project is licensed under the MIT License - see the LICENSE file for details. |
0 commit comments