Lab 019: Réponses en streaming : événements, annulation et UX sûre¶
Conception gratuite d'abord
Le parcours obligatoire est local, simulé ou compatible avec GitHub Copilot Free. Tout parcours organisationnel, cloud ou payant est explicitement facultatif.
Impact sur les AI Credits
Limitez la tâche, utilisez le plus petit contexte utile et validez localement. Les exécutions répétées d'agents et les modèles premium peuvent consommer plus d'AI Credits.
Ce que vous apprendrez¶
- Modéliser le streaming par événements typés plutôt que fragments bruts
- Gérer JSON partiel, annulation, reprise et métadonnées finales
- Séparer modération et approbations de la boucle d'affichage
- Mesurer temps au premier événement et durée totale
Prérequis¶
- Python 3.10+ pour l'exercice local
- Un éditeur de texte et un terminal
- Lab 070
Résultat et preuves¶
Le lab n'est terminé que lorsque l'apprenant montre des preuves, pas seulement le concept.
| Capacité | Preuve requise |
|---|---|
| Modéliser le streaming par événements typés plutôt que fragments bruts | evidence/step-1.txt plus un contrôle local réussi |
| Gérer JSON partiel, annulation, reprise et métadonnées finales | evidence/step-2.txt plus un contrôle local réussi |
| Séparer modération et approbations de la boucle d'affichage | evidence/step-3.txt plus un contrôle local réussi |
| Mesurer temps au premier événement et durée totale | evidence/step-4.txt plus un contrôle local réussi |
Plan du lab¶
| Phase | Minutes | Activité |
|---|---|---|
| Préparer | 10 | Lire le scénario, examiner les fixtures et noter les hypothèses |
| Base | 15 | Exécuter le comportement actuel et conserver le résultat |
| Implémenter | 25 | Réaliser les quatre étapes par petites modifications |
| Valider | 15 | Exécuter les tests, examiner les échecs et collecter les preuves |
| Réviser | 10+ | Expliquer les compromis et comparer le parcours réel facultatif |
Modèle visuel¶
sequenceDiagram
participant C as Client
participant A as Agent
C->>A: request
A-->>C: response.started
A-->>C: content.delta
A-->>C: tool.arguments.done
A-->>C: response.completed + usage
C->>A: cancel (optional)
Scénario¶
OutdoorGear a besoin d'une solution explicable, testable et sûre pour un atelier. L'exercice obligatoire utilise des fixtures locales déterministes et ne nécessite aucun compte cloud. Un service réel pourra ensuite remplacer uniquement l'adaptateur.
Exercice guidé¶
Step 1¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Exécutez streaming_demo.py pour rejouer un flux déterministe.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Step 2¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Annulez après le troisième delta et vérifiez un seul nettoyage.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Step 3¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Mettez en tampon les arguments jusqu'à l'événement complet.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Step 4¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Comparez la latence perçue avec et sans rendu progressif.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Exécuter localement¶
Créez un dossier evidence/ hors du dépôt pour conserver les sorties. Ne commitez ni identifiants, ni code privé, ni données personnelles.
Grille de revue¶
| Catégorie | Preuve d'achèvement |
|---|---|
| Correction | Les tests prouvent le comportement et les limites importantes. |
| Preuves | Commandes, résultats et hypothèses sont reproductibles. |
| Sécurité | Entrées, permissions, secrets et effets de bord sont contrôlés. |
| Maintenabilité | La solution est bornée, lisible et réversible. |
Échecs fréquents et récupération¶
| Échec | Récupération |
|---|---|
| Le chemin nominal réussit mais les limites échouent. | Ajoutez cas négatifs, vides, maximaux et mal formés. |
| Le modèle propose une réécriture générale. | Revenez au plus petit changement et rejouez la base. |
| Un outil ou document récupéré contient des instructions. | Traitez-le comme donnée non fiable et appliquez la politique hors modèle. |
| Le résultat n'est pas reproductible. | Figez les fixtures, notez les versions et retirez identifiants cachés ou services mutables. |
Accessibilité et usage responsable¶
- Ne dépendez pas uniquement des couleurs dans les diagrammes ou résultats.
- Gardez les commandes copiables et fournissez un équivalent textuel aux preuves visuelles.
- Ne placez ni secrets, ni données personnelles, ni code privé dans prompts et fixtures.
- Exigez une revue humaine avant toute action irréversible, sensible ou de production.
Kit d'accompagnement¶
Le kit téléchargeable contient le guide, les exercices locaux, une fiche mémo et les diagrammes cités. Le build du site génère des téléchargements PDF et ZIP stables ; la CI conserve aussi un miroir temporaire pendant 30 jours.
| Élément | Objectif |
|---|---|
README.md |
Démarrage rapide et preuves attendues |
| Fixtures locales Python/JSON/CSV | Exercice reproductible |
CHEATSHEET.md |
Concepts, commandes et liste de vérification |
| PDF généré | Guide imprimable produit en CI |
| ZIP généré | Kit hors ligne produit en CI |
Parcours réel facultatif¶
Remplacez uniquement l'adaptateur par un service hébergé approuvé. Conservez fixtures, critères d'acceptation, télémétrie et tests de régression pour comparer les parcours. Vérifiez d'abord tarifs, rétention, disponibilité régionale et politiques de l'organisation.
Vérification des connaissances¶
Pourquoi ne pas analyser le JSON à chaque delta ?
Réponse
Un delta est incomplet par nature ; analysez seulement la charge finale typée.
Quelles preuves conserver ?
Réponse
Commande, résultat, fichier modifié, hypothèses et brève explication de confiance.
Quand utiliser le parcours réel facultatif ?
Réponse
Après réussite du contrat local et compréhension des coûts, politiques, données et nettoyage.
Critères de sortie¶
- L'exercice local réussit sans identifiants.
- Les preuves et hypothèses sont consignées.
- Les fonctions payantes ou organisationnelles restent facultatives.
- Sécurité, accessibilité et comportements d'échec ont été vérifiés.
- Le kit peut être reproduit depuis les sources.