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
325
collections/mcp-m365-copilot.collection.md
Normal file
325
collections/mcp-m365-copilot.collection.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# MCP-based M365 Agents Collection
|
||||
|
||||
A comprehensive collection of prompts and instructions for building declarative agents with Model Context Protocol (MCP) integration for Microsoft 365 Copilot.
|
||||
|
||||
## Overview
|
||||
|
||||
The Model Context Protocol (MCP) is a universal standard that allows AI models to integrate with external systems through standardized server endpoints. This collection provides everything you need to build, deploy, and manage MCP-based declarative agents that extend Microsoft 365 Copilot with custom capabilities.
|
||||
|
||||
## What is Model Context Protocol?
|
||||
|
||||
MCP is an open protocol developed to streamline how AI models connect to external data sources and tools. Instead of custom integration code for each system, MCP provides a consistent interface for:
|
||||
|
||||
- **Server Metadata**: Discover available tools and capabilities
|
||||
- **Tools Listing**: Get function definitions and schemas
|
||||
- **Tool Execution**: Invoke tools with parameters and receive results
|
||||
|
||||
For Microsoft 365 Copilot, this means you can create agents that connect to any MCP-compatible server with point-and-click configuration instead of writing custom code.
|
||||
|
||||
## Collection Contents
|
||||
|
||||
### Prompts
|
||||
|
||||
1. **Create Declarative Agent** ([mcp-create-declarative-agent.prompt.md](prompts/mcp-create-declarative-agent.prompt.md))
|
||||
- Build declarative agents using Microsoft 365 Agents Toolkit
|
||||
- Configure MCP server integration with tool import
|
||||
- Set up OAuth 2.0 or SSO authentication
|
||||
- Configure response semantics for data extraction
|
||||
- Package and deploy agents for testing
|
||||
|
||||
2. **Create Adaptive Cards** ([mcp-create-adaptive-cards.prompt.md](prompts/mcp-create-adaptive-cards.prompt.md))
|
||||
- Design static and dynamic Adaptive Card templates
|
||||
- Configure response semantics (data_path, properties, template_selector)
|
||||
- Use template language for conditionals and data binding
|
||||
- Create responsive cards that work across Copilot surfaces
|
||||
- Implement card actions for user interactions
|
||||
|
||||
3. **Deploy and Manage Agents** ([mcp-deploy-manage-agents.prompt.md](prompts/mcp-deploy-manage-agents.prompt.md))
|
||||
- Deploy agents via Microsoft 365 admin center
|
||||
- Configure organizational or public store distribution
|
||||
- Manage agent lifecycle (publish, deploy, block, remove)
|
||||
- Set up governance and compliance controls
|
||||
- Monitor agent usage and performance
|
||||
|
||||
### Instructions
|
||||
|
||||
**MCP M365 Copilot Development Guidelines** ([mcp-m365-copilot.instructions.md](instructions/mcp-m365-copilot.instructions.md))
|
||||
- Best practices for MCP server design and tool selection
|
||||
- File organization and project structure
|
||||
- Response semantics configuration patterns
|
||||
- Adaptive Card design principles
|
||||
- Security, governance, and compliance requirements
|
||||
- Testing and deployment workflows
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Declarative Agents
|
||||
|
||||
Declarative agents are defined through configuration files rather than code:
|
||||
- **declarativeAgent.json**: Agent instructions, capabilities, conversation starters
|
||||
- **ai-plugin.json**: MCP server tools, response semantics, adaptive card templates
|
||||
- **mcp.json**: MCP server URL, authentication configuration
|
||||
- **manifest.json**: Teams app manifest for packaging
|
||||
|
||||
### MCP Server Integration
|
||||
|
||||
The Microsoft 365 Agents Toolkit provides a visual interface for:
|
||||
1. **Scaffold** a new agent project
|
||||
2. **Add MCP action** to connect to a server
|
||||
3. **Choose tools** from the server's available functions
|
||||
4. **Configure authentication** (OAuth 2.0, SSO)
|
||||
5. **Generate files** (agent config, plugin manifest)
|
||||
6. **Test** in m365.cloud.microsoft/chat
|
||||
|
||||
### Authentication Patterns
|
||||
|
||||
**OAuth 2.0 Static Registration:**
|
||||
- Pre-register OAuth app with service provider
|
||||
- Store credentials in .env.local (never commit)
|
||||
- Reference in ai-plugin.json authentication config
|
||||
- Users consent once, tokens stored in plugin vault
|
||||
|
||||
**Single Sign-On (SSO):**
|
||||
- Use Microsoft Entra ID for authentication
|
||||
- Seamless experience for M365 users
|
||||
- No separate login required
|
||||
- Ideal for internal organizational agents
|
||||
|
||||
### Response Semantics
|
||||
|
||||
Extract and format data from MCP server responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"response_semantics": {
|
||||
"data_path": "$.items[*]",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.description",
|
||||
"url": "$.html_url"
|
||||
},
|
||||
"static_template": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **data_path**: JSONPath to extract array or object
|
||||
- **properties**: Map response fields to Copilot properties
|
||||
- **template_selector**: Choose dynamic template based on response
|
||||
- **static_template**: Adaptive Card for visual formatting
|
||||
|
||||
### Adaptive Cards
|
||||
|
||||
Rich visual responses for agent outputs:
|
||||
|
||||
**Static Templates:**
|
||||
- Defined once in ai-plugin.json
|
||||
- Used for all responses with same structure
|
||||
- Better performance and easier maintenance
|
||||
|
||||
**Dynamic Templates:**
|
||||
- Returned in API response body
|
||||
- Selected via template_selector JSONPath
|
||||
- Useful for varied response structures
|
||||
|
||||
**Template Language:**
|
||||
- `${property}`: Data binding
|
||||
- `${if(condition, true, false)}`: Conditionals
|
||||
- `${formatNumber(value, decimals)}`: Formatting
|
||||
- `$when`: Conditional element rendering
|
||||
|
||||
## Deployment Options
|
||||
|
||||
### Organization Deployment
|
||||
- IT admin deploys to all users or specific groups
|
||||
- Requires approval in Microsoft 365 admin center
|
||||
- Best for internal business agents
|
||||
- Full governance and compliance controls
|
||||
|
||||
### Agent Store
|
||||
- Submit to Partner Center for validation
|
||||
- Public availability to all Copilot users
|
||||
- Rigorous security and compliance review
|
||||
- Suitable for partner-built agents
|
||||
|
||||
## Partner Examples
|
||||
|
||||
### monday.com
|
||||
Task and project management integration:
|
||||
- Create tasks directly from Copilot
|
||||
- Query project status and updates
|
||||
- Assign work items to team members
|
||||
- View deadlines and milestones
|
||||
|
||||
### Canva
|
||||
Design automation capabilities:
|
||||
- Generate branded content
|
||||
- Create social media graphics
|
||||
- Access design templates
|
||||
- Export in multiple formats
|
||||
|
||||
### Sitecore
|
||||
Content management integration:
|
||||
- Search content repository
|
||||
- Create and update content items
|
||||
- Manage workflows and approvals
|
||||
- Preview content in context
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
- Visual Studio Code
|
||||
- Microsoft 365 Agents Toolkit extension (v6.3.x or later)
|
||||
- GitHub account (for OAuth examples)
|
||||
- Microsoft 365 Copilot license
|
||||
- Access to an MCP-compatible server
|
||||
|
||||
### Quick Start
|
||||
1. Install Microsoft 365 Agents Toolkit in VS Code
|
||||
2. Use **Create Declarative Agent** prompt to scaffold project
|
||||
3. Add MCP server URL and choose tools
|
||||
4. Configure authentication with OAuth or SSO
|
||||
5. Use **Create Adaptive Cards** prompt to design response templates
|
||||
6. Test agent at m365.cloud.microsoft/chat
|
||||
7. Use **Deploy and Manage Agents** prompt for distribution
|
||||
|
||||
### Development Workflow
|
||||
```
|
||||
1. Scaffold agent project
|
||||
↓
|
||||
2. Connect MCP server
|
||||
↓
|
||||
3. Import tools
|
||||
↓
|
||||
4. Configure authentication
|
||||
↓
|
||||
5. Design adaptive cards
|
||||
↓
|
||||
6. Test locally
|
||||
↓
|
||||
7. Deploy to organization
|
||||
↓
|
||||
8. Monitor and iterate
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### MCP Server Design
|
||||
- Import only necessary tools (avoid over-scoping)
|
||||
- Use secure authentication (OAuth 2.0, SSO)
|
||||
- Test each tool individually
|
||||
- Validate server endpoints are HTTPS
|
||||
- Consider token limits when selecting tools
|
||||
|
||||
### Agent Instructions
|
||||
- Be specific and clear about agent capabilities
|
||||
- Provide examples of how to interact
|
||||
- Set boundaries for what agent can/cannot do
|
||||
- Use conversation starters to guide users
|
||||
|
||||
### Response Formatting
|
||||
- Use JSONPath to extract relevant data
|
||||
- Map properties clearly (title, subtitle, url)
|
||||
- Design adaptive cards for readability
|
||||
- Test cards across Copilot surfaces (Chat, Teams, Outlook)
|
||||
|
||||
### Security and Governance
|
||||
- Never commit credentials to source control
|
||||
- Use environment variables for secrets
|
||||
- Follow principle of least privilege
|
||||
- Review compliance requirements
|
||||
- Monitor agent usage and performance
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Data Retrieval
|
||||
- Search external systems
|
||||
- Fetch user-specific information
|
||||
- Query databases or APIs
|
||||
- Aggregate data from multiple sources
|
||||
|
||||
### Task Automation
|
||||
- Create tickets or tasks
|
||||
- Update records or statuses
|
||||
- Trigger workflows
|
||||
- Schedule actions
|
||||
|
||||
### Content Generation
|
||||
- Create documents or designs
|
||||
- Generate reports or summaries
|
||||
- Format data into templates
|
||||
- Export in various formats
|
||||
|
||||
### Integration Scenarios
|
||||
- Connect CRM systems
|
||||
- Integrate project management tools
|
||||
- Access knowledge bases
|
||||
- Connect to custom business apps
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent Not Appearing in Copilot
|
||||
- Verify agent is deployed in admin center
|
||||
- Check user is in assigned group
|
||||
- Confirm agent is not blocked
|
||||
- Refresh Copilot interface
|
||||
|
||||
### Authentication Errors
|
||||
- Validate OAuth credentials in .env.local
|
||||
- Check scopes match required permissions
|
||||
- Test auth flow independently
|
||||
- Verify MCP server is accessible
|
||||
|
||||
### Response Formatting Issues
|
||||
- Test JSONPath expressions with sample data
|
||||
- Validate data_path extracts expected array/object
|
||||
- Check property mappings are correct
|
||||
- Test adaptive card with various response structures
|
||||
|
||||
### Performance Problems
|
||||
- Monitor MCP server response times
|
||||
- Reduce number of imported tools
|
||||
- Optimize response data size
|
||||
- Use caching where appropriate
|
||||
|
||||
## Resources
|
||||
|
||||
### Official Documentation
|
||||
- [Build Declarative Agents with MCP (DevBlogs)](https://devblogs.microsoft.com/microsoft365dev/build-declarative-agents-for-microsoft-365-copilot-with-mcp/)
|
||||
- [Build MCP Plugins (Microsoft Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-mcp-plugins)
|
||||
- [API Plugin Adaptive Cards (Microsoft Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-adaptive-cards)
|
||||
- [Manage Copilot Agents (Microsoft Learn)](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps)
|
||||
|
||||
### Tools and Extensions
|
||||
- [Microsoft 365 Agents Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension)
|
||||
- [Adaptive Cards Designer](https://adaptivecards.io/designer/)
|
||||
- [Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teams-toolkit-fundamentals)
|
||||
|
||||
### MCP Resources
|
||||
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
|
||||
- [MCP Server Directory](https://github.com/modelcontextprotocol/servers)
|
||||
- Community MCP servers and examples
|
||||
|
||||
### Admin and Governance
|
||||
- [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
|
||||
|
||||
## Support and Community
|
||||
|
||||
- Join the [Microsoft 365 Developer Community](https://developer.microsoft.com/en-us/microsoft-365/community)
|
||||
- Ask questions on [Microsoft Q&A](https://learn.microsoft.com/en-us/answers/products/)
|
||||
- Share feedback in [Microsoft 365 Copilot GitHub discussions](https://github.com/microsoft/copilot-feedback)
|
||||
|
||||
## What's Next?
|
||||
|
||||
After mastering MCP-based agents, explore:
|
||||
- **Advanced tool composition**: Combine multiple MCP servers
|
||||
- **Custom authentication flows**: Implement custom OAuth providers
|
||||
- **Complex adaptive cards**: Multi-action cards with dynamic data
|
||||
- **Agent analytics**: Track usage patterns and optimize
|
||||
- **Multi-agent orchestration**: Build agents that work together
|
||||
|
||||
---
|
||||
|
||||
*This collection is maintained by the community and reflects current best practices for MCP-based M365 Copilot agent development. Contributions and feedback welcome!*
|
||||
18
collections/mcp-m365-copilot.collection.yml
Normal file
18
collections/mcp-m365-copilot.collection.yml
Normal file
@@ -0,0 +1,18 @@
|
||||
id: mcp-m365-copilot
|
||||
name: MCP-based M365 Agents
|
||||
description: Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot
|
||||
tags: [mcp, m365-copilot, declarative-agents, api-plugins, model-context-protocol, adaptive-cards]
|
||||
|
||||
display:
|
||||
order: manual
|
||||
show_badge: true
|
||||
|
||||
items:
|
||||
- kind: prompt
|
||||
path: prompts/mcp-create-declarative-agent.prompt.md
|
||||
- kind: prompt
|
||||
path: prompts/mcp-create-adaptive-cards.prompt.md
|
||||
- kind: prompt
|
||||
path: prompts/mcp-deploy-manage-agents.prompt.md
|
||||
- kind: instruction
|
||||
path: instructions/mcp-m365-copilot.instructions.md
|
||||
357
instructions/mcp-m365-copilot.instructions.md
Normal file
357
instructions/mcp-m365-copilot.instructions.md
Normal file
@@ -0,0 +1,357 @@
|
||||
---
|
||||
description: 'Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration'
|
||||
applyTo: '**/{*mcp*,*agent*,*plugin*,declarativeAgent.json,ai-plugin.json,mcp.json,manifest.json}'
|
||||
---
|
||||
|
||||
# MCP-based M365 Copilot Development Guidelines
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Model Context Protocol First
|
||||
- Leverage MCP servers for external system integration
|
||||
- Import tools from server endpoints, not manual definitions
|
||||
- Let MCP handle schema discovery and function generation
|
||||
- Use point-and-click tool selection in Agents Toolkit
|
||||
|
||||
### Declarative Over Imperative
|
||||
- Define agent behavior through configuration, not code
|
||||
- Use declarativeAgent.json for instructions and capabilities
|
||||
- Specify tools and actions in ai-plugin.json
|
||||
- Configure MCP servers in mcp.json
|
||||
|
||||
### Security and Governance
|
||||
- Always use OAuth 2.0 or SSO for authentication
|
||||
- Follow principle of least privilege for tool selection
|
||||
- Validate MCP server endpoints are secure
|
||||
- Review compliance requirements before deployment
|
||||
|
||||
### User-Centric Design
|
||||
- Create adaptive cards for rich visual responses
|
||||
- Provide clear conversation starters
|
||||
- Design for responsive experience across hubs
|
||||
- Test thoroughly before organizational deployment
|
||||
|
||||
## MCP Server Design
|
||||
|
||||
### Server Selection
|
||||
Choose MCP servers that:
|
||||
- Expose relevant tools for user tasks
|
||||
- Support secure authentication (OAuth 2.0, SSO)
|
||||
- Provide reliable uptime and performance
|
||||
- Follow MCP specification standards
|
||||
- Return well-structured response data
|
||||
|
||||
### Tool Import Strategy
|
||||
- Import only necessary tools (avoid over-scoping)
|
||||
- Group related tools from same server
|
||||
- Test each tool individually before combining
|
||||
- Consider token limits when selecting multiple tools
|
||||
|
||||
### Authentication Configuration
|
||||
**OAuth 2.0 Static Registration:**
|
||||
```json
|
||||
{
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "YOUR_AUTH_ID",
|
||||
"client_id": "github_client_id",
|
||||
"client_secret": "github_client_secret",
|
||||
"authorization_url": "https://github.com/login/oauth/authorize",
|
||||
"token_url": "https://github.com/login/oauth/access_token",
|
||||
"scope": "repo read:user"
|
||||
}
|
||||
```
|
||||
|
||||
**SSO (Microsoft Entra ID):**
|
||||
```json
|
||||
{
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "sso_auth",
|
||||
"authorization_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
|
||||
"token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
|
||||
"scope": "User.Read"
|
||||
}
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
project-root/
|
||||
├── appPackage/
|
||||
│ ├── manifest.json # Teams app manifest
|
||||
│ ├── declarativeAgent.json # Agent config (instructions, capabilities)
|
||||
│ ├── ai-plugin.json # API plugin definition
|
||||
│ ├── color.png # App icon color
|
||||
│ └── outline.png # App icon outline
|
||||
├── .vscode/
|
||||
│ └── mcp.json # MCP server configuration
|
||||
├── .env.local # Credentials (NEVER commit)
|
||||
└── teamsapp.yml # Teams Toolkit config
|
||||
```
|
||||
|
||||
### Critical Files
|
||||
|
||||
**declarativeAgent.json:**
|
||||
- Agent name and description
|
||||
- Instructions for behavior
|
||||
- Conversation starters
|
||||
- Capabilities (actions from plugins)
|
||||
|
||||
**ai-plugin.json:**
|
||||
- MCP server tools import
|
||||
- Response semantics (data_path, properties)
|
||||
- Static adaptive card templates
|
||||
- Function definitions (auto-generated)
|
||||
|
||||
**mcp.json:**
|
||||
- MCP server URL
|
||||
- Server metadata endpoint
|
||||
- Authentication reference
|
||||
|
||||
**.env.local:**
|
||||
- OAuth client credentials
|
||||
- API keys and secrets
|
||||
- Environment-specific config
|
||||
- **CRITICAL**: Add to .gitignore
|
||||
|
||||
## Response Semantics Best Practices
|
||||
|
||||
### Data Path Configuration
|
||||
Use JSONPath to extract relevant data:
|
||||
```json
|
||||
{
|
||||
"data_path": "$.items[*]",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.description",
|
||||
"url": "$.html_url"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Template Selection
|
||||
For dynamic templates:
|
||||
```json
|
||||
{
|
||||
"data_path": "$",
|
||||
"template_selector": "$.templateType",
|
||||
"properties": {
|
||||
"title": "$.title",
|
||||
"url": "$.url"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Static Templates
|
||||
Define in ai-plugin.json for consistent formatting:
|
||||
- Use when all responses follow same structure
|
||||
- Better performance than dynamic templates
|
||||
- Easier to maintain and version control
|
||||
|
||||
## Adaptive Card Guidelines
|
||||
|
||||
### Design Principles
|
||||
- **Single-column layout**: Stack elements vertically
|
||||
- **Flexible widths**: Use "stretch" or "auto", not fixed pixels
|
||||
- **Responsive design**: Test in Chat, Teams, Outlook
|
||||
- **Minimal complexity**: Keep cards simple and scannable
|
||||
|
||||
### Template Language Patterns
|
||||
**Conditionals:**
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${if(status == 'active', '✅ Active', '❌ Inactive')}"
|
||||
}
|
||||
```
|
||||
|
||||
**Data Binding:**
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${title}",
|
||||
"weight": "bolder"
|
||||
}
|
||||
```
|
||||
|
||||
**Number Formatting:**
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Score: ${formatNumber(score, 0)}"
|
||||
}
|
||||
```
|
||||
|
||||
**Conditional Rendering:**
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$when": "${count(items) > 0}",
|
||||
"items": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### Card Elements Usage
|
||||
- **TextBlock**: Titles, descriptions, metadata
|
||||
- **FactSet**: Key-value pairs (status, dates, IDs)
|
||||
- **Image**: Icons, thumbnails (use size: "small")
|
||||
- **Container**: Grouping related content
|
||||
- **ActionSet**: Buttons for follow-up actions
|
||||
|
||||
## Testing and Deployment
|
||||
|
||||
### Local Testing Workflow
|
||||
1. **Provision**: Teams Toolkit → Provision
|
||||
2. **Deploy**: Teams Toolkit → Deploy
|
||||
3. **Sideload**: App uploaded to Teams
|
||||
4. **Test**: Visit [m365.cloud.microsoft/chat](https://m365.cloud.microsoft/chat)
|
||||
5. **Iterate**: Fix issues and re-deploy
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
- [ ] All MCP server tools tested individually
|
||||
- [ ] Authentication flow works end-to-end
|
||||
- [ ] Adaptive cards render correctly across hubs
|
||||
- [ ] Response semantics extract expected data
|
||||
- [ ] Error handling provides clear messages
|
||||
- [ ] Conversation starters are relevant and clear
|
||||
- [ ] Agent instructions guide proper behavior
|
||||
- [ ] Compliance and security reviewed
|
||||
|
||||
### Deployment Options
|
||||
**Organization Deployment:**
|
||||
- IT admin deploys to all or selected users
|
||||
- Requires approval in Microsoft 365 admin center
|
||||
- Best for internal business agents
|
||||
|
||||
**Agent Store:**
|
||||
- Submit to Partner Center for validation
|
||||
- Public availability to all Copilot users
|
||||
- Requires rigorous security review
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Multi-Tool Agent
|
||||
Import tools from multiple MCP servers:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"url": "https://github-mcp.example.com"
|
||||
},
|
||||
"jira": {
|
||||
"url": "https://jira-mcp.example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Search and Display
|
||||
1. Tool retrieves data from MCP server
|
||||
2. Response semantics extract relevant fields
|
||||
3. Adaptive card displays formatted results
|
||||
4. User can take action from card buttons
|
||||
|
||||
### Authenticated Actions
|
||||
1. User triggers tool requiring auth
|
||||
2. OAuth flow redirects for consent
|
||||
3. Access token stored in plugin vault
|
||||
4. Subsequent requests use stored token
|
||||
|
||||
## Error Handling
|
||||
|
||||
### MCP Server Errors
|
||||
- Provide clear error messages in agent responses
|
||||
- Fall back to alternative tools if available
|
||||
- Log errors for debugging
|
||||
- Guide user to retry or alternative approach
|
||||
|
||||
### Authentication Failures
|
||||
- Check OAuth credentials in .env.local
|
||||
- Verify scopes match required permissions
|
||||
- Test auth flow outside Copilot first
|
||||
- Ensure token refresh logic works
|
||||
|
||||
### Response Parsing Failures
|
||||
- Validate JSONPath expressions in response semantics
|
||||
- Handle missing or null data gracefully
|
||||
- Provide default values where appropriate
|
||||
- Test with varied API responses
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Tool Selection
|
||||
- Import only necessary tools (reduces token usage)
|
||||
- Avoid redundant tools from multiple servers
|
||||
- Test impact of each tool on response time
|
||||
|
||||
### Response Size
|
||||
- Use data_path to filter unnecessary data
|
||||
- Limit result sets where possible
|
||||
- Consider pagination for large datasets
|
||||
- Keep adaptive cards lightweight
|
||||
|
||||
### Caching Strategy
|
||||
- MCP servers should cache where appropriate
|
||||
- Agent responses may be cached by M365
|
||||
- Consider cache invalidation for time-sensitive data
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Credential Management
|
||||
- **NEVER** commit .env.local to source control
|
||||
- Use environment variables for all secrets
|
||||
- Rotate OAuth credentials regularly
|
||||
- Use separate credentials for dev/prod
|
||||
|
||||
### Data Privacy
|
||||
- Only request minimum necessary scopes
|
||||
- Avoid logging sensitive user data
|
||||
- Review data residency requirements
|
||||
- Follow compliance policies (GDPR, etc.)
|
||||
|
||||
### Server Validation
|
||||
- Verify MCP server is trusted and secure
|
||||
- Check HTTPS endpoints only
|
||||
- Review server's privacy policy
|
||||
- Test for injection vulnerabilities
|
||||
|
||||
## Governance and Compliance
|
||||
|
||||
### Admin Controls
|
||||
Agents can be:
|
||||
- **Blocked**: Prevented from use
|
||||
- **Deployed**: Assigned to specific users/groups
|
||||
- **Published**: Made available organization-wide
|
||||
|
||||
### Monitoring
|
||||
Track:
|
||||
- Agent usage and adoption
|
||||
- Error rates and performance
|
||||
- User feedback and satisfaction
|
||||
- Security incidents
|
||||
|
||||
### Audit Requirements
|
||||
Maintain:
|
||||
- Change history for agent configurations
|
||||
- Access logs for sensitive operations
|
||||
- Approval records for deployments
|
||||
- Compliance attestations
|
||||
|
||||
## Resources and References
|
||||
|
||||
### Official Documentation
|
||||
- [Build Declarative Agents with MCP (DevBlogs)](https://devblogs.microsoft.com/microsoft365dev/build-declarative-agents-for-microsoft-365-copilot-with-mcp/)
|
||||
- [Build MCP Plugins (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-mcp-plugins)
|
||||
- [API Plugin Adaptive Cards (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-adaptive-cards)
|
||||
- [Manage Copilot Agents (Learn)](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps)
|
||||
|
||||
### Tools and SDKs
|
||||
- Microsoft 365 Agents Toolkit (VS Code extension v6.3.x+)
|
||||
- Teams Toolkit for agent packaging
|
||||
- Adaptive Cards Designer
|
||||
- MCP specification documentation
|
||||
|
||||
### Partner Examples
|
||||
- monday.com: Task management integration
|
||||
- Canva: Design automation
|
||||
- Sitecore: Content management
|
||||
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