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/examples.md

M365 JSON Agent Developer Examples

This document provides workflow examples for common M365 Copilot JSON-based agent development scenarios.

Note: This guide is for JSON-based agents that use .json manifest files directly.


Example 1: Development and Provisioning

Complete workflow for provisioning a JSON-based agent to a development environment:

# Install dependencies (if any)
npm install

# Provision agent to development environment (no compile step needed for JSON agents)
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false

Result: Returns a test URL like https://m365.cloud.microsoft/chat/?titleId=T_abc123xyz to test the agent in Microsoft 365 Copilot.

Use case: Testing agent functionality in a live environment during development.


Example 2: Provision and Share Agent

Workflow for provisioning and sharing an agent with your organization:

# Provision agent to target environment
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env dev --interactive false

# Share agent with tenant users
npx -y --package @microsoft/m365agentstoolkit-cli atk share --scope tenant --env dev

Result: Agent becomes available to all users in the Microsoft 365 tenant.

Use case: Deploying a shared agent for organizational use after testing and validation.


Example 3: Package Agent for Distribution

Workflow for creating an agent package for distribution:

# Package agent for distribution
npx -y --package @microsoft/m365agentstoolkit-cli atk package --env prod

Result: Creates a distributable package file that can be uploaded to the Microsoft 365 admin center or shared externally.

Use case: Creating a final package for production deployment or external distribution.


Example 4: Basic Declarative Agent JSON

A minimal declarative agent manifest file (declarativeAgent.json):

{
  "version": "v1.6",
  "name": "My Support Agent",
  "description": "An agent to help with customer support inquiries",
  "instructions": "You are a helpful customer support agent. Help users find information about their issues and guide them to solutions. Be polite and professional at all times."
}

Example 5: Agent with Capabilities

A declarative agent with SharePoint and Email capabilities:

{
  "version": "v1.6",
  "name": "Knowledge Base Agent",
  "description": "An agent that searches company knowledge bases and emails",
  "instructions": "You help employees find information from our SharePoint knowledge base and relevant emails. Always cite your sources when providing information.",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/KnowledgeBase/Documents"
        }
      ]
    },
    {
      "name": "Email"
    }
  ]
}

Example 6: Agent with Conversation Starters

A declarative agent with helpful conversation starters:

{
  "version": "v1.6",
  "name": "HR Assistant",
  "description": "An agent that helps employees with HR-related questions",
  "instructions": "You are an HR assistant helping employees with common HR questions about policies, benefits, and procedures.",
  "conversation_starters": [
    {
      "title": "Time Off Policy",
      "text": "What is our company's time off policy?"
    },
    {
      "title": "Benefits Overview",
      "text": "Can you explain our health insurance benefits?"
    },
    {
      "title": "Expense Reports",
      "text": "How do I submit an expense report?"
    }
  ]
}

Example 7: Agent with API Plugin Action

A declarative agent connected to an external API:

{
  "version": "v1.6",
  "name": "Repairs Agent",
  "description": "An agent that helps manage repair tickets",
  "instructions": "You help users create, find, and track repair tickets. Use the repairs API to search for existing tickets and create new ones when requested.",
  "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"
    }
  ]
}

Example 8: API Plugin Manifest

A complete API plugin manifest file (plugins/repairs-plugin.json):

{
  "schema_version": "v2.4",
  "name_for_human": "Repairs API",
  "namespace": "repairs",
  "description_for_human": "Search and manage repair tickets",
  "description_for_model": "Use this plugin to search for repair tickets, get details about specific repairs, and create new repair requests.",
  "functions": [
    {
      "name": "searchRepairs",
      "description": "Search for repair tickets by keyword or status"
    },
    {
      "name": "getRepair",
      "description": "Get details about a specific repair ticket",
      "parameters": {
        "type": "object",
        "properties": {
          "repairId": {
            "type": "string",
            "description": "The unique ID of the repair ticket"
          }
        },
        "required": ["repairId"]
      }
    },
    {
      "name": "createRepair",
      "description": "Create a new repair ticket",
      "parameters": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Title of the repair"
          },
          "description": {
            "type": "string",
            "description": "Detailed description of the issue"
          }
        },
        "required": ["title", "description"]
      },
      "capabilities": {
        "confirmation": {
          "type": "AdaptiveCard",
          "title": "Create Repair?",
          "body": "Create a new repair ticket?"
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://api.contoso.com/openapi.yaml"
      }
    }
  ]
}

