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