Scénario : de l’idée au backlog de réalisation

Un utilisateur métier soumet une idée à un agent Copilot Studio. La squad product mène les recherches, élabore un plan, produit les livrables destinés aux parties prenantes et restitue un backlog structuré. L’agent crée ensuite les epics, user stories et tâches correspondants dans Azure DevOps, Jira ou GitHub. Cette page décrit l’ensemble du parcours pour vous permettre de le reproduire.

Ce que vous obtiendrez#

1. Un serveur MCP déployé dans votre propre locataire Azure, avec le profil product et les outils métier activés.
2. Un agent Copilot Studio doté de deux connecteurs : celui de ce serveur et le connecteur natif de votre outil de suivi du travail.
3. Un échange reproductible : « transforme ce PRD en backlog » → confirmation → création des éléments de travail, avec les bons liens parent-enfant et l’intégralité des critères d’acceptation.
4. Une trace durable sous .copilot-tracking/ dans votre propre stockage, relue automatiquement à l’exécution suivante.

Partie 0 — Prérequis#

• Un abonnement Azure dans lequel vous pouvez déployer des ressources et l’autorisation de créer une inscription d’application Entra.
• Un déploiement Azure OpenAI. C’est là que se situe le coût.
• Une licence Copilot Studio et la possibilité d’ajouter un connecteur personnalisé.
• Azure DevOps, Jira ou GitHub, avec une licence permettant l’utilisation du connecteur natif.
• Le dépôt cloné et la commande npm ci && npm run build exécutée une fois.

Partie 1 — Déployer en activant le parcours produit#

Suivez les étapes 1 à 7 de host/RUNBOOK.md pour le déploiement de base. Ce scénario nécessite davantage de fonctionnalités que le mode consultatif par défaut. Configurez donc les paramètres suivants avant l’étape 6 : ils sont disponibles à la fois dans main.bicepparam et sous forme de variables d’environnement.

Partie 2 — Choisir où conserver l’historique#

Ce choix est souvent négligé. Après une première utilisation réelle, on découvre alors qu’un mois de résultats de la squad se trouve dans un emplacement que personne ne peut consulter. Décidez maintenant : un seul paramètre suffit, et il s’applique à tout ce que la squad écrit.

Ce qui est effectivement écrit#

Avec SQUAD_MCP_ENABLE_ARTIFACTS=true, chaque exécution écrit une arborescence .copilot-tracking/ consultable, identique à celle que la squad produit lorsqu’elle s’exécute localement dans VS Code :

squad/team.md                          the 13 seeded roles
squad/routing.md                       the rows those roles can serve
squad/state.json                       the ledger
squad/decisions.md                     append-only — incl. the Intake Readiness Verdict
squad/notifications.md                 append-only
squad/history/<agent>.md               per agent, with a measured Consumption block
squad/history/autopilot-run-<id>.md    per run
squad/consumption.md                   rebuilt from those blocks, so earlier turns are never dropped
plans/ · docs/ · outputs/ · ppt/<date>/<slug>/   the deliverables themselves

Choisir une destination#

Un seul paramètre, SQUAD_MCP_MEMORY_BACKEND, définit simultanément la destination de la mémoire, du registre et des livrables.

Si vous avez choisi SharePoint#

Chaque entrée devient un fichier Markdown à l’emplacement suivant :

<rootPath>/<tenantId>/<project>/<path>.md

SharePoint en gère les versions et lui applique vos politiques existantes de conservation, de recherche et de prévention de la perte de données (DLP). La gestion des accès concurrents utilise l’eTag natif de Graph avec If-Match : une écriture fondée sur une version obsolète est donc refusée au lieu d’écraser les données.

Vous devez effectuer vous-même deux étapes :

1. Récupérez l’identifiant du lecteur de la bibliothèque qui accueillera l’historique :
   Copier

   SITE_ID=$(az rest --method GET \
     --url "https://graph.microsoft.com/v1.0/sites/<TENANT>.sharepoint.com:/sites/<SITE_PATH>" \
     --query id --output tsv)
   
   az rest --method GET \
     --url "https://graph.microsoft.com/v1.0/sites/$SITE_ID/drives" \
     --query "value[].{name:name,id:id}" --output table

