references/api-plugins.md
API Plugin Architecture for M365 JSON Agents
Note: This guide is for JSON-based agents. API plugins are defined using JSON manifest files that reference OpenAPI specifications.
Overview
API plugins (also called "actions") allow your M365 Copilot agent to interact with external REST APIs. They consist of:
- OpenAPI Specification - Describes the REST API endpoints, parameters, and responses
- API Plugin Manifest (JSON) - Configures how M365 Copilot interacts with the API
- Declarative Agent Reference - Links the plugin to your agent via the
actionsarray
⛔ Post-npx -y --package @microsoft/m365agentstoolkit-cli atk add action Checklist — MANDATORY
After running npx -y --package @microsoft/m365agentstoolkit-cli atk add action, you MUST complete ALL of these before validating and deploying:
- Update
name_for_humanin ai-plugin.json — descriptive, user-facing name (max 20 chars) - Update
description_for_modelin ai-plugin.json — detailed guidance for the AI on when and how to use each function - Customize adaptive cards in
appPackage/adaptiveCards/for each operation — different layouts per HTTP verb (list view for GET collections, detail view for GET by ID, confirmation for DELETE, etc.) - Add
confirmationdialogs for all destructive operations (POST, PUT, PATCH, DELETE) - Deploy with
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false
Skipping ANY of these steps = incomplete work. The npx -y --package @microsoft/m365agentstoolkit-cli atk add action command generates scaffolding — you must finish the job by customizing every generated file.
Adding API Plugins with ATK CLI
⚠️ IMPORTANT: When adding an API, OpenAPI spec, or REST API to your agent, you MUST use the
npx -y --package @microsoft/m365agentstoolkit-cli atk add actioncommand. This is the required method for adding API plugins to M365 Copilot agents. Do NOT manually create plugin files - the path resolution between local packaging and M365 service validation is complex and error-prone.
⛔ ONE PLUGIN PER API — HARD RULE: Always add ALL operations from the same OpenAPI spec in a single
npx -y --package @microsoft/m365agentstoolkit-cli atk add actioncall. List every operation in the--api-operationparameter as a comma-separated list. NEVER run separatenpx -y --package @microsoft/m365agentstoolkit-cli atk add actioncalls for different operations from the same spec — this creates multiple plugins instead of one unified plugin. One OpenAPI spec = onenpx -y --package @microsoft/m365agentstoolkit-cli atk add actioncall = one plugin.
The npx -y --package @microsoft/m365agentstoolkit-cli atk add action Command
ALWAYS use this command when asked to add an API, OpenAPI specification, or REST API to an M365 Copilot agent:
npx -y --package @microsoft/m365agentstoolkit-cli atk add action \
--api-plugin-type api-spec \
--openapi-spec-type enter-url-or-open-local-file \
--openapi-spec-location URL_OR_FILE_PATH \
--api-operation "OPERATIONS_TO_MAP" \
-i false
Command Parameters
| Parameter | Description |
|-----------|-------------|
| --api-plugin-type | Type of plugin. Use api-spec for OpenAPI-based plugins. |
| --openapi-spec-type | How to provide the spec. Use enter-url-or-open-local-file. |
| --openapi-spec-location | URL or local file path to the OpenAPI specification. |
| --api-operation | Comma-separated list of operations to include (format: METHOD /path). |
| -i false | Non-interactive mode. |
⚠️ CRITICAL: Use Absolute Paths for Local Files
When using a local OpenAPI specification file, you MUST use an absolute path:
# ✅ CORRECT - Absolute path
--openapi-spec-location /home/user/project/openapi.json
# ❌ WRONG - Relative path (will fail!)
--openapi-spec-location ./openapi.json
--openapi-spec-location openapi.json
Why? The ATK CLI executes from a temporary directory, so relative paths cannot be resolved. Always use the full absolute path to your OpenAPI specification file.
Operation Format
The --api-operation parameter uses the format: METHOD /path,METHOD /path,...
Example with Repairs API (URL):
npx -y --package @microsoft/m365agentstoolkit-cli atk add action \
--api-plugin-type api-spec \
--openapi-spec-type enter-url-or-open-local-file \
--openapi-spec-location "https://repairshub.azurewebsites.net/openapi.json" \
--api-operation "GET /repairs,GET /repairs/{id},POST /repairs,PATCH /repairs/{id},DELETE /repairs/{id}" \
-i false
Example with local file (absolute path):
npx -y --package @microsoft/m365agentstoolkit-cli atk add action \
--api-plugin-type api-spec \
--openapi-spec-type enter-url-or-open-local-file \
--openapi-spec-location /home/user/myproject/nhl-openapi.json \
--api-operation "GET /v1/standings/now,GET /v1/score/now,GET /v1/schedule/now" \
-i false
What the Command Creates
After running npx -y --package @microsoft/m365agentstoolkit-cli atk add action, the following files are created/updated:
appPackage/
├── declarativeAgent.json # Updated with action reference
├── ai-plugin.json # API plugin manifest (generated)
├── adaptiveCards/ # Response templates (auto-generated)
│ ├── getRepairs.json
│ ├── getRepairById.json
│ └── ...
└── apiSpecificationFile/
├── openapi.yaml # OpenAPI spec (converted to 3.0 if needed)
└── openapi.yaml.original # Original spec (if converted)
Note: OpenAPI 3.1 specifications are automatically converted to OpenAPI 3.0 format for compatibility.
Post-Generation: Enhance the Plugin
After running npx -y --package @microsoft/m365agentstoolkit-cli atk add action, you MUST enhance the generated files:
- Update
name_for_human- Make it descriptive and user-friendly - Update
description_for_model- Add detailed guidance on when and how to use each function - 🎨 Update adaptive cards for each action - Customize the auto-generated cards in
appPackage/adaptiveCards/to present meaningful, well-structured data for each operation
Example plugin enhancement:
{
"name_for_human": "NHL Data API",
"description_for_human": "Access real-time NHL standings, scores, and player statistics",
"description_for_model": "Use this plugin to access real-time NHL data. Call getCurrentStandings for league standings. Call getTodaysScores for today's game scores or getScoresByDate for historical scores (YYYY-MM-DD format). Call getCurrentTeamStats or getCurrentRoster with a 3-letter team code (TOR, BOS, NYR, MTL, EDM, VGK, etc.). Always provide context about the data format and available parameters."
}
The description_for_model is critical - it tells the AI when to use each function and what parameters to provide.
🎨 Post-Generation: Enhance Adaptive Cards for Each Action
The npx -y --package @microsoft/m365agentstoolkit-cli atk add action command auto-generates basic adaptive cards in appPackage/adaptiveCards/ — one per operation. These default cards are generic and only display raw data. You MUST customize each card to provide a valuable UX tailored to the data each action returns.
⚠️ CRITICAL: Check ALL Operations Have Adaptive Cards
After running npx -y --package @microsoft/m365agentstoolkit-cli atk add action, verify that an adaptive card exists for EVERY operation. The command may not generate cards for POST, PATCH, or DELETE operations. If any operation is missing an adaptive card, CREATE one manually in appPackage/adaptiveCards/.
- GET operations → List or detail layout showing returned data
- POST operations → Confirmation/summary layout showing what was created
- PATCH operations → Summary layout showing what was updated
- DELETE operations → Confirmation layout confirming what was deleted
Why Customize Adaptive Cards?
- Default cards are generic — they list all response fields as plain text with no hierarchy or formatting
- Users expect rich, scannable output — titles, subtitles, key metrics, and visual hierarchy help users quickly understand results
- Different actions need different layouts — a list of items needs a different card than a single detail view or a confirmation response
How to Enhance Each Card
For each adaptive card file generated in appPackage/adaptiveCards/:
- Examine the API response schema — understand what fields each operation returns
- Identify the most important fields — determine what users care about most (title, status, date, assignee, etc.)
- Design a clear visual hierarchy — use
weight: "Bolder",size: "Medium"/"Large",spacing, andseparatorto create structure - Use appropriate layouts —
ColumnSetfor side-by-side data,FactSetfor key-value pairs,Containerfor grouping - Add conditional styling — use
"color"properties and"style"to highlight important states (e.g., urgent, overdue) - Include action buttons — add
Action.OpenUrlfor links to external resources when the data includes URLs - Handle arrays with
$foreach— use${$root}for the items array and${$data}for individual items within the template
Example: Before vs After Enhancement
❌ Auto-generated card (generic — poor UX):
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"text": "id: ${if(id, id, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "title: ${if(title, title, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "description: ${if(description, description, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "assignedTo: ${if(assignedTo, assignedTo, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "date: ${if(date, date, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "image: ${if(image, image, 'N/A')}",
"wrap": true
}
]
}
✅ Enhanced card (rich UX — tailored to data):
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "${image}",
"size": "Medium",
"altText": "${title}"
}
]
},
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "${title}",
"weight": "Bolder",
"size": "Medium",
"wrap": true
},
{
"type": "TextBlock",
"text": "Assigned to: ${assignedTo}",
"spacing": "None",
"isSubtle": true,
"wrap": true
}
]
}
]
},
{
"type": "TextBlock",
"text": "${description}",
"wrap": true,
"spacing": "Medium"
},
{
"type": "FactSet",
"separator": true,
"facts": [
{
"title": "Repair ID",
"value": "#${id}"
},
{
"title": "Date",
"value": "${date}"
}
]
}
]
}
Example: List Action Card (Array Response with $foreach)
When an action returns an array of items, use the $foreach data binding pattern to render each item:
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "Container",
"$data": "${$root}",
"separator": true,
"items": [
{
"type": "TextBlock",
"text": "${title}",
"weight": "Bolder",
"wrap": true
},
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Assigned to: ${assignedTo}",
"isSubtle": true,
"spacing": "None",
"wrap": true
}
]
},
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "TextBlock",
"text": "${date}",
"isSubtle": true,
"spacing": "None",
"horizontalAlignment": "Right"
}
]
}
]
}
]
}
]
}
Card Design Guidelines Per Action Type
| Action Type | Recommended Layout | Key Elements |
|-------------|-------------------|--------------|
| List / Search (GET returning array) | Repeating Container with $data: "${$root}" | Title, subtitle, key status field per item, separator between items |
| Get by ID (GET returning single object) | ColumnSet + FactSet | Image/icon, title, description, key-value pairs for metadata |
| Create (POST) | Confirmation summary | Show created item's key fields, success indicator |
| Update (PATCH/PUT) | Before/after or summary | Show updated fields, confirmation status |
| Delete (DELETE) | Simple confirmation | Item identifier, success message |
When to Use API Plugins
Use API plugins (actions) when the agent needs to:
- Call external APIs not available through M365 capabilities
- Perform CRUD operations (Create, Read, Update, Delete)
- Access real-time transactional data from external systems
- Modify state in external systems (create tickets, update records)
- Integrate with line-of-business systems (CRM, ticketing, databases)
Don't use API plugins when:
- M365 capabilities already provide the data (use capabilities like
OneDriveAndSharePoint,Email, etc.) - Read-only access to documents is sufficient
- No external API interaction needed
API Plugin vs Capabilities Decision Tree
Need external API?
Yes → Create API Plugin Action
No → Use built-in Capability
↓
Need real-time transactional data?
Yes → API Plugin
No → Capability (SharePoint, Connectors)
↓
Need CRUD operations?
Yes → API Plugin
No → Capability
↓
Need to modify state?
Yes → API Plugin
No → Capability
API Plugin Manifest Structure (v2.4)
The API plugin manifest is a JSON file that configures how M365 Copilot interacts with your API.
Basic Structure
{
"schema_version": "v2.4",
"name_for_human": "Plugin Name",
"namespace": "pluginNamespace",
"description_for_human": "What this plugin does for users",
"description_for_model": "Detailed instructions for the AI model on when and how to use this plugin",
"functions": [],
"runtimes": []
}
Complete Example: Repairs API Plugin
{
"schema_version": "v2.4",
"name_for_human": "Repairs API",
"namespace": "repairs",
"description_for_human": "Manage repair tickets and track issues",
"description_for_model": "Use this plugin to search, create, update, and delete repair tickets. Call getRepairs to list all repairs or filter by assignee. Call getRepairById to get details about a specific repair. Call createRepair to create new tickets. Call updateRepair to modify existing repairs. Call deleteRepair to remove completed repairs.",
"logo_url": "https://repairshub.azurewebsites.net/logo.png",
"contact_email": "[email protected]",
"legal_info_url": "https://contoso.com/terms",
"privacy_policy_url": "https://contoso.com/privacy",
"functions": [
{
"name": "getRepairs",
"description": "Get all repairs, optionally filtered by assignee",
"capabilities": {
"response_semantics": {
"data_path": "$",
"properties": {
"title": "$.title",
"subtitle": "$.assignedTo"
}
}
}
},
{
"name": "getRepairById",
"description": "Get a specific repair by its ID"
},
{
"name": "createRepair",
"description": "Create a new repair ticket",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Create Repair?",
"body": "Are you sure you want to create this repair ticket?"
}
}
},
{
"name": "updateRepair",
"description": "Update an existing repair ticket",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Update Repair?",
"body": "Are you sure you want to update this repair?"
}
}
},
{
"name": "deleteRepair",
"description": "Delete a repair ticket",
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Delete Repair?",
"body": "Are you sure you want to permanently delete this repair?"
}
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "apiSpecificationFile/openapi.json"
},
"run_for_functions": ["getRepairs", "getRepairById", "createRepair", "updateRepair", "deleteRepair"]
}
]
}
OpenAPI Specification
The OpenAPI specification describes your REST API endpoints. Here's an example based on the Repairs API:
Example: Repairs API OpenAPI Spec
{
"openapi": "3.1.0",
"info": {
"title": "Repairs API",
"description": "A simple service to manage repairs for various items",
"version": "1.0.0"
},
"servers": [
{
"url": "https://repairshub.azurewebsites.net/"
}
],
"paths": {
"/repairs": {
"get": {
"operationId": "getRepairs",
"summary": "Get all repairs",
"parameters": [
{
"name": "assignedTo",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter repairs by assignee name"
}
],
"responses": {
"200": {
"description": "List of repairs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Repair"
}
}
}
}
}
}
},
"post": {
"operationId": "createRepair",
"summary": "Create a new repair",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateRepairRequest"
}
}
}
},
"responses": {
"201": {
"description": "Repair created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Repair"
}
}
}
}
}
}
},
"/repairs/{id}": {
"get": {
"operationId": "getRepairById",
"summary": "Get a repair by ID",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Repair found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Repair"
}
}
}
},
"404": {
"description": "Repair not found"
}
}
},
"patch": {
"operationId": "updateRepair",
"summary": "Update a repair by ID",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateRepairRequest"
}
}
}
},
"responses": {
"200": {
"description": "Repair updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Repair"
}
}
}
}
}
},
"delete": {
"operationId": "deleteRepair",
"summary": "Delete a repair by ID",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Repair deleted"
}
}
}
}
},
"components": {
"schemas": {
"Repair": {
"type": "object",
"properties": {
"id": { "type": "number" },
"title": { "type": "string" },
"description": { "type": "string" },
"assignedTo": { "type": "string" },
"date": { "type": "string" },
"image": { "type": "string" }
},
"required": ["id", "title", "description", "assignedTo", "date", "image"]
},
"CreateRepairRequest": {
"type": "object",
"properties": {
"title": { "type": "string" },
"description": { "type": "string" },
"assignedTo": { "type": "string" },
"date": { "type": "string" },
"image": { "type": "string" }
},
"required": ["title", "description", "assignedTo", "date", "image"]
},
"UpdateRepairRequest": {
"type": "object",
"properties": {
"title": { "type": "string" },
"description": { "type": "string" },
"assignedTo": { "type": "string" },
"date": { "type": "string" },
"image": { "type": "string" }
}
}
}
}
}
Linking API Plugin to Declarative Agent
Reference the API plugin in your declarativeAgent.json:
{
"version": "v1.6",
"name": "Repairs Agent",
"description": "An agent to manage repair tickets",
"instructions": "You help users manage repair tickets. Use the repairs API to search, create, update, and delete repairs.",
"actions": [
{
"id": "repairsPlugin",
"file": "plugins/repairs-plugin.json"
}
],
"conversation_starters": [
{
"title": "My Repairs",
"text": "What repairs are assigned to me?"
},
{
"title": "Create Repair",
"text": "I need to create a new repair ticket"
}
]
}
Authentication for API Plugins
No Authentication
For public APIs or development:
{
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "apiSpecificationFile/openapi.json"
}
}
]
}
OAuth Authentication
For OAuth2-protected APIs:
{
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "OAuthPluginVault",
"referen