AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

declarative-agent-developer

Create, build, deploy, and localize declarative agents for M365 Copilot and Teams. USE THIS SKILL for ANY task involving a declarative agent — including localization, scaffolding, editing manifests, adding capabilities, and deploying. Localization requires tokenized manifests and language files that only this skill knows how to produce. Triggers: "create agent", "create a declarative agent", "new declarative agent", "scaffold an agent", "new agent project", "add a capability", "add a plugin", "configure my agent", "deploy my agent", "fix my agent manifest", "edit my agent", "localize my agent", "add localization", "translate my agent", "multi-language agent", "add an API plugin", "add an MCP plugin", "add OAuth to my plugin", "review instructions", "improve instructions", "fix my instructions"

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read microsoft--declarative-agent-developer at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 14

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:

  1. OpenAPI Specification - Describes the REST API endpoints, parameters, and responses
  2. API Plugin Manifest (JSON) - Configures how M365 Copilot interacts with the API
  3. Declarative Agent Reference - Links the plugin to your agent via the actions array

⛔ 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:

  1. Update name_for_human in ai-plugin.json — descriptive, user-facing name (max 20 chars)
  2. Update description_for_model in ai-plugin.json — detailed guidance for the AI on when and how to use each function
  3. 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.)
  4. Add confirmation dialogs for all destructive operations (POST, PUT, PATCH, DELETE)
  5. 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 action command. 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 action call. List every operation in the --api-operation parameter as a comma-separated list. NEVER run separate npx -y --package @microsoft/m365agentstoolkit-cli atk add action calls for different operations from the same spec — this creates multiple plugins instead of one unified plugin. One OpenAPI spec = one npx -y --package @microsoft/m365agentstoolkit-cli atk add action call = 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:

  1. Update name_for_human - Make it descriptive and user-friendly
  2. Update description_for_model - Add detailed guidance on when and how to use each function
  3. 🎨 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/:

  1. Examine the API response schema — understand what fields each operation returns
  2. Identify the most important fields — determine what users care about most (title, status, date, assignee, etc.)
  3. Design a clear visual hierarchy — use weight: "Bolder", size: "Medium"/"Large", spacing, and separator to create structure
  4. Use appropriate layouts — ColumnSet for side-by-side data, FactSet for key-value pairs, Container for grouping
  5. Add conditional styling — use "color" properties and "style" to highlight important states (e.g., urgent, overdue)
  6. Include action buttons — add Action.OpenUrl for links to external resources when the data includes URLs
  7. 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