mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-20 02:15:12 +00:00
Add MCP-based M365 Agents collection
- Create Declarative Agent prompt with MCP server integration - Create Adaptive Cards prompt for visual response templates - Deploy and Manage Agents prompt for admin workflows - Development guidelines instruction file - Collection manifest and reference documentation Based on: - https://devblogs.microsoft.com/microsoft365dev/build-declarative-agents-for-microsoft-365-copilot-with-mcp/ - https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-mcp-plugins - https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-adaptive-cards - https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps
This commit is contained in:
Troy Taylor
527
prompts/mcp-create-adaptive-cards.prompt.md
Normal file
527
prompts/mcp-create-adaptive-cards.prompt.md
Normal file
@@ -0,0 +1,527 @@
|
||||
````prompt
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Add Adaptive Card response templates to MCP-based API plugins for visual data presentation in Microsoft 365 Copilot'
|
||||
model: 'gpt-4.1'
|
||||
tags: [mcp, adaptive-cards, m365-copilot, api-plugin, response-templates]
|
||||
---
|
||||
|
||||
# Create Adaptive Cards for MCP Plugins
|
||||
|
||||
Add Adaptive Card response templates to MCP-based API plugins to enhance how data is presented visually in Microsoft 365 Copilot.
|
||||
|
||||
## Adaptive Card Types
|
||||
|
||||
### Static Response Templates
|
||||
Use when API always returns items of the same type and format doesn't change often.
|
||||
|
||||
Define in `response_semantics.static_template` in ai-plugin.json:
|
||||
|
||||
```json
|
||||
{
|
||||
"functions": [
|
||||
{
|
||||
"name": "GetBudgets",
|
||||
"description": "Returns budget details including name and available funds",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.availableFunds"
|
||||
},
|
||||
"static_template": {
|
||||
"type": "AdaptiveCard",
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Name: ${if(name, name, 'N/A')}",
|
||||
"wrap": true
|
||||
},
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Response Templates
|
||||
Use when API returns multiple types and each item needs a different template.
|
||||
|
||||
**ai-plugin.json configuration:**
|
||||
```json
|
||||
{
|
||||
"name": "GetTransactions",
|
||||
"description": "Returns transaction details with dynamic templates",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.transactions",
|
||||
"properties": {
|
||||
"template_selector": "$.displayTemplate"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**API Response with Embedded Templates:**
|
||||
```json
|
||||
{
|
||||
"transactions": [
|
||||
{
|
||||
"budgetName": "Fourth Coffee lobby renovation",
|
||||
"amount": -2000,
|
||||
"description": "Property survey for permit application",
|
||||
"expenseCategory": "permits",
|
||||
"displayTemplate": "$.templates.debit"
|
||||
},
|
||||
{
|
||||
"budgetName": "Fourth Coffee lobby renovation",
|
||||
"amount": 5000,
|
||||
"description": "Additional funds to cover cost overruns",
|
||||
"expenseCategory": null,
|
||||
"displayTemplate": "$.templates.credit"
|
||||
}
|
||||
],
|
||||
"templates": {
|
||||
"debit": {
|
||||
"type": "AdaptiveCard",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"size": "medium",
|
||||
"weight": "bolder",
|
||||
"color": "attention",
|
||||
"text": "Debit"
|
||||
},
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Budget",
|
||||
"value": "${budgetName}"
|
||||
},
|
||||
{
|
||||
"title": "Amount",
|
||||
"value": "${formatNumber(amount, 2)}"
|
||||
},
|
||||
{
|
||||
"title": "Category",
|
||||
"value": "${if(expenseCategory, expenseCategory, 'N/A')}"
|
||||
},
|
||||
{
|
||||
"title": "Description",
|
||||
"value": "${if(description, description, 'N/A')}"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
|
||||
},
|
||||
"credit": {
|
||||
"type": "AdaptiveCard",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"size": "medium",
|
||||
"weight": "bolder",
|
||||
"color": "good",
|
||||
"text": "Credit"
|
||||
},
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Budget",
|
||||
"value": "${budgetName}"
|
||||
},
|
||||
{
|
||||
"title": "Amount",
|
||||
"value": "${formatNumber(amount, 2)}"
|
||||
},
|
||||
{
|
||||
"title": "Description",
|
||||
"value": "${if(description, description, 'N/A')}"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Combined Static and Dynamic Templates
|
||||
Use static template as default when item doesn't have template_selector or when value doesn't resolve.
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.items",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"template_selector": "$.templateId"
|
||||
},
|
||||
"static_template": {
|
||||
"type": "AdaptiveCard",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Default: ${name}",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response Semantics Properties
|
||||
|
||||
### data_path
|
||||
JSONPath query indicating where data resides in API response:
|
||||
```json
|
||||
"data_path": "$" // Root of response
|
||||
"data_path": "$.results" // In results property
|
||||
"data_path": "$.data.items"// Nested path
|
||||
```
|
||||
|
||||
### properties
|
||||
Map response fields for Copilot citations:
|
||||
```json
|
||||
"properties": {
|
||||
"title": "$.name", // Citation title
|
||||
"subtitle": "$.description", // Citation subtitle
|
||||
"url": "$.link" // Citation link
|
||||
}
|
||||
```
|
||||
|
||||
### template_selector
|
||||
Property on each item indicating which template to use:
|
||||
```json
|
||||
"template_selector": "$.displayTemplate"
|
||||
```
|
||||
|
||||
## Adaptive Card Template Language
|
||||
|
||||
### Conditional Rendering
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${if(field, field, 'N/A')}" // Show field or 'N/A'
|
||||
}
|
||||
```
|
||||
|
||||
### Number Formatting
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${formatNumber(amount, 2)}" // Two decimal places
|
||||
}
|
||||
```
|
||||
|
||||
### Data Binding
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}", // Break to root context
|
||||
"items": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Display
|
||||
```json
|
||||
{
|
||||
"type": "Image",
|
||||
"url": "${imageUrl}",
|
||||
"$when": "${imageUrl != null}" // Only show if imageUrl exists
|
||||
}
|
||||
```
|
||||
|
||||
## Card Elements
|
||||
|
||||
### TextBlock
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Text content",
|
||||
"size": "medium", // small, default, medium, large, extraLarge
|
||||
"weight": "bolder", // lighter, default, bolder
|
||||
"color": "attention", // default, dark, light, accent, good, warning, attention
|
||||
"wrap": true
|
||||
}
|
||||
```
|
||||
|
||||
### FactSet
|
||||
```json
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Label",
|
||||
"value": "Value"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Image
|
||||
```json
|
||||
{
|
||||
"type": "Image",
|
||||
"url": "https://example.com/image.png",
|
||||
"size": "medium", // auto, stretch, small, medium, large
|
||||
"style": "default" // default, person
|
||||
}
|
||||
```
|
||||
|
||||
### Container
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${items}", // Iterate over array
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${name}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### ColumnSet
|
||||
```json
|
||||
{
|
||||
"type": "ColumnSet",
|
||||
"columns": [
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "auto",
|
||||
"items": [ ... ]
|
||||
},
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "stretch",
|
||||
"items": [ ... ]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Actions
|
||||
```json
|
||||
{
|
||||
"type": "Action.OpenUrl",
|
||||
"title": "View Details",
|
||||
"url": "https://example.com/item/${id}"
|
||||
}
|
||||
```
|
||||
|
||||
## Responsive Design Best Practices
|
||||
|
||||
### Single-Column Layouts
|
||||
- Use single columns for narrow viewports
|
||||
- Avoid multi-column layouts when possible
|
||||
- Ensure cards work at minimum viewport width
|
||||
|
||||
### Flexible Widths
|
||||
- Don't assign fixed widths to elements
|
||||
- Use "auto" or "stretch" for width properties
|
||||
- Allow elements to resize with viewport
|
||||
- Fixed widths OK for icons/avatars only
|
||||
|
||||
### Text and Images
|
||||
- Avoid placing text and images in same row
|
||||
- Exception: Small icons or avatars
|
||||
- Use "wrap": true for text content
|
||||
- Test at various viewport widths
|
||||
|
||||
### Test Across Hubs
|
||||
Validate cards in:
|
||||
- Teams (desktop and mobile)
|
||||
- Word
|
||||
- PowerPoint
|
||||
- Various viewport widths (contract/expand UI)
|
||||
|
||||
## Complete Example
|
||||
|
||||
**ai-plugin.json:**
|
||||
```json
|
||||
{
|
||||
"functions": [
|
||||
{
|
||||
"name": "SearchProjects",
|
||||
"description": "Search for projects with status and details",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.projects",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.status",
|
||||
"url": "$.projectUrl"
|
||||
},
|
||||
"static_template": {
|
||||
"type": "AdaptiveCard",
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"size": "medium",
|
||||
"weight": "bolder",
|
||||
"text": "${if(name, name, 'Untitled Project')}",
|
||||
"wrap": true
|
||||
},
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Status",
|
||||
"value": "${status}"
|
||||
},
|
||||
{
|
||||
"title": "Owner",
|
||||
"value": "${if(owner, owner, 'Unassigned')}"
|
||||
},
|
||||
{
|
||||
"title": "Due Date",
|
||||
"value": "${if(dueDate, dueDate, 'Not set')}"
|
||||
},
|
||||
{
|
||||
"title": "Budget",
|
||||
"value": "${if(budget, formatNumber(budget, 2), 'N/A')}"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${if(description, description, 'No description')}",
|
||||
"wrap": true,
|
||||
"separator": true
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
{
|
||||
"type": "Action.OpenUrl",
|
||||
"title": "View Project",
|
||||
"url": "${projectUrl}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
Ask the user:
|
||||
1. What type of data does the API return?
|
||||
2. Are all items the same type (static) or different types (dynamic)?
|
||||
3. What fields should appear in the card?
|
||||
4. Should there be actions (e.g., "View Details")?
|
||||
5. Are there multiple states or categories requiring different templates?
|
||||
|
||||
Then generate:
|
||||
- Appropriate response_semantics configuration
|
||||
- Static template, dynamic templates, or both
|
||||
- Proper data binding with conditional rendering
|
||||
- Responsive single-column layout
|
||||
- Test scenarios for validation
|
||||
|
||||
## Resources
|
||||
|
||||
- [Adaptive Card Designer](https://adaptivecards.microsoft.com/designer) - Visual design tool
|
||||
- [Adaptive Card Schema](https://adaptivecards.io/schemas/adaptive-card.json) - Full schema reference
|
||||
- [Template Language](https://learn.microsoft.com/en-us/adaptive-cards/templating/language) - Binding syntax guide
|
||||
- [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) - Path query syntax
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### List with Images
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${items}",
|
||||
"items": [
|
||||
{
|
||||
"type": "ColumnSet",
|
||||
"columns": [
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "auto",
|
||||
"items": [
|
||||
{
|
||||
"type": "Image",
|
||||
"url": "${thumbnailUrl}",
|
||||
"size": "small",
|
||||
"$when": "${thumbnailUrl != null}"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "stretch",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${title}",
|
||||
"weight": "bolder",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Status Indicators
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${status}",
|
||||
"color": "${if(status == 'Completed', 'good', if(status == 'In Progress', 'attention', 'default'))}"
|
||||
}
|
||||
```
|
||||
|
||||
### Currency Formatting
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "$${formatNumber(amount, 2)}"
|
||||
}
|
||||
```
|
||||
|
||||
````
|
||||
310
prompts/mcp-create-declarative-agent.prompt.md
Normal file
310
prompts/mcp-create-declarative-agent.prompt.md
Normal file
@@ -0,0 +1,310 @@
|
||||
````prompt
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Create a declarative agent for Microsoft 365 Copilot by integrating an MCP server with authentication, tool selection, and configuration'
|
||||
model: 'gpt-4.1'
|
||||
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
|
||||
---
|
||||
|
||||
# Create MCP-based Declarative Agent for Microsoft 365 Copilot
|
||||
|
||||
Create a complete declarative agent for Microsoft 365 Copilot that integrates with a Model Context Protocol (MCP) server to access external systems and data.
|
||||
|
||||
## Requirements
|
||||
|
||||
Generate the following project structure using Microsoft 365 Agents Toolkit:
|
||||
|
||||
### Project Setup
|
||||
1. **Scaffold declarative agent** via Agents Toolkit
|
||||
2. **Add MCP action** pointing to MCP server
|
||||
3. **Select tools** to import from MCP server
|
||||
4. **Configure authentication** (OAuth 2.0 or SSO)
|
||||
5. **Review generated files** (manifest.json, ai-plugin.json, declarativeAgent.json)
|
||||
|
||||
### Key Files Generated
|
||||
|
||||
**appPackage/manifest.json** - Teams app manifest with plugin reference:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
|
||||
"manifestVersion": "devPreview",
|
||||
"version": "1.0.0",
|
||||
"id": "...",
|
||||
"developer": {
|
||||
"name": "...",
|
||||
"websiteUrl": "...",
|
||||
"privacyUrl": "...",
|
||||
"termsOfUseUrl": "..."
|
||||
},
|
||||
"name": {
|
||||
"short": "Agent Name",
|
||||
"full": "Full Agent Name"
|
||||
},
|
||||
"description": {
|
||||
"short": "Short description",
|
||||
"full": "Full description"
|
||||
},
|
||||
"copilotAgents": {
|
||||
"declarativeAgents": [
|
||||
{
|
||||
"id": "declarativeAgent",
|
||||
"file": "declarativeAgent.json"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**appPackage/declarativeAgent.json** - Agent definition:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://aka.ms/json-schemas/copilot/declarative-agent/v1.0/schema.json",
|
||||
"version": "v1.0",
|
||||
"name": "Agent Name",
|
||||
"description": "Agent description",
|
||||
"instructions": "You are an assistant that helps with [specific domain]. Use the available tools to [capabilities].",
|
||||
"capabilities": [
|
||||
{
|
||||
"name": "WebSearch",
|
||||
"websites": [
|
||||
{
|
||||
"url": "https://learn.microsoft.com"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "MCP",
|
||||
"file": "ai-plugin.json"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**appPackage/ai-plugin.json** - MCP plugin manifest:
|
||||
```json
|
||||
{
|
||||
"schema_version": "v2.1",
|
||||
"name_for_human": "Service Name",
|
||||
"description_for_human": "Description for users",
|
||||
"description_for_model": "Description for AI model",
|
||||
"contact_email": "support@company.com",
|
||||
"namespace": "serviceName",
|
||||
"capabilities": {
|
||||
"conversation_starters": [
|
||||
{
|
||||
"text": "Example query 1"
|
||||
}
|
||||
]
|
||||
},
|
||||
"functions": [
|
||||
{
|
||||
"name": "functionName",
|
||||
"description": "Function description",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$",
|
||||
"properties": {
|
||||
"title": "$.title",
|
||||
"subtitle": "$.description"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"runtimes": [
|
||||
{
|
||||
"type": "MCP",
|
||||
"spec": {
|
||||
"url": "https://api.service.com/mcp/"
|
||||
},
|
||||
"run_for_functions": ["functionName"],
|
||||
"auth": {
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "${{OAUTH_REFERENCE_ID}}"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**/.vscode/mcp.json** - MCP server configuration:
|
||||
```json
|
||||
{
|
||||
"serverUrl": "https://api.service.com/mcp/",
|
||||
"pluginFilePath": "appPackage/ai-plugin.json"
|
||||
}
|
||||
```
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
### Supported MCP Endpoints
|
||||
The MCP server must provide:
|
||||
- **Server metadata** endpoint
|
||||
- **Tools listing** endpoint (exposes available functions)
|
||||
- **Tool execution** endpoint (handles function calls)
|
||||
|
||||
### Tool Selection
|
||||
When importing from MCP:
|
||||
1. Fetch available tools from server
|
||||
2. Select specific tools to include (for security/simplicity)
|
||||
3. Tool definitions are auto-generated in ai-plugin.json
|
||||
|
||||
### Authentication Types
|
||||
|
||||
**OAuth 2.0 (Static Registration)**
|
||||
```json
|
||||
"auth": {
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "${{OAUTH_REFERENCE_ID}}",
|
||||
"authorization_url": "https://auth.service.com/authorize",
|
||||
"client_id": "${{CLIENT_ID}}",
|
||||
"client_secret": "${{CLIENT_SECRET}}",
|
||||
"scope": "read write"
|
||||
}
|
||||
```
|
||||
|
||||
**Single Sign-On (SSO)**
|
||||
```json
|
||||
"auth": {
|
||||
"type": "SSO"
|
||||
}
|
||||
```
|
||||
|
||||
## Response Semantics
|
||||
|
||||
### Define Data Mapping
|
||||
Use `response_semantics` to extract relevant fields from API responses:
|
||||
|
||||
```json
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.results",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.description",
|
||||
"url": "$.link"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add Adaptive Cards (Optional)
|
||||
See the `mcp-create-adaptive-cards` prompt for adding visual card templates.
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Create `.env.local` or `.env.dev` for credentials:
|
||||
|
||||
```env
|
||||
OAUTH_REFERENCE_ID=your-oauth-reference-id
|
||||
CLIENT_ID=your-client-id
|
||||
CLIENT_SECRET=your-client-secret
|
||||
```
|
||||
|
||||
## Testing & Deployment
|
||||
|
||||
### Local Testing
|
||||
1. **Provision** agent in Agents Toolkit
|
||||
2. **Start debugging** to sideload in Teams
|
||||
3. Test in Microsoft 365 Copilot at https://m365.cloud.microsoft/chat
|
||||
4. Authenticate when prompted
|
||||
5. Query the agent using natural language
|
||||
|
||||
### Validation
|
||||
- Verify tool imports in ai-plugin.json
|
||||
- Check authentication configuration
|
||||
- Test each exposed function
|
||||
- Validate response data mapping
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Tool Design
|
||||
- **Focused functions**: Each tool should do one thing well
|
||||
- **Clear descriptions**: Help the model understand when to use each tool
|
||||
- **Minimal scoping**: Only import tools the agent needs
|
||||
- **Descriptive names**: Use action-oriented function names
|
||||
|
||||
### Security
|
||||
- **Use OAuth 2.0** for production scenarios
|
||||
- **Store secrets** in environment variables
|
||||
- **Validate inputs** on the MCP server side
|
||||
- **Limit scopes** to minimum required permissions
|
||||
- **Use reference IDs** for OAuth registration
|
||||
|
||||
### Instructions
|
||||
- **Be specific** about the agent's purpose and capabilities
|
||||
- **Define behavior** for both successful and error scenarios
|
||||
- **Reference tools** explicitly in instructions when applicable
|
||||
- **Set expectations** for users about what the agent can/cannot do
|
||||
|
||||
### Performance
|
||||
- **Cache responses** when appropriate on MCP server
|
||||
- **Batch operations** where possible
|
||||
- **Set timeouts** for long-running operations
|
||||
- **Paginate results** for large datasets
|
||||
|
||||
## Common MCP Server Examples
|
||||
|
||||
### GitHub MCP Server
|
||||
```
|
||||
URL: https://api.githubcopilot.com/mcp/
|
||||
Tools: search_repositories, search_users, get_repository
|
||||
Auth: OAuth 2.0
|
||||
```
|
||||
|
||||
### Jira MCP Server
|
||||
```
|
||||
URL: https://your-domain.atlassian.net/mcp/
|
||||
Tools: search_issues, create_issue, update_issue
|
||||
Auth: OAuth 2.0
|
||||
```
|
||||
|
||||
### Custom Service
|
||||
```
|
||||
URL: https://api.your-service.com/mcp/
|
||||
Tools: Custom tools exposed by your service
|
||||
Auth: OAuth 2.0 or SSO
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
Ask the user:
|
||||
1. What MCP server are you integrating with (URL)?
|
||||
2. What tools should be exposed to Copilot?
|
||||
3. What authentication method does the server support?
|
||||
4. What should the agent's primary purpose be?
|
||||
5. Do you need response semantics or Adaptive Cards?
|
||||
|
||||
Then generate:
|
||||
- Complete appPackage/ structure (manifest.json, declarativeAgent.json, ai-plugin.json)
|
||||
- mcp.json configuration
|
||||
- .env.local template
|
||||
- Provisioning and testing instructions
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### MCP Server Not Responding
|
||||
- Verify server URL is correct
|
||||
- Check network connectivity
|
||||
- Validate MCP server implements required endpoints
|
||||
|
||||
### Authentication Fails
|
||||
- Verify OAuth credentials are correct
|
||||
- Check reference ID matches registration
|
||||
- Confirm scopes are requested properly
|
||||
- Test OAuth flow independently
|
||||
|
||||
### Tools Not Appearing
|
||||
- Ensure mcp.json points to correct server
|
||||
- Verify tools were selected during import
|
||||
- Check ai-plugin.json has correct function definitions
|
||||
- Re-fetch actions from MCP if server changed
|
||||
|
||||
### Agent Not Understanding Queries
|
||||
- Review instructions in declarativeAgent.json
|
||||
- Check function descriptions are clear
|
||||
- Verify response_semantics extract correct data
|
||||
- Test with more specific queries
|
||||
|
||||
````
|
||||
336
prompts/mcp-deploy-manage-agents.prompt.md
Normal file
336
prompts/mcp-deploy-manage-agents.prompt.md
Normal file
@@ -0,0 +1,336 @@
|
||||
````prompt
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Deploy and manage MCP-based declarative agents in Microsoft 365 admin center with governance, assignments, and organizational distribution'
|
||||
model: 'gpt-4.1'
|
||||
tags: [mcp, m365-copilot, deployment, admin, agent-management, governance]
|
||||
---
|
||||
|
||||
# Deploy and Manage MCP-Based Agents
|
||||
|
||||
Deploy, manage, and govern MCP-based declarative agents in Microsoft 365 using the admin center for organizational distribution and control.
|
||||
|
||||
## Agent Types
|
||||
|
||||
### Published by Organization
|
||||
- Built with predefined instructions and actions
|
||||
- Follow structured logic for predictable tasks
|
||||
- Require admin approval and publishing process
|
||||
- Support compliance and governance requirements
|
||||
|
||||
### Shared by Creator
|
||||
- Created in Microsoft 365 Copilot Studio or Agent Builder
|
||||
- Shared directly with specific users
|
||||
- Enhanced functionality with search, actions, connectors, APIs
|
||||
- Visible to admins in agent registry
|
||||
|
||||
### Microsoft Agents
|
||||
- Developed and maintained by Microsoft
|
||||
- Integrated with Microsoft 365 services
|
||||
- Pre-approved and ready to use
|
||||
|
||||
### External Partner Agents
|
||||
- Created by verified external developers/vendors
|
||||
- Subject to admin approval and control
|
||||
- Configurable availability and permissions
|
||||
|
||||
### Frontier Agents
|
||||
- Experimental or advanced capabilities
|
||||
- May require limited rollout or additional oversight
|
||||
- Examples:
|
||||
- **App Builder agent**: Managed via M365 Copilot or Power Platform admin center
|
||||
- **Workflows agent**: Flow automation managed via Power Platform admin center
|
||||
|
||||
## Admin Roles and Permissions
|
||||
|
||||
### Required Roles
|
||||
- **AI Admin**: Full agent management capabilities
|
||||
- **Global Reader**: View-only access (no editing)
|
||||
|
||||
### Best Practices
|
||||
- Use roles with fewest permissions
|
||||
- Limit Global Administrator to emergency scenarios
|
||||
- Follow principle of least privilege
|
||||
|
||||
## Agent Management in Microsoft 365 Admin Center
|
||||
|
||||
### Access Agent Management
|
||||
1. Go to [Microsoft 365 admin center](https://admin.microsoft.com/)
|
||||
2. Navigate to **Agents** page
|
||||
3. View available, deployed, or blocked agents
|
||||
|
||||
### Available Actions
|
||||
|
||||
**View Agents**
|
||||
- Filter by availability (available, deployed, blocked)
|
||||
- Search for specific agents
|
||||
- View agent details (name, creator, date, host products, status)
|
||||
|
||||
**Deploy Agents**
|
||||
Options for distribution:
|
||||
1. **Agent Store**: Submit to Partner Center for validation and public availability
|
||||
2. **Organization Deployment**: IT admin deploys to all or selected employees
|
||||
|
||||
**Manage Agent Lifecycle**
|
||||
- **Publish**: Make agent available to organization
|
||||
- **Deploy**: Assign to specific users or groups
|
||||
- **Block**: Prevent agent from being used
|
||||
- **Remove**: Delete agent from organization
|
||||
|
||||
**Configure Access**
|
||||
- Set availability for specific user groups
|
||||
- Manage permissions per agent
|
||||
- Control which agents appear in Copilot
|
||||
|
||||
## Deployment Workflows
|
||||
|
||||
### Publish to Organization
|
||||
|
||||
**For Agent Developers:**
|
||||
1. Build agent with Microsoft 365 Agents Toolkit
|
||||
2. Test thoroughly in development
|
||||
3. Submit agent for approval
|
||||
4. Wait for admin review
|
||||
|
||||
**For Admins:**
|
||||
1. Review submitted agent in admin center
|
||||
2. Validate compliance and security
|
||||
3. Approve for organizational use
|
||||
4. Configure deployment settings
|
||||
5. Publish to selected users or organization-wide
|
||||
|
||||
### Deploy via Agent Store
|
||||
|
||||
**Developer Steps:**
|
||||
1. Complete agent development and testing
|
||||
2. Package agent for submission
|
||||
3. Submit to Partner Center
|
||||
4. Await validation process
|
||||
5. Receive approval notification
|
||||
6. Agent appears in Copilot store
|
||||
|
||||
**Admin Steps:**
|
||||
1. Discover agents in Copilot store
|
||||
2. Review agent details and permissions
|
||||
3. Assign to organization or user groups
|
||||
4. Monitor usage and feedback
|
||||
|
||||
### Deploy Organizational Agent
|
||||
|
||||
**Admin Deployment Options:**
|
||||
```
|
||||
Organization-wide:
|
||||
- All employees with Copilot license
|
||||
- Automatically available in Copilot
|
||||
|
||||
Group-based:
|
||||
- Specific departments or teams
|
||||
- Security group assignments
|
||||
- Role-based access control
|
||||
```
|
||||
|
||||
**Configuration Steps:**
|
||||
1. Navigate to Agents page in admin center
|
||||
2. Select agent to deploy
|
||||
3. Choose deployment scope:
|
||||
- All users
|
||||
- Specific security groups
|
||||
- Individual users
|
||||
4. Set availability status
|
||||
5. Configure permissions if applicable
|
||||
6. Deploy and monitor
|
||||
|
||||
## User Experience
|
||||
|
||||
### Agent Discovery
|
||||
Users find agents in:
|
||||
- Microsoft 365 Copilot hub
|
||||
- Agent picker in Copilot interface
|
||||
- Organization's agent catalog
|
||||
|
||||
### Agent Access Control
|
||||
Users can:
|
||||
- Toggle agents on/off during interactions
|
||||
- Add/remove agents from their experience
|
||||
- Right-click agents to manage preferences
|
||||
- Only access admin-allowed agents
|
||||
|
||||
### Agent Usage
|
||||
- Agents appear in Copilot sidebar
|
||||
- Users select agent for context
|
||||
- Queries routed through selected agent
|
||||
- Responses leverage agent's capabilities
|
||||
|
||||
## Governance and Compliance
|
||||
|
||||
### Security Considerations
|
||||
- **Data access**: Review what data agent can access
|
||||
- **API permissions**: Validate required scopes
|
||||
- **Authentication**: Ensure secure OAuth flows
|
||||
- **External connections**: Assess risk of external integrations
|
||||
|
||||
### Compliance Requirements
|
||||
- **Data residency**: Verify data stays within boundaries
|
||||
- **Privacy policies**: Review agent privacy statement
|
||||
- **Terms of use**: Validate acceptable use policies
|
||||
- **Audit logs**: Monitor agent usage and activity
|
||||
|
||||
### Monitoring and Reporting
|
||||
Track:
|
||||
- Agent adoption rates
|
||||
- User feedback and satisfaction
|
||||
- Error rates and performance
|
||||
- Security incidents or violations
|
||||
|
||||
## MCP-Specific Management
|
||||
|
||||
### MCP Agent Characteristics
|
||||
- Connect to external systems via Model Context Protocol
|
||||
- Use tools exposed by MCP servers
|
||||
- Require OAuth 2.0 or SSO authentication
|
||||
- Support same governance as REST API agents
|
||||
|
||||
### MCP Agent Validation
|
||||
Verify:
|
||||
- MCP server URL is accessible
|
||||
- Authentication configuration is secure
|
||||
- Tools imported are appropriate
|
||||
- Response data doesn't expose sensitive info
|
||||
- Server follows security best practices
|
||||
|
||||
### MCP Agent Deployment
|
||||
Same process as REST API agents:
|
||||
1. Review in admin center
|
||||
2. Validate MCP server compliance
|
||||
3. Test authentication flow
|
||||
4. Deploy to users/groups
|
||||
5. Monitor performance
|
||||
|
||||
## Agent Settings and Configuration
|
||||
|
||||
### Organizational Settings
|
||||
Configure at tenant level:
|
||||
- Enable/disable agent creation
|
||||
- Set default permissions
|
||||
- Configure approval workflows
|
||||
- Define compliance policies
|
||||
|
||||
### Per-Agent Settings
|
||||
Configure for individual agents:
|
||||
- Availability (on/off)
|
||||
- User assignment (all/groups/individuals)
|
||||
- Permission scopes
|
||||
- Usage limits or quotas
|
||||
|
||||
### Environment Routing
|
||||
For Power Platform-based agents:
|
||||
- Configure default environment
|
||||
- Enable environment routing for Copilot Studio
|
||||
- Manage flows via Power Platform admin center
|
||||
|
||||
## Shared Agent Management
|
||||
|
||||
### View Shared Agents
|
||||
Admins can see:
|
||||
- List of all shared agents
|
||||
- Creator information
|
||||
- Creation date
|
||||
- Host products
|
||||
- Availability status
|
||||
|
||||
### Manage Shared Agents
|
||||
Admin actions:
|
||||
- Search for specific shared agents
|
||||
- View agent capabilities
|
||||
- Block unsafe or non-compliant agents
|
||||
- Monitor agent lifecycle
|
||||
|
||||
### User Access to Shared Agents
|
||||
Users access through:
|
||||
- Microsoft 365 Copilot on various surfaces
|
||||
- Agent-specific tasks and assistance
|
||||
- Creator-defined capabilities
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Deployment
|
||||
- **Pilot test** with small user group
|
||||
- **Gather feedback** from early adopters
|
||||
- **Validate security** and compliance
|
||||
- **Document** agent capabilities and limitations
|
||||
- **Train users** on agent usage
|
||||
|
||||
### During Deployment
|
||||
- **Phased rollout** to manage adoption
|
||||
- **Monitor performance** and errors
|
||||
- **Collect feedback** continuously
|
||||
- **Address issues** promptly
|
||||
- **Communicate** availability to users
|
||||
|
||||
### Post-Deployment
|
||||
- **Track metrics**: Adoption, satisfaction, errors
|
||||
- **Iterate**: Improve based on feedback
|
||||
- **Update**: Keep agent current with new features
|
||||
- **Retire**: Remove obsolete or unused agents
|
||||
- **Review**: Regular security and compliance audits
|
||||
|
||||
### Communication
|
||||
- Announce new agents to users
|
||||
- Provide documentation and examples
|
||||
- Share best practices and use cases
|
||||
- Highlight benefits and capabilities
|
||||
- Offer support channels
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent Not Appearing
|
||||
- Check deployment status in admin center
|
||||
- Verify user is in assigned group
|
||||
- Confirm agent is not blocked
|
||||
- Check user has Copilot license
|
||||
- Refresh Copilot interface
|
||||
|
||||
### Authentication Failures
|
||||
- Verify OAuth credentials are valid
|
||||
- Check user has necessary permissions
|
||||
- Confirm MCP server is accessible
|
||||
- Test authentication flow independently
|
||||
|
||||
### Performance Issues
|
||||
- Monitor MCP server response times
|
||||
- Check network connectivity
|
||||
- Review error logs in admin center
|
||||
- Validate agent isn't rate-limited
|
||||
|
||||
### Compliance Violations
|
||||
- Block agent immediately if unsafe
|
||||
- Review audit logs for violations
|
||||
- Investigate data access patterns
|
||||
- Update policies to prevent recurrence
|
||||
|
||||
## Resources
|
||||
|
||||
- [Microsoft 365 admin center](https://admin.microsoft.com/)
|
||||
- [Power Platform admin center](https://admin.powerplatform.microsoft.com/)
|
||||
- [Partner Center](https://partner.microsoft.com/) for agent submissions
|
||||
- [Microsoft Agent 365 Overview](https://learn.microsoft.com/en-us/microsoft-agent-365/overview)
|
||||
- [Agent Registry Documentation](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/agent-registry)
|
||||
|
||||
## Workflow
|
||||
|
||||
Ask the user:
|
||||
1. Is this agent ready for deployment or still in development?
|
||||
2. Who should have access (all users, specific groups, individuals)?
|
||||
3. Are there compliance or security requirements to address?
|
||||
4. Should this be published to the organization or the public store?
|
||||
5. What monitoring and reporting is needed?
|
||||
|
||||
Then provide:
|
||||
- Step-by-step deployment guide
|
||||
- Admin center configuration steps
|
||||
- User assignment recommendations
|
||||
- Governance and compliance checklist
|
||||
- Monitoring and reporting plan
|
||||
|
||||
````
|
||||
Reference in New Issue
Block a user