Bonnes pratiques pour les agents IA : ingénierie de harness prête pour la production

Utilisez ceci comme une version révisée destinée aux opérateurs des idées présentées dans « AI Agent Best Practices: Production-Ready Harness Engineering (2026 Guide) » : étapes claires, emplacements de code ordonnés et notes de récupération qui survivent au transfert de responsabilités. L’étape « Aperçu » fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût en tokens ou requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés.

Qu’est-ce qu’un Agent Harness (et pourquoi en avez-vous besoin) ?

Pour l’étape « Qu’est-ce qu’un agent ? », définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les stocks de secrets et les flags fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans avoir à lire l’ensemble du système. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

Principes non négociables (du répertoire)

Pour les principes non négociables de cette étape, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez conjointement le parcours normal et les scénarios de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures. Authentifiez au niveau du gateway et réautorisez au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

Découverte approfondie du répertoire agents-best-practices

Pour une analyse approfondie de l’étape, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Authentifiez au niveau du gateway et réautorisez au niveau du plan de données. Un simple token porteur ne constitue pas une frontière entre les tenants. Pour une analyse approfondie de l’étape, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés.

Fichiers de référence en un coup d’œil

Lorsque vous travaillez sur les fichiers de référence à un stade donné, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, le débogage des boucles prend des heures inutilement.

Pourquoi ce n’est pas « une autre liste de conseils »

Lorsque vous analysez pourquoi une étape n’est pas applicable, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, les boucles d’analyse des erreurs perdent des heures précieuses.

Principes clés pour des agents prêts à être déployés en production (extraits de la compétence)

Lors de la phase des Principes clés pour la production, notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, le débogage devient une perte de temps considérable. Lors de la phase des Principes clés pour la production, notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Notez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le système passe de l’environnement de démonstration à des environnements partagés.

1. Le modèle propose – l’outil exécute

Le modèle 1 propose que l’étape d’exécution fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Fixez des limites budgétaires par tour et par session. Les outils agents élargissent de manière importante le contexte ; des plafonds stricts empêchent que les démonstrations se transforment en factures inattendues.

2. Chaque appel d’outil renvoie un résultat – même en cas d’échec

Chaque étape d’appel d’outil fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours optimal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Exposez les outils dotés de schémas restreints et de labels explicites indiquant leurs effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant de valider automatiquement.

3. Le risque modifie le processus

The 3 Risk changes the stage fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et une note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt qu’un processus embrouillé. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement. The 3 Risk changes the stage fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et une note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés.

4. Le contexte est assemblé, pas déversé

Pour l’étape d’assemblage du contexte 4, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les flags fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

5. Les tâches longues ont des budgets

Pour les 5 tâches longues à étapes, définissez les entrées, le responsable de chaque étape ainsi que les critères d’achèvement avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Documentez conjointement le parcours normal et les scénarios de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

6. Les échecs récurrents deviennent des fonctionnalités intégrées

Pour les 6 échecs récurrents qui atteignent une étape donnée, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Authentifiez au niveau du gateway et réautorisez au niveau du plan de données. Un simple token porteur ne constitue pas une frontière entre les tenants. Pour les 6 échecs récurrents qui atteignent une étape donnée, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés.

Guide pas à pas : de l’idée à la production en utilisant cette compétence

Lors de l’étape du guide pas à pas, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les flags fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, le débogage des boucles d’agent prend des heures inutilement.

Phase 1 : Cartographier (poser les bonnes questions)

Lors de l’élaboration de la carte de la Phase 1, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours idéal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie du produit, et non d’une mise en forme ultérieure. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, les boucles d’agent de débogage gaspillent des heures.

Phase 2 : Identifier (choisir le niveau MVP)

Lors de la phase 2 « Identifier et choisir », notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, les boucles de débogage perdent des heures. Lors de la phase 2 « Identifier et choisir », notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Notez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des factures inattendues lorsque le processus passe de la démonstration aux environnements partagés.

Phase 3 : Plan directeur (générer la conception du harnais)

La phase de génération du plan directeur de la Phase 3 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Conservez les configurations en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du schéma. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant de valider automatiquement.

Phase 4 : Mise en œuvre (respecter strictement le plan directeur)

