Agents OpenAI : un contrat d’artefact pour livrer et valider

La livraison d’un agent ne se résume pas à quelques fichiers. Un contrat d’artefact lui impose une structure, des preuves et un statut de révision pour qu’un humain ou un service puisse l’exploiter. À l’appui de l’API Agents d’OpenAI, ce cadre propose cinq volets concrets, de la surface de sortie à la règle de transfert.

Une mise en pratique avec manifeste, run unique et répertoires dédiés

Une organisation pratique consiste à regrouper chaque exécution d’agent sous un répertoire de sortie dédié, tel que /workspace/outputs/run-<id>, en séparant clairement manifeste, livrables, preuves et vérifications. Un identifiant de run unique évite les chevauchements entre travaux parallèles. Le manifeste doit rester explicite et factuel, la narration étant réservée au README. Un exemple de manifest.json comprend contract_version, run_id, task_type, status, summary_path, la liste des deliverables, les checks, des open_questions et un bloc review. Dans cet exemple, le statut est needs_review et une révision est requise avec un propriétaire désigné (sre-on-call). Le manifeste n’inclut ni champ notes illimité ni promesse d’action non approuvée. Cette organisation rejoint l’usage de /workspace/outputs mentionné pour les résultats, preuves et atténuations recommandées.

Pourquoi les sorties brutes échouent au transfert

Un agent qui se déclare terminé ne livre pas nécessairement un élément exploitable. Dans la pratique, retrouver le travail réel s’avère difficile dans des espaces temporaires ou des arborescences confuses, et cet écart devient coûteux dès que les flux deviennent asynchrones ou impliquent une passation. Sans preuves, un manager ne peut pas approuver une atténuation, et un service ne peut pas ingérer un rapport dont le nom varie à chaque exécution. Un second agent ne sait pas interpréter un dossier vide. Les écueils observés sont fréquents : livrable utile noyé dans des artefacts temporaires, contrôles déclarés sans commande ni statut, confusion entre observation, hypothèse et changement, écrasement croisé de sorties par noms génériques, JSON valide mais incomplet, secrets ou données brutes sortis à tort du bac à sable. Les métadonnées d’artefacts, limitées à des informations techniques, n’indiquent ni adéquation à la tâche ni sources de soutien.

Cinq volets pour cadrer une livraison exploitable

Le contrat d’artefact s’articule en cinq parties. D’abord, déclarer la surface de livraison : répertoire de sortie, fichiers requis et types d’artefacts, en intégrant explicitement l’emplacement d’écriture dans la tâche. L’attendu n’est pas un simple rapport, mais un rapport lisible par un humain, un manifeste lisible par une machine et les fichiers de soutien nommés dans l’espace de sortie. Ensuite, donner à chaque fichier un rôle : README.md comme porte d’entrée humaine, manifest.json comme point d’entrée machine avec statut et inventaire, evidence/ pour les pièces, deliverables/ pour le travail demandé et checks/ pour les tests et journaux. Cette séparation évite d’interpréter une transcription de terminal comme une conclusion. Plus largement, un transfert est un petit paquet vérifiable qui explicite existence, pertinence et décisions restantes. Le contrat rend ces attentes explicites avant l’exécution, s’apparente à un contrat d’API tout en intégrant révision humaine et preuve opérationnelle, et reconnaît qu’un schéma JSON ne suffit pas à garantir justesse, actualité ou sûreté d’usage.

Exiger des preuves reliées aux affirmations

Chaque revendication doit être appuyée par une preuve. Pour du code, cela inclut un résultat de test et un diff ; pour une enquête d’incident, des requêtes de journaux horodatées, des instantanés de métriques et la liste des questions ouvertes ; pour des données, la version d’entrée, le script de transformation, des comptes de lignes et des validations. La confiance, bien que pertinente, ne remplace pas la preuve. L’agent doit signaler ses incertitudes et inventorier les preuves manquantes. Ce cadre transforme une exécution d’agent en un parcours de révision plutôt qu’en une accumulation opaque de sorties.

Valider le paquet et distinguer exécution et approbation

La validation doit être déterministe autant que possible : présence des fichiers requis, analyse correcte du manifeste, existence des fichiers référencés, confinement des chemins dans l’espace de sortie et respect d’une limite de taille. Si la tâche inclut un test, la commande désignée doit se terminer sans erreur. Dans les cas où une intervention humaine est requise, le paquet doit porter le statut needs_review plutôt que complet. Il convient de ne pas assimiler l’achèvement de la mission par l’agent à la validation par l’organisation.

Règles de transfert, rétention et intégration dans l’invite

Le contrat se termine par des règles de transfert et de conservation, avec un propriétaire et une action suivante précisés, comme l’examen SRE avant redémarrage, le dépôt signé par la CI dans une demande de tirage ou la décision de publication par un responsable de recherche. Il indique la durée de disponibilité du paquet, les éléments à expurger et rappelle que l’immuabilité ne remplace pas le contrôle d’accès. Identifiants, données clients brutes, captures d’écran et journaux doivent être traités avec précaution. Pour éviter les artefacts incohérents, ces exigences doivent figurer dans l’invite de tâche : localisation stricte des sorties (par exemple /workspace/outputs/run-8f3c), fichiers requis, séparation entre observations, hypothèses et recommandations, interdiction d’actions externes non approuvées, et auto‑vérifications avant clôture. Cette approche permet à l’agent d’être utile sans prétendre à une autorité, tout en donnant aux humains la visibilité sur la décision restante et aux systèmes une collecte fiable et répétable. Elle s’appuie sur l’API Agents d’OpenAI et ses environnements capables d’exécuter du code, de gérer des fichiers et d’exposer des artefacts de session immuables, tout en restant indépendante des noms d’API en phase bêta.