mcp-create-declarative-agent

---
mode: 'agent'
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
description: 'Créer un agent déclaratif pour Microsoft 365 Copilot en intégrant un serveur MCP avec authentification, sélection d'outils et configuration'
model: 'gpt-4.1'
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
---

# Créer un Agent Déclaratif basé sur MCP pour Microsoft 365 Copilot

Créer un agent déclaratif complet pour Microsoft 365 Copilot qui s'intègre avec un serveur Model Context Protocol (MCP) pour accéder à des systèmes et données externes.

## Requirements

Générer la structure de projet suivante à l'aide de Microsoft 365 Agents Toolkit :

### Configuration du Projet
1. **Générer l'agent déclaratif** via Agents Toolkit
2. **Ajouter une action MCP** pointant vers le serveur MCP
3. **Sélectionner les outils** à importer depuis le serveur MCP
4. **Configurer l'authentification** (OAuth 2.0 ou SSO)
5. **Examiner les fichiers générés** (manifest.json, ai-plugin.json, declarativeAgent.json)

### Fichiers Clés Générés

**appPackage/manifest.json** - Manifeste d'application Teams avec référence plugin :
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
  "manifestVersion": "devPreview",
  "version": "1.0.0",
  "id": "...",
  "developer": {
    "name": "...",
    "websiteUrl": "...",
    "privacyUrl": "...",
    "termsOfUseUrl": "..."
  },
  "name": {
    "short": "Agent Name",
    "full": "Full Agent Name"
  },
  "description": {
    "short": "Short description",
    "full": "Full description"
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}
```

**appPackage/declarativeAgent.json** - Définition de l'agent :
```json
{
  "$schema": "https://aka.ms/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Agent Name",
  "description": "Agent description",
  "instructions": "You are an assistant that helps with [specific domain]. Use the available tools to [capabilities].",
  "capabilities": [
    {
      "name": "WebSearch",
      "websites": [
        {
          "url": "https://learn.microsoft.com"
        }
      ]
    },
    {
      "name": "MCP",
      "file": "ai-plugin.json"
    }
  ]
}
```

**appPackage/ai-plugin.json** - Manifeste du plugin MCP :
```json
{
  "schema_version": "v2.1",
  "name_for_human": "Service Name",
  "description_for_human": "Description for users",
  "description_for_model": "Description for AI model",
  "contact_email": "support@company.com",
  "namespace": "serviceName",
  "capabilities": {
    "conversation_starters": [
      {
        "text": "Example query 1"
      }
    ]
  },
  "functions": [
    {
      "name": "functionName",
      "description": "Function description",
      "capabilities": {
        "response_semantics": {
          "data_path": "$",
          "properties": {
            "title": "$.title",
            "subtitle": "$.description"
          }
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "MCP",
      "spec": {
        "url": "https://api.service.com/mcp/"
      },
      "run_for_functions": ["functionName"],
      "auth": {
        "type": "OAuthPluginVault",
        "reference_id": "${{OAUTH_REFERENCE_ID}}"
      }
    }
  ]
}
```

**/.vscode/mcp.json** - Configuration du serveur MCP :
```json
{
  "serverUrl": "https://api.service.com/mcp/",
  "pluginFilePath": "appPackage/ai-plugin.json"
}
```

## Intégration du Serveur MCP

### Points de Terminaison MCP Supportés
Le serveur MCP doit fournir :
- Endpoint de **métadonnées du serveur**
- Endpoint **listage des outils** (expose les fonctions disponibles)
- Endpoint **exécution des outils** (gère les appels de fonction)

### Sélection des Outils
Lors de l'importation depuis MCP :
1. Récupérer les outils disponibles depuis le serveur
2. Sélectionner les outils spécifiques à inclure (pour la sécurité/simplicité)
3. Les définitions d'outils sont auto-générées dans ai-plugin.json

### Types d'Authentification

**OAuth 2.0 (Enregistrement Statique)**
```json
"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "${{OAUTH_REFERENCE_ID}}",
  "authorization_url": "https://auth.service.com/authorize",
  "client_id": "${{CLIENT_ID}}",
  "client_secret": "${{CLIENT_SECRET}}",
  "scope": "read write"
}
```

**Single Sign-On (SSO)**
```json
"auth": {
  "type": "SSO"
}
```

## Sémantique des Réponses

### Définir le Mappage des Données
Utiliser `response_semantics` pour extraire les champs pertinents des réponses API :

```json
"capabilities": {
  "response_semantics": {
    "data_path": "$.results",
    "properties": {
      "title": "$.name",
      "subtitle": "$.description",
      "url": "$.link"
    }
  }
}
```

### Ajouter des Cartes Adaptatives (Optionnel)
Consulter le prompt `mcp-create-adaptive-cards` pour ajouter des modèles de cartes visuelles.

## Configuration de l'Environnement

Créer `.env.local` ou `.env.dev` pour les identifiants :

```env
OAUTH_REFERENCE_ID=your-oauth-reference-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
```

## Tests & Déploiement

### Tests Locaux
1. **Provisionner** l'agent dans Agents Toolkit
2. **Démarrer le débogage** pour chargement dans Teams
3. Tester dans Microsoft 365 Copilot à https://m365.cloud.microsoft/chat
4. S'authentifier lorsque demandé
5. Interroger l'agent en langage naturel

### Validation
- Vérifier les importations d'outils dans ai-plugin.json
- Vérifier la configuration d'authentification
- Tester chaque fonction exposée
- Valider le mappage des données de réponse

## Bonnes Pratiques

### Conception des Outils
- **Fonctions ciblées** : Chaque outil doit faire une chose bien
- **Descriptions claires** : Aider le modèle à comprendre quand utiliser chaque outil
- **Portée minimale** : Importer uniquement les outils dont l'agent a besoin
- **Noms descriptifs** : Utiliser des noms de fonction orientés action

### Sécurité
- **Utiliser OAuth 2.0** pour les scénarios de production
- **Stocker les secrets** dans des variables d'environnement
- **Valider les entrées** côté serveur MCP
- **Limiter les portées** aux permissions minimales requises
- **Utiliser des IDs de référence** pour l'enregistrement OAuth

### Instructions
- **Être spécifique** sur l'objectif et les capacités de l'agent
- **Définir le comportement** pour les scénarios de succès et d'erreur
- **Référencer les outils** explicitement dans les instructions le cas échéant
- **Fixer les attentes** des utilisateurs sur ce que l'agent peut/ne peut pas faire

### Performance
- **Mettre en cache les réponses** le cas échéant sur le serveur MCP
- **Regrouper les opérations** lorsque possible
- **Définir des délais d'expiration** pour les opérations longues
- **Paginer les résultats** pour les grands ensembles de données

## Exemples Courants de Serveurs MCP

### Serveur MCP GitHub
```
URL: https://api.githubcopilot.com/mcp/
Tools: search_repositories, search_users, get_repository
Auth: OAuth 2.0
```

### Serveur MCP Jira
```
URL: https://your-domain.atlassian.net/mcp/
Tools: search_issues, create_issue, update_issue
Auth: OAuth 2.0
```

### Service Personnalisé
```
URL: https://api.your-service.com/mcp/
Tools: Outils personnalisés exposés par votre service
Auth: OAuth 2.0 ou SSO
```

## Flux de Travail

Demander à l'utilisateur :
1. Quel serveur MCP intégrez-vous (URL) ?
2. Quels outils doivent être exposés à Copilot ?
3. Quelle méthode d'authentification le serveur supporte-t-il ?
4. Quel doit être l'objectif principal de l'agent ?
5. Avez-vous besoin de sémantique de réponse ou de Cartes Adaptatives ?

Ensuite générer :
- Structure complète d'appPackage/ (manifest.json, declarativeAgent.json, ai-plugin.json)
- Configuration mcp.json
- Modèle .env.local
- Instructions de provisionnement et de test

## Dépannage

### Le Serveur MCP ne Répond pas
- Vérifier que l'URL du serveur est correcte
- Vérifier la connectivité réseau
- Valider que le serveur MCP implémente les endpoints requis

### L'Authentification Échoue
- Vérifier que les identifiants OAuth sont corrects
- Vérifier que l'ID de référence correspond à l'enregistrement
- Confirmer que les scopes sont demandés correctement
- Tester le flux OAuth indépendamment

### Les Outils n'Apparaissent pas
- S'assurer que mcp.json pointe vers le bon serveur
- Vérifier que les outils ont été sélectionnés lors de l'importation
- Vérifier que ai-plugin.json a les bonnes définitions de fonction
- Re-récupérer les actions depuis MCP si le serveur a changé

### L'Agent ne Comprend pas les Requêtes
- Examiner les instructions dans declarativeAgent.json
- Vérifier que les descriptions de fonction sont claires
- Valider que response_semantics extrait les bonnes données
- Tester avec des requêtes plus spécifiques