Shell, Skills et compactage : conseils pour créer des agents capables de mener à bien des tâches de longue durée

Nous passons des assistants qui répondent en un seul échange à des agents capables de travailler dans la durée sur des tâches concrètes. Ils peuvent lire de vastes jeux de données, mettre à jour des fichiers et écrire des applications.

À partir des retours des développeurs et de notre expérience avec Codex et nos agents internes, nous lançons trois briques qui facilitent l’exécution de tâches de longue durée par les agents :

• Les Skills, conformes au standard ouvert Agent Skills, regroupent des instructions réutilisables et versionnées. Vous pouvez les monter dans des conteneurs pour que les agents exécutent leurs tâches de façon plus fiable.
• L’outil shell évolue. Il fournit un conteneur hébergé par OpenAI avec un accès contrôlé à Internet, dans lequel un agent peut installer des dépendances, exécuter des scripts et enregistrer ses résultats, par exemple des rapports et d’autres artefacts.
• Le compactage côté serveur permet de compacter automatiquement le contexte pendant les longues exécutions, pour que vos agents n’atteignent jamais la limite de contexte.

La documentation et la référence de l’API décrivent chacun de ces éléments séparément. Cet article présente des techniques moins évidentes qui, jusqu’ici, ont donné les meilleurs résultats chez OpenAI et en production chez Glean, l’un des premiers clients à utiliser les skills.

Quelques repères

Skills : des « procédures » que le modèle peut charger à la demande

Une skill regroupe des fichiers et un manifeste SKILL.md qui contient un en-tête de métadonnées et des instructions. C’est un guide pratique versionné que le modèle peut consulter au moment de passer à l’action.

Lorsque des skills sont disponibles, la plateforme communique au modèle les champs name, description et path de chacune. Le modèle s’appuie sur ces métadonnées pour décider s’il doit utiliser une skill. Si c’est le cas, il lit SKILL.md pour connaître le workflow complet.

Outil shell : un environnement d’« exécution » pour les agents

Grâce à l’outil shell, les modèles disposent d’un véritable terminal dans l’un des deux environnements suivants :

• Des conteneurs hébergés et gérés par OpenAI.
• Un shell local que vous exécutez vous-même. L’outil fonctionne de la même façon et vous gardez la maîtrise de la machine.

Le shell distant fonctionne via l’API Responses. D’une requête à l’autre, vous pouvez ainsi conserver l’état du travail en cours, enchaîner les appels d’outils, poursuivre le travail sur plusieurs échanges et récupérer les artefacts produits.

Compactage : poursuivre les exécutions de longue durée

À mesure qu’un workflow s’allonge, il finit par atteindre la limite de la fenêtre de contexte. Le compactage côté serveur lui permet de se poursuivre en gérant cette fenêtre et en comprimant automatiquement l’historique de la conversation.

L’API Responses propose deux modes de compactage :

• Compactage côté serveur (nouveauté) : lorsque le contexte dépasse le seuil, le compactage se déclenche automatiquement dans le flux en cours, sans appel distinct.
• Point de terminaison de compactage autonome : utilisez /responses/compact pour choisir précisément quand déclencher le compactage.

Pourquoi les combiner ?

• Les skills simplifient les prompts en regroupant les procédures stables et les exemples dans un ensemble réutilisable.
• Le shell fournit un environnement d’exécution complet pour installer du code, lancer des scripts et enregistrer les résultats.
• Le compactage assure la continuité des longues exécutions. Le même workflow peut se poursuivre sans que vous ayez à remanier le contexte à la main.
• Ensemble, ces outils permettent de reproduire des workflows et d’en exécuter concrètement les étapes, sans transformer le prompt système en un document démesuré et difficile à maintenir.

Conseils pratiques

1) Rédigez les descriptions des skills comme des règles de routage et évitez le discours commercial

C’est la description d’une skill qui permet au modèle de décider s’il doit l’utiliser. Elle doit répondre à trois questions :

• Quand dois-je utiliser cette skill ?
• Dans quels cas dois-je l’éviter ?
• Quels résultats dois-je produire et selon quels critères juger de la réussite ?

Dans la description, ajoutez une courte rubrique « Quand utiliser cette skill et quand l’éviter ». Donnez des indications concrètes sur les entrées, les outils à utiliser et les artefacts attendus.

2) Ajoutez des contre-exemples et des cas limites pour réduire les erreurs de déclenchement

Un problème inattendu peut survenir quand on met des skills à disposition : dans un premier temps, le modèle peut les déclencher moins souvent à bon escient. Nous avons constaté que l’ajout de contre-exemples et de cas limites aide à corriger le problème.

En pratique, indiquez explicitement quelques cas sous la forme « N’appelez pas cette skill lorsque… » et précisez la marche à suivre à la place. Le modèle choisira plus facilement la bonne skill, surtout si plusieurs se ressemblent au premier abord.

