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 · 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_id is 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_id for 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:

  1. zipAppPackage resolves spec paths relative to the plugin file location
  2. 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.yaml in 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/register lifecycle step in m365agents.yml
  • Using OAuthPluginVault in 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.


Related Documentation