Example 9: Full Agent with All Features

A complete agent combining all features:

{
  "version": "v1.6",
  "id": "customer-support-agent",
  "name": "Customer Support Agent",
  "description": "A comprehensive support agent for customer inquiries",
  "instructions": "You are a professional customer support agent for Contoso.\n\nResponsibilities:\n1. Search the knowledge base for relevant documentation\n2. Look up repair tickets and their status\n3. Create new repair tickets when requested\n4. Search support emails for context\n\nGuidelines:\n- Always be polite and professional\n- Cite sources when providing information\n- Ask clarifying questions when needed\n- Never share confidential information",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/Support/Documents"
        }
      ]
    },
    {
      "name": "Email",
      "shared_mailbox": "[email protected]"
    },
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://docs.contoso.com"
        }
      ]
    }
  ],
  "actions": [
    {
      "id": "repairsApi",
      "file": "plugins/repairs-plugin.json"
    }
  ],
  "conversation_starters": [
    {
      "title": "Check Repair Status",
      "text": "What is the status of my repairs?"
    },
    {
      "title": "Search Knowledge Base",
      "text": "How do I troubleshoot connection issues?"
    },
    {
      "title": "Create New Ticket",
      "text": "I need to create a new support ticket"
    }
  ],
  "disclaimer": {
    "text": "This agent provides general support assistance. For urgent issues, please contact our support hotline."
  }
}

Example 10: Localized Agent

A declarative agent with tokenized strings for multi-language support.

Tokenized declarativeAgent.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
  "version": "v1.6",
  "name": "[[agent_name]]",
  "description": "[[agent_description]]",
  "instructions": "$[file]('instructions.txt')",
  "conversation_starters": [
    {
      "title": "[[starter_status_title]]",
      "text": "[[starter_status_text]]"
    },
    {
      "title": "[[starter_kb_title]]",
      "text": "[[starter_kb_text]]"
    }
  ],
  "disclaimer": {
    "text": "[[disclaimer_text]]"
  }
}

manifest.json with localizationInfo

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
  "manifestVersion": "devPreview",
  "localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
      {
        "languageTag": "fr",
        "file": "fr.json"
      }
    ]
  },
  "name": {
    "short": "Support Agent",
    "full": "Customer Support Agent"
  },
  "description": {
    "short": "Get help with support issues",
    "full": "An agent that helps resolve customer support issues using internal knowledge bases."
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}

Default language file (en.json)

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json",
  "name.short": "Support Agent",
  "name.full": "Customer Support Agent",
  "description.short": "Get help with support issues",
  "description.full": "An agent that helps resolve customer support issues using internal knowledge bases.",
  "localizationKeys": {
    "agent_name": "Customer Support Agent",
    "agent_description": "An agent that helps resolve customer support issues using internal knowledge bases.",
    "starter_status_title": "Check ticket status",
    "starter_status_text": "What is the status of my open tickets?",
    "starter_kb_title": "Search knowledge base",
    "starter_kb_text": "How do I reset my password?",
    "disclaimer_text": "This agent provides general support guidance. For urgent issues, contact the helpdesk."
  }
}

French language file (fr.json)

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json",
  "name.short": "Agent de support",
  "name.full": "Agent de support client",
  "description.short": "Obtenez de l'aide pour vos problèmes",
  "description.full": "Un agent qui aide à résoudre les problèmes de support client à l'aide des bases de connaissances internes.",
  "localizationKeys": {
    "agent_name": "Agent de support client",
    "agent_description": "Un agent qui aide à résoudre les problèmes de support client à l'aide des bases de connaissances internes.",
    "starter_status_title": "Vérifier le statut du ticket",
    "starter_status_text": "Quel est le statut de mes tickets ouverts ?",
    "starter_kb_title": "Rechercher la base de connaissances",
    "starter_kb_text": "Comment réinitialiser mon mot de passe ?",
    "disclaimer_text": "Cet agent fournit des conseils de support généraux. Pour les problèmes urgents, contactez le service d'assistance."
  }
}

Reference: localization.md for the full localization workflow