2. Accordez à l’identité de l’application l’accès à cette seule bibliothèque, en tant qu’administrateur :
   Copier

   az deployment group create \
     --resource-group "$RG" \
     --template-file host/infra/graph-memory-permissions.bicep \
     --parameters host/infra/graph-memory-permissions.bicepparam

   Ce déploiement attribue Sites.Selected, qui, à lui seul, ne donne accès à aucun site, puis accorde un droit d’écriture uniquement sur le site que vous avez indiqué. Il est volontairement distinct : il nécessite AppRoleAssignment.ReadWrite.All et Sites.FullControl.All, des autorisations bien plus étendues que celles requises pour déployer la Container App. Vos déploiements courants n’exigent donc jamais de droits d’administration Graph. Le relancer n’entraîne aucune modification supplémentaire.

Artefacts volumineux#

Une entité Table est soumise à une limite de taille, qu’un PRD ou un backlog complet dépassera. Activez le stockage des données excédentaires pour éviter l’échec de l’écriture :

Tout contenu dépassant le seuil est stocké dans un blob, avec un pointeur conservé dans l’entité. La lecture reste transparente.

Proposer plusieurs destinations aux équipes#

Si un même déploiement dessert plusieurs équipes qui ne doivent pas partager la même destination, déclarez une liste de destinations autorisées plutôt qu’un backend unique :

SQUAD_MCP_MEMORY_TARGETS=[
  { "name": "azure",      "backend": "table", "tableName": "squadmemory" },
  { "name": "sharepoint", "backend": "graph", "driveId": "<DRIVE_ID>", "rootPath": "squad-memory" }
]
SQUAD_MCP_MEMORY_DEFAULT_TARGET=azure

L’appelant transmet alors un nom target opaque. Vous gardez la maîtrise de tous les champs contenant des informations d’authentification ; un nom non déclaré est refusé avant toute entrée-sortie, sans jamais utiliser la destination par défaut comme solution de repli.

Relire l’historique#

Deux modes sont possibles ; dans ce scénario, c’est le premier qui importe :

• Automatiquement. Avec SQUAD_MCP_MEMORY_AUTO_ENABLED=true, le serveur lit les entrées state et decisions du projet avant chaque délégation et les injecte comme des données explicitement délimitées, jamais comme des instructions faisant autorité. Personne n’a besoin de penser à le demander. C’est pourquoi l’appel à squad_backlog dans la partie 7 ne nécessite pas de recoller l’artefact de l’exécution.
• À la demande. squad_history permet de parcourir l’arborescence : op=index pour en obtenir une synthèse, op=list pour en lister le contenu et op=read pour ouvrir un fichier. Il nécessite l’étendue d’autorisation Squad.Memory.

Garanties communes à toutes les destinations#

• Le tenantId du jeton validé constitue toujours le premier segment du chemin : l’isolation par locataire est donc assurée dans Azure Table, SharePoint et sur disque.
• La partition est déterminée à partir d’une sous-squad épinglée ou de SQUAD_MCP_MEMORY_DEFAULT_PROJECT, et jamais à partir d’un texte libre fourni par l’appelant.
• Lorsque SQUAD_MCP_RUN_ENCRYPTION_KEY_B64 est défini, les artefacts des étapes, le verdict du conseil et les champs request/context de l’appelant sont chiffrés au repos avec AES-256-GCM.
• Les écritures utilisent une comparaison suivie d’un échange atomique : deux exécutions simultanées dans un même projet ne peuvent donc pas écraser leurs données respectives.

Partie 3 — Exposer les étendues d’autorisation utilisées par ce scénario#

Dans l’inscription d’application Entra créée à l’étape 2 du guide d’exploitation, exposez les étendues suivantes et accordez les consentements correspondants :

Le contrôle d’accès refuse toute opération sans l’étendue requise : si elle manque, le serveur renvoie une réponse 403, sans effectuer de travail ni générer de facturation.

Partie 4 — Importer le connecteur dans Copilot Studio#

