references/api-plugins.md · 24000
ce_id": "your-oauth-reference-id" }, "spec": { "url": "apiSpecificationFile/openapi.json" } } ] }
### API Key Authentication
For API key-protected APIs:
```json
{
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "ApiKeyPluginVault",
"reference_id": "your-apikey-reference-id"
},
"spec": {
"url": "apiSpecificationFile/openapi.json"
}
}
]
}
Note: The
reference_idis obtained when configuring authentication in the Microsoft 365 admin center or through the ATK CLI during provisioning.
API Plugin Best Practices
1. Operation Naming in OpenAPI
Use clear operationId values that describe the action:
{
"get": {
"operationId": "searchTickets",
"summary": "Search for tickets by keyword or status"
},
"post": {
"operationId": "createTicket",
"summary": "Create a new ticket"
}
}
✅ Good: searchTickets, createTicket, updateTicketStatus
❌ Bad: tickets, doSomething, api1
2. Descriptive Function Entries
Provide detailed descriptions in the plugin manifest:
{
"functions": [
{
"name": "searchTickets",
"description": "Search for support tickets. Use this when the user asks about finding tickets, checking ticket status, or looking up issues. Supports filtering by status (open, closed, pending) and assignee."
}
]
}
3. Add Confirmations for Destructive Operations
Always add confirmation dialogs for create, update, and delete operations:
{
"functions": [
{
"name": "deleteTicket",
"description": "Permanently delete a ticket",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Delete Ticket?",
"body": "This action cannot be undone. Are you sure you want to delete this ticket?"
}
}
}
]
}
4. Use Response Semantics for Rich Display
Configure how results are displayed to users:
{
"functions": [
{
"name": "getRepairs",
"description": "Get all repairs",
"capabilities": {
"response_semantics": {
"data_path": "$",
"properties": {
"title": "$.title",
"subtitle": "$.assignedTo",
"url": "$.url"
},
"static_template": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"text": "${title}",
"weight": "Bolder",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Assigned to: ${assignedTo}",
"spacing": "None"
},
{
"type": "TextBlock",
"text": "${description}",
"wrap": true
}
]
}
}
}
}
]
}
Common API Plugin Patterns
Pattern: CRM Integration
Plugin Manifest:
{
"schema_version": "v2.4",
"name_for_human": "CRM API",
"namespace": "crm",
"description_for_human": "Manage customer accounts and opportunities",
"description_for_model": "Use this plugin to search for customer accounts, view account details, list opportunities, and update opportunity status in the CRM system.",
"functions": [
{
"name": "searchAccounts",
"description": "Search for customer accounts by name or industry"
},
{
"name": "getAccount",
"description": "Get detailed information about a specific account"
},
{
"name": "listOpportunities",
"description": "List sales opportunities, optionally filtered by account or stage"
},
{
"name": "updateOpportunityStage",
"description": "Update the stage of a sales opportunity",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Update Opportunity?",
"body": "Update the opportunity stage?"
}
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "OAuthPluginVault",
"reference_id": "crm-oauth-ref"
},
"spec": {
"url": "apiSpecificationFile/crm-openapi.json"
}
}
]
}
Pattern: Ticketing System
Plugin Manifest:
{
"schema_version": "v2.4",
"name_for_human": "Ticket System",
"namespace": "tickets",
"description_for_human": "Manage support tickets and track issues",
"description_for_model": "Use this plugin to search support tickets, create new tickets, add comments, and update ticket status. Always confirm with the user before creating or modifying tickets.",
"functions": [
{
"name": "searchTickets",
"description": "Search for tickets by keyword, status, or assignee",
"capabilities": {
"response_semantics": {
"data_path": "$.tickets",
"properties": {
"title": "$.title",
"subtitle": "$.status"
}
}
}
},
{
"name": "getTicket",
"description": "Get detailed information about a specific ticket including comments and history"
},
{
"name": "createTicket",
"description": "Create a new support ticket",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Create Ticket?",
"body": "Create a new support ticket?"
}
}
},
{
"name": "addComment",
"description": "Add a comment to an existing ticket",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Add Comment?",
"body": "Add this comment to the ticket?"
}
}
},
{
"name": "updateTicketStatus",
"description": "Update the status of a ticket (open, in-progress, resolved, closed)",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Update Status?",
"body": "Update the ticket status?"
}
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "ApiKeyPluginVault",
"reference_id": "tickets-apikey-ref"
},
"spec": {
"url": "apiSpecificationFile/tickets-openapi.yaml"
}
}
]
}
Pattern: Analytics/Reporting
Plugin Manifest:
{
"schema_version": "v2.4",
"name_for_human": "Analytics API",
"namespace": "analytics",
"description_for_human": "Query business metrics and generate reports",
"description_for_model": "Use this plugin to retrieve business metrics, run analytics queries, and generate reports. This is a read-only API for data analysis.",
"functions": [
{
"name": "getMetrics",
"description": "Get key business metrics for a specified date range"
},
{
"name": "runQuery",
"description": "Execute a custom analytics query with filters and dimensions"
},
{
"name": "getReport",
"description": "Get a pre-built report by name or ID"
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "OAuthPluginVault",
"reference_id": "analytics-oauth-ref"
},
"spec": {
"url": "apiSpecificationFile/analytics-openapi.json"
}
}
]
}
Testing API Plugins
1. Validate OpenAPI Specification
Before adding to your agent, validate your OpenAPI spec:
# Using online validator
# Visit https://editor.swagger.io and paste your spec
# Or use a local tool
npx @apidevtools/swagger-cli validate openapi.json
2. Test API Endpoints Directly
Use tools like Bruno, Postman, or REST Client extension to test your API:
### Get all repairs
GET https://repairshub.azurewebsites.net/repairs
### Get repair by ID
GET https://repairshub.azurewebsites.net/repairs/1
### Create a new repair
POST https://repairshub.azurewebsites.net/repairs
Content-Type: application/json
{
"title": "Fix broken laptop",
"description": "Screen is cracked",
"assignedTo": "John Doe",
"date": "2026-01-20",
"image": "https://example.com/image.jpg"
}
3. Provision and Test in M365 Copilot
# Provision the agent
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false
# Use the returned test URL to test in M365 Copilot
Test with various prompts:
- "Show me all repairs"
- "Find repairs assigned to John"
- "Create a new repair for a broken laptop"
- "Update repair #1 to assign it to Jane"
Security Considerations
1. Credential Management
- Never hardcode credentials in JSON files
- Use
reference_idfor OAuth and API key authentication - Store secrets in environment variables or secure vaults
- Rotate credentials regularly
2. Input Validation
- Validate all inputs in your API backend
- Prevent injection attacks
- Limit string lengths and ranges
- Use strong typing in OpenAPI schemas
3. Confirmation Dialogs
- Always add confirmations for state-changing operations
- Be clear about what action will be taken
- Allow users to cancel destructive operations
4. Rate Limiting
- Implement rate limiting in your API backend
- Handle 429 (Too Many Requests) responses gracefully
- Consider caching for frequently-accessed data
5. Data Privacy
- Only request necessary data from your API
- Follow data residency requirements
- Log API calls for audit purposes
- Handle PII appropriately
Common Issues and Solutions
| Issue | Cause | Solution |
|-------|-------|----------|
| "Function not found" | operationId in OpenAPI doesn't match name in functions | Ensure function names match OpenAPI operationIds |
| Authentication fails | Invalid or expired reference_id | Re-register authentication in admin center |
| CORS errors | API doesn't allow agent origin | Configure API CORS to allow M365 origins |
| Timeout errors | API response too slow | Optimize API, add caching, increase timeout |
| Schema mismatch | Plugin expects different response format | Update OpenAPI spec to match actual API response |
| "No operations selected" | Empty --api-operation parameter | Specify operations in correct format: METHOD /path |
| "File not found" during npx -y --package @microsoft/m365agentstoolkit-cli atk add action | Relative path used for local OpenAPI spec | Use absolute path: /full/path/to/openapi.json |
| "File not found in zip archive" during provision | Manual plugin creation with incorrect spec path | Use npx -y --package @microsoft/m365agentstoolkit-cli atk add action command - do not manually create plugins |
| OpenAPI spec path resolution fails | Path conflicts between zipAppPackage and M365 service | The ATK CLI handles this correctly - always use npx -y --package @microsoft/m365agentstoolkit-cli atk add action |
Why Manual Plugin Creation Fails
If you try to manually create API plugin files, you'll encounter path resolution conflicts:
- zipAppPackage resolves spec paths relative to the plugin file location
- M365 extendToM365 resolves spec paths relative to the zip archive root
These different resolution strategies make manual path configuration nearly impossible. The npx -y --package @microsoft/m365agentstoolkit-cli atk add action command handles this complexity automatically by:
- Placing the OpenAPI spec in
apiSpecificationFile/ - Using the correct relative path
apiSpecificationFile/openapi.yamlin the plugin - Ensuring the zip archive structure matches the path expectations
Authentication for API Plugins
The examples above use "auth": {"type": "None"} (unauthenticated APIs). If your API requires OAuth authentication, see authentication.md for:
- Discovering OAuth endpoints from well-known metadata
- Obtaining client credentials (via Dynamic Client Registration or manual entry)
- Configuring the
oauth/registerlifecycle step inm365agents.yml - Using
OAuthPluginVaultin the plugin manifest runtime block
The oauth/register step must be added to m365agents.yml before teamsApp/zipAppPackage. The resulting <PREFIX>_MCP_AUTH_ID environment variable is referenced in the plugin's runtime auth block.