Glean l’a constaté lors d’évaluations ciblées : avec le routage par skills, le taux de déclenchement a d’abord baissé d’environ 20 %, puis il est revenu à son niveau initial après l’ajout de contre-exemples et de cas limites dans les descriptions.

3) Placez les modèles de documents et les exemples dans la skill (leur coût est négligeable tant qu’ils ne servent pas)

Si vous accumulez les modèles de documents dans le prompt système, cessez de les y mettre.

Intégrer des modèles de documents et des exemples détaillés aux skills présente deux avantages :

• Ils sont disponibles au moment précis où ils servent, quand la skill est appelée.
• Ils n’augmentent pas le nombre de tokens des requêtes sans rapport avec la skill.

Cette approche est particulièrement efficace pour produire des documents de travail tels que :

• Des rapports structurés.
• Des synthèses de triage des dossiers transmis au niveau supérieur.
• Des plans d’action par compte client.
• Des comptes rendus d’analyse de données.

Selon Glean, cette approche a permis d’obtenir certains de ses gains les plus importants en qualité et en latence en production, car les exemples ne sont chargés qu’au déclenchement de la skill.

4) Prévoyez dès le départ la réutilisation des conteneurs et le compactage pour les tâches de longue durée

Les agents réussissent rarement une tâche de longue durée avec un prompt qui leur demande de tout faire en une seule étape. Prévoyez dès le départ comment ils pourront poursuivre leur travail :

• Réutilisez le même conteneur d’une étape à l’autre pour conserver les dépendances, les fichiers en cache et les résultats intermédiaires.
• Transmettez previous_response_id pour que le modèle puisse poursuivre son travail dans le même fil.
• Utilisez le compactage par défaut pour les longues exécutions, sans attendre d’avoir épuisé la fenêtre de contexte.

Cette combinaison limite les reprises depuis le début et préserve la cohérence des tâches en plusieurs étapes à mesure que le fil s’allonge.

5) Pour obtenir un comportement déterministe, demandez explicitement au modèle d’utiliser la skill

Par défaut, le modèle décide quand utiliser une skill. C’est souvent le comportement souhaité.

Mais si vous exécutez en production un workflow dont les règles sont claires et que vous préférez un choix déterministe, il suffit d’écrire :

« Utilisez la skill <skill name>. »

C’est le moyen le plus simple de gagner en fiabilité. Le modèle dispose alors d’une consigne explicite pour choisir la skill.

6) Prévoyez des mesures de confinement lorsque vous combinez skills et accès réseau

Cette mesure de sécurité est facile à négliger au départ, mais difficile à mettre en place après coup.

Associer des skills à un accès réseau ouvert crée un risque élevé d’exfiltration de données. Si vous activez le réseau, limitez strictement les destinations autorisées et traitez les résultats des outils comme des données non fiables. Dans les workflows destinés au grand public, où les utilisateurs s’attendent à devoir confirmer les actions sensibles, évitez d’associer un accès Internet ouvert à des procédures capables d’effectuer des actions étendues.

Adoptez par défaut la configuration suivante :

• Skills : autorisées
• Shell : autorisé
• Réseau : activé uniquement avec une liste d’autorisation minimale, requête par requête, pour des tâches au périmètre restreint

7) Utilisez /mnt/data comme point de transfert des artefacts

Pour les workflows qui utilisent le shell distant, écrivez dans /mnt/data les résultats que vous comptez récupérer, examiner ou transmettre aux étapes suivantes. Il peut s’agir de rapports, de jeux de données nettoyés ou de feuilles de calcul finalisées.

Retenez ce principe : les outils écrivent les fichiers sur le disque, les modèles raisonnent à partir de leur contenu et les développeurs les récupèrent sur ce même disque.

8) Distinguez les deux niveaux d’autorisation réseau : l’organisation et la requête

L’accès réseau se configure à deux niveaux :

• La liste d’autorisation de l’organisation, configurée par un administrateur, fixe l’ensemble maximal des destinations autorisées.
• Pour chaque requête, network_policy doit se limiter à un sous-ensemble des destinations autorisées par l’organisation.

En pratique, deux règles en découlent :

1. Maintenez une liste courte et stable au niveau de l’organisation : « les destinations de confiance que vous avez approuvées ».
2. Limitez davantage la liste pour chaque requête : « les destinations nécessaires à cette seule tâche ».

Si une requête contient des domaines absents de la liste d’autorisation de l’organisation, elle échoue.

9) Utilisez domain_secrets pour les appels authentifiés afin d’éviter les fuites d’identifiants

Si un domaine autorisé exige des en-têtes d’authentification, utilisez domain_secrets pour que le modèle n’ait jamais accès aux identifiants en clair.

À l’exécution, le modèle voit des variables de substitution (par exemple $API_KEY). Un composant auxiliaire injecte les valeurs réelles uniquement pour les destinations approuvées. Adoptez cette configuration par défaut chaque fois que votre agent doit appeler une API protégée depuis un conteneur.

10) Utilisez les mêmes API dans le cloud et en local

Vous pouvez utiliser les skills et le shell sans avoir à tout héberger :

• Les skills fonctionnent aussi bien avec le shell distant qu’en mode shell local.
• Le shell propose un mode d’exécution local dans lequel vous exécutez vous-même shell_call, puis renvoyez shell_call_output au modèle.
• Si vous utilisez le SDK Agents, vous pouvez aussi y intégrer votre propre moteur d’exécution du shell.

Voici un cycle de développement possible :

1. Commencez en local pour itérer rapidement, accéder aux outils internes et faciliter le débogage.
2. Passez aux conteneurs hébergés lorsque vous avez besoin d’exécutions reproductibles et isolées, ainsi que de déploiements cohérents.
3. Conservez les mêmes skills dans les deux modes pour que le workflow reste stable même si le lieu d’exécution change.

Trois exemples de mise en œuvre

N’hésitez pas à expérimenter avec ces nouveaux outils pour agents. Voici trois façons de les combiner pour créer des applications utiles.

Exemple A : installez les dépendances, récupérez les données, puis écrivez l’artefact

C’est la manière la plus simple de tirer parti du shell distant. L’agent installe des dépendances, récupère des données externes et produit un livrable concret.

Par exemple :

• Installez deux bibliothèques.
• Extrayez des données d’un site ou appelez une API.
• Enregistrez un rapport dans /mnt/data/report.md.

Cette approche sert de base aux agents chargés de tâches concrètes, car elle fournit un résultat distinct que l’on peut examiner. Votre application peut présenter l’artefact à l’utilisateur, le consigner, le comparer à une version précédente ou le transmettre à une étape ultérieure.

Exemple B : combinez les skills et le shell pour des workflows reproductibles

Après avoir mis au point un ou deux workflows avec le shell, vous rencontrerez une autre difficulté : ils fonctionnent, mais perdent en fiabilité à mesure que les prompts s’écartent de leur formulation initiale.

C’est là que les skills interviennent. Voici une structure qui tient dans la durée :

1. Décrivez le workflow dans une skill, avec ses étapes, ses garde-fous et ses modèles de documents.
2. Montez la skill dans votre environnement shell.
3. Demandez à l’agent de suivre la skill pour produire les artefacts de façon déterministe.

Cette méthode est particulièrement efficace pour des workflows tels que :

• L’analyse ou la modification de feuilles de calcul.
• Le nettoyage de jeux de données et la production d’une synthèse.
• La production de rapports standardisés pour des processus métier récurrents.

Exemple C (avancé) : utilisez les skills pour formaliser les workflows d’entreprise

Nous avons rapidement constaté une baisse de précision lorsqu’un agent passe de l’appel à un seul outil à l’orchestration de plusieurs outils. Les skills peuvent combler cet écart en donnant au modèle une procédure pour guider son raisonnement sur l’utilisation des outils, sans alourdir le prompt système.

Voici ce qu’a observé Glean :

• Une skill dédiée à Salesforce a fait passer la précision lors des évaluations de 73 % à 85 % et a réduit le délai avant le premier token de 18,1 %.
• L’équipe a affiné les règles de routage, ajouté des contre-exemples et intégré des modèles de documents et des exemples directement à la skill.
• Glean utilise également les skills pour formaliser des tâches récurrentes dans ses workflows d’entreprise, notamment la planification par compte client, le triage des dossiers transmis au niveau supérieur et la création de contenus conformes à l’identité de la marque.

C’est à cette échelle que les skills prennent tout leur intérêt. Elles deviennent des procédures opérationnelles standard que vous pouvez mettre à jour à mesure que votre organisation évolue et que les agents exécutent de manière cohérente.

Concevez une fois, exécutez partout

Les agents qui travaillent dans la durée deviennent bien plus utiles lorsqu’ils peuvent à la fois suivre des procédures et accomplir des tâches concrètes sur un ordinateur. Les skills, le shell distant et le compactage leur donnent cette capacité. En résumé :

• Utilisez les skills pour décrire la marche à suivre : procédures, modèles de documents et garde-fous.
• Utilisez le shell pour passer à l’action : installer des dépendances, exécuter des scripts et écrire des artefacts.
• Utilisez le compactage pour préserver la cohérence des longues exécutions sans gérer le contexte à la main.
• Commencez en local pour itérer rapidement.
• Passez aux conteneurs hébergés lorsque vous avez besoin d’exécutions reproductibles et isolées.
• Limitez strictement l’accès réseau avec des listes d’autorisation au niveau de l’organisation et de chaque requête. Utilisez des secrets propres à chaque domaine pour les appels authentifiés.

Pour mettre ces techniques en pratique dans votre application, consultez la documentation sur les skills, la documentation sur le shell et la documentation sur le compactage.