La mise en œuvre de la Phase 4, qui se base strictement sur des étapes définies, fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez en même temps le parcours optimal et celui de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Fournissez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état du système avant de valider automatiquement.

Phase 5 : Lancement (audit avant mise en production)

La phase d’audit du lancement de la Phase 5 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et une note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité et non vers un processus embrouillé. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement. La phase d’audit du lancement de la Phase 5 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et une note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés.

Cas concret : Agent d’analyse des risques contractuels

Pour le cas du monde réel en phase de contrat, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans avoir à lire l’ensemble du système. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

Cas : Audit d’un agent de recherche existant

Pour l’audit d’un cas existant, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez conjointement le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Authentifiez au niveau du gateway et réautorisez au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

Conseils pratiques de mise en œuvre (avec pseudocode)

Pour les conseils de mise en œuvre pratique liés aux étapes, définissez les entrées, le responsable de chaque étape ainsi que les critères d’arrêt avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Authentifiez à l’entrée du système et réautorisez au niveau du plan de données. Un jeton porteur seul ne constitue pas une frontière entre les tenants.

Le cycle agentiel canonique (simplifié)

Pour la phase du cycle d’agent canonique, définissez les entrées, le responsable de l’étape et les critères de sortie avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définissez des vérifications de succès et refusez toute exécution partielle silencieuse. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

budgets = Budgets(step=25, time=120, tokens=8000, cost=0.50)
context = build_initial_context()
permissions = load_permission_matrix()while not budgets.exhausted():
    response = model.generate(context, tools=typed_tool_schemas)
    if response.finish_reason == "stop":
        break
    if response.tool_calls:
        for tool_call in response.tool_calls:
            if not permissions.is_allowed(tool_call):
                observation = "Permission denied: " + tool_call.name
            else:
                # Execute with risk‑appropriate checks
                if permissions.risk(tool_call) == "external_write":
                    approval = request_human_approval(tool_call.draft)
                    if not approval:
                        observation = "Human rejected: " + tool_call.name
                    else:
                        observation = execute_tool(tool_call)
                else:
                    observation = execute_tool(tool_call)
            context.append(observation)
        # Optional compaction trigger
        if context.token_count() > budgets.token_per_turn:
            context = compact_context(context, preserve_approvals=True)
    else:
        # No tool calls, just final answer
        break

Outils : du mauvais au bon

Pour les outils, de la phase de développement à celle de production, il convient de définir les entrées, le responsable de chaque étape ainsi que les critères d’achèvement avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des jetons ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts permet d’éviter des factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple jeton porteur ne constitue pas une frontière entre les tenants.

Stratification du contexte pour une efficacité du cache

Pour la superposition des couches de contexte dans l’étape de cache, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les stocks de secrets et les flags fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans avoir à lire l’ensemble du schéma. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

Layer 0: System policies (stable prefix) → Cached
Layer 1: Agent skill definitions (rarely change) → Cached
Layer 2: User session instructions (per conversation) → Not cached
Layer 3: JIT‑retrieved tool outputs (fresh) → Not cached

Déployer votre agent Harness : pourquoi l’infrastructure est importante

Pour l’étape « Déployer votre agent Harness », définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une amélioration ultérieure. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

C’est là que Aeza intervient.

Dans cette étape Aeza, il convient de définir les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Préférer des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Authentifier au niveau du gateway et réautoriser au niveau du plan de données. Un simple token porteur ne constitue pas une frontière entre les tenants. Dans cette étape Aeza, il convient de définir les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Enregistrer les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts permet d’éviter des factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés.

Pourquoi choisir Aeza pour les charges de travail de vos agents ?

Lorsque vous analysez pourquoi Aeza convient à votre étape, notez d’abord le contrat : les données requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Enregistrez le nom outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, le débogage des boucles d’agents prend des heures inutilement.

Sécurité, observabilité et évaluations (Ne passez pas à côté de cela)

Lors de la phase d’Observabilité et d’évaluation de la sécurité, notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures.

Conclusion et prochaines étapes

Votre plan d’action immédiat

npx skills add DenisSergeevitch/agents-best-practices -g

git clone https://github.com/DenisSergeevitch/agents-best-practices.git ~/.codex/skills/

Liste de contrôle opérationnelle