1. Régénérez le connecteur pour qu’il corresponde à votre build, puis remplacez les valeurs provisoires dans generated/copilot-studio-connector/apiDefinition.swagger.json et apiProperties.json :
   Copier

   npm run generate:connector

   Valeur provisoire	Valeur de remplacement
   <SQUAD_MCP_HOST>	le nom de domaine complet (FQDN) de votre Container App, uniquement le nom d’hôte, sans schéma
   <ENTRA_TENANT_ID>	l’identifiant de votre locataire
   <ENTRA_CLIENT_ID>	l’identifiant de l’application obtenu à l’étape 2
   <SQUAD_MCP_AUDIENCE>	api://<ENTRA_CLIENT_ID>

2. Ajoutez un connecteur personnalisé dans Copilot Studio à partir du fichier OpenAPI. Il déclare l’opération x-ms-agentic-protocol: mcp-streamable-1.0 /mcp.
3. Finalisez la connexion Entra OAuth 2.0 en accordant le consentement aux étendues de la partie 3.
4. Activez l’orchestration générative sur l’agent. Sans elle, l’agent ne peut appeler aucun outil MCP : c’est de loin la raison la plus fréquente lorsqu’« il ne se passe rien ».
5. Ajoutez le connecteur de votre outil de suivi au même agent : le connecteur certifié Azure DevOps, Jira ou GitHub, authentifié avec l’identité de l’utilisateur final.
6. Collez les instructions générées pour l’agent depuis generated/copilot-studio-connector/agent-instructions.md dans le champ Instructions de l’agent. Elles contiennent déjà le protocole de création des éléments de travail, l’exigence de confirmation et les règles de rattachement parent-enfant. Supprimez la section consacrée à la mémoire : vous avez activé la mémoire automatique dans la partie 1, l’agent ne doit donc pas appeler les outils de mémoire.

Partie 5 — Ce que le profil product exécute réellement#

profile: "product" initialise 13 rôles. C’est cette initialisation qui distingue ce scénario d’un appel générique à squad_run. Une fois les rôles associés aux agents disponibles dans le package, l’exécution du profil product enchaîne les étapes suivantes :

Deux comportements méritent d’être compris avant de lancer l’exécution :

• Le point de validation des données d’entrée peut arrêter l’exécution. Comme le profil product initialise le rôle intake-validator, toute exécution fondée sur un document d’exigences fait d’abord l’objet d’une validation. Le validateur consigne le verdict Ready, Ready-With-Gaps ou Not-Ready. Dans le cas de Not-Ready, le pipeline s’arrête avec reason: "intake_not_ready", plutôt que de laisser sept spécialistes travailler à partir de données qu’il vient de rejeter. C’est le fonctionnement attendu du point de validation : corrigez le document et relancez l’exécution.
• Il n’existe pas d’étape distincte de transmission du backlog. Le profil product inclut product-owner parmi les spécialistes chargés des livrables : la transmission correspond donc à l’étape 4. Pour un profil qui ne contient pas ce rôle, une étape consacrée au backlog est ajoutée à la fin.

Chaque spécialiste écrit dans son propre répertoire racine, où vous retrouverez ensuite ses livrables :

Partie 6 — Lancer l’exécution#

Dans l’agent Copilot Studio, l’utilisateur formule par exemple la demande suivante :

Run the full product squad on our customer onboarding PRD and turn it into a delivery backlog.

L’agent appelle squad_run. Assurez-vous que vos instructions transmettent bien le profil :

{
  "name": "squad_run",
  "arguments": {
    "request": "Turn our customer onboarding PRD into a delivery backlog",
    "profile": "product",
    "mode": "autopilot",
    "squad": "onboarding",
    "context": "<the PRD text, or the constraints the user gave>"
  }
}

Le résultat dépend du choix effectué dans la partie 1 :

curl -sS -X POST "https://$FQDN/admin/approve" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"runId":"<run-id>"}'

Partie 7 — Transformer le résultat en éléments de travail#

L’artefact consolidé est rédigé en prose : il convient à une personne, mais pas à un connecteur. squad_backlog assure la conversion :

{
  "name": "squad_backlog",
  "arguments": {
    "request": "Break the approved onboarding plan into epics, stories, and tasks",
    "squad": "onboarding"
  }
}

Lorsque la mémoire automatique est activée, vous n’avez pas à recoller les résultats de l’exécution : la lecture préalable intègre l’état antérieur du projet à context en tant que données. Il suffit donc de transmettre la même valeur squad. Ne fournissez explicitement context que pour ajouter des informations absentes de l’exécution, comme un backlog existant ou une définition de « terminé ».

Le contrat renvoyé#

{
  "summary": "Plain-language summary for the business user.",
  "epics": [ { "title": "...", "description": "...",
               "acceptanceCriteria": ["..."],
               "stories": [ { "title": "...", "tasks": [ ... ] } ] } ],
  "workItems": [
    { "ref": "E1",       "type": "Epic",       "title": "...", "acceptanceCriteria": ["..."] },
    { "ref": "E1-S1",    "type": "User Story", "parentRef": "E1",    "estimate": "M", "...": "..." },
    { "ref": "E1-S1-T1", "type": "Task",       "parentRef": "E1-S1", "...": "..." }
  ]
}

workItems est une liste aplatie obtenue par parcours en profondeur de epics : les parents précèdent donc toujours leurs enfants. En parcourant cette liste dans l’ordre et en créant les éléments au fur et à mesure, l’identifiant du parent existe toujours au moment où un enfant en a besoin. Les valeurs ref et parentRef sont attribuées par le serveur, et non par le modèle. C’est essentiel : l’agent établit les liens à partir des identifiants qu’il a enregistrés, jamais en rapprochant les titres, car ceux-ci ne sont pas uniques et le modèle peut les reformuler.

Le serveur valide et normalise le JSON du modèle. S’il n’y parvient pas, il signale proprement l’échec : l’agent ne reçoit donc jamais de résultat partiellement analysé. Des limites strictes s’appliquent : 30 epics, 30 user stories par epic, 30 tâches par user story, 20 critères d’acceptation et 4 000 caractères par champ texte. Un appel ne peut donc jamais produire un backlog de taille illimitée.

La boucle de création de l’agent#

Cette procédure figure déjà dans les instructions générées ; elle est rappelée ici pour vous permettre de vérifier le comportement observé :

1. Présentez à l’utilisateur le contenu de summary et la liste des epics et des user stories. Demandez une confirmation. Ne lancez jamais de création en masse sans confirmation.
2. Après confirmation, parcourez workItems dans l’ordre, avec un appel au connecteur par élément : le type provient de type, le titre de title, la description de description, et les lignes de acceptanceCriteria sont réunies en une liste.
3. Enregistrez l’identifiant créé en l’associant à la valeur ref de l’élément. Lorsqu’un élément possède un parentRef, rattachez-le à l’identifiant enregistré pour cette référence.
4. En cas d’échec, indiquez la ref concernée, poursuivez avec les autres éléments, puis proposez de ne réessayer que les créations en échec.
5. Espacez les appels. Les connecteurs imposent des limites de débit par connexion : créez un epic et ses user stories à la fois, plutôt que d’envoyer tout le tableau d’un seul coup.

Partie 8 — Adapter le contrat à votre outil de suivi#

Le contrat utilise les noms de types d’Azure DevOps. Il s’agit d’un choix de nomenclature, pas d’une dépendance imposée : la correspondance est définie dans les instructions de votre agent, et le serveur ne sait pas quel outil de suivi vous utilisez.

Partie 9 — Vérifier le résultat#

Dépannage#

Ce que ce scénario ne fait volontairement pas#

• Il n’écrit pas dans Azure DevOps, Jira ou GitHub depuis le serveur. Chaque écriture est effectuée par l’agent au moyen de la connexion propre à l’utilisateur, avec l’authentification, les règles DLP et les limites de débit du connecteur.
• Il n’exécute pas de code, n’ouvre pas de pull request et ne déploie rien.
• Il ne permet ni au modèle ni à l’appelant d’autoriser la reprise à un point de validation humain. Seul Squad.Operate le permet, par un canal distinct.
• Il ne traite pas le PRD comme des instructions. Le contenu de l’appelant constitue des données ; seule la charte d’un persona fait autorité.