Ingénierie d'Eval

Construisez les evals de manière itérative :

inspectez l'agent et interviewez l'utilisateur -> proposez des directions -> l'utilisateur choisit
-> approuvez le runtime et l'environnement -> construisez, exécutez, auditez -> examinez et répétez

Utilisez la dernière version de Harbor. Placez la source de la tâche sous evals/. Lisez references/harbor.md avant de créer ou d'exécuter une tâche.

1. Cartographiez l'agent

Inspectez l'agent actif et le code accessible à partir de son point d'entrée public. Trouvez :

runtime : point d'entrée, entrées/sorties, prompts, modèles, routage, retries, hooks, middleware et mémoire ;
actions : outils, entrées, sorties, défaillances, dépendances externes et effets ;
données de support : documents, enregistrements, index, fichiers, politiques, schémas, source et version si disponibles ;
état : identité, permissions, système de fichiers, réseau, temps, sessions et état mutable ;
objectif : utilisateurs prévus, jobs et ce qu'un bon résultat fournit ;
preuves : tests, fixtures, issues, evals existantes et défaillances documentées.

La cartographie est en lecture seule. Ne démarrez pas la cible ou les services, n'installez pas de packages ou n'utilisez pas de credentials externes avant que l'utilisateur n'approuve le runtime et l'environnement.

Résumez la carte dans la conversation :

Agent : cible et point d'entrée
Objectif : utilisateurs et jobs
Capacités : travail qu'il est censé accomplir
Outils et données : actions, données de support et dépendances
Effets : lectures, écritures et changements d'état
Preuves : tests, défaillances ou traces

Utilisez du code pour modéliser l'agent ; ne transformez pas les détails d'implémentation en question d'eval sauf si répondre à des questions sur ce code est le job de l'agent.

Impliquez l'utilisateur : expliquez la carte et ce qu'elle implique en langage clair, puis posez uniquement des questions que le repository et les traces ne peuvent pas établir. Par exemple : « Quel job utilisateur est le plus important ? », « Quelle défaillance ne doit jamais se produire ? », ou « À quoi ressemblerait un bon résultat ? »

Traces optionnelles

Utilisez les traces uniquement quand l'utilisateur fournit une source ou demande de les utiliser. Lisez references/trace-sourcing.md. Utilisez les traces sélectionnées pour identifier les requêtes réelles et le comportement de dépendance, et ne traitez jamais une réponse cible enregistrée comme la vérité.

2. Discutez et choisissez une direction d'eval

Proposez deux ou trois capacités fondées sur la carte. Pour chacune, donnez :

Nom
Exemple de requête : requête réaliste envoyée à l'agent
Tests : comportement que l'eval distingue
Besoins : principal obstacle, données ou exigence d'environnement

Exemple :

Nom : choisir la bonne recherche de compte
Exemple de requête : « Quel plan le compte A a-t-il ? »
Tests : récupère le compte A, utilise le plan retourné, et n'invente pas de détails de compte
Besoins : une recherche de compte en lecture seule avec des enregistrements connus

Recommandez une et demandez à l'utilisateur laquelle construire. La requête doit faire exercer à l'agent la capacité : utilisez plusieurs tours pour l'utilisation du contexte, des outils concurrents pour le choix d'outil, du matériel source pour la récupération, ou un état connu pour une action.

N'implémentez pas avant que l'utilisateur choisisse.

3. Point de contrôle : approuvez le runtime et l'environnement

Lisez references/task-design.md et references/environment-building.md. Concevez un scénario qui requiert la capacité sélectionnée.

Recommandez un runtime cible :

Point d'entrée actif : préservez le comportement de l'agent du repository. Recommandez ceci quand il peut s'exécuter en toute sécurité.
Reconstruction : utilisez uniquement quand le point d'entrée actif ne peut pas s'exécuter dans une eval contrôlée. Nommez le comportement qu'il ne peut pas préserver et étiquetez l'eval comme une reconstruction.

Avant l'implémentation, donnez à l'utilisateur une proposition sous 150 mots :

Tâche : requête et capacité
Runtime : point d'entrée actif ou reconstruction, avec tradeoff
Dépendances et données de support : live, frozen ou simulated ; credentials requises si live, effets et source/version
Succès : comment le résultat est jugé
Recommandation : configuration préférée et pourquoi

L'utilisateur approuve ou révise la limite du runtime et de l'environnement cible. Ne n'écrivez jamais en production ; isolez les mutations.

4. Construisez une tâche Harbor

Créez une tâche pour la capacité sélectionnée :

evals/<task-id>/
├── task.toml
├── instruction.md
├── environment/
└── tests/

Ajoutez un adaptateur ou une configuration non-défaut uniquement quand Harbor a besoin pour invoquer le runtime cible approuvé. Gardez les instructions et les faits d'environnement visibles à la cible ; gardez les résultats attendus, critères de jugement et credentials de jugement indisponibles pour elle.

Un adaptateur peut traduire les E/S et injecter des dépendances approuvées. Il ne doit pas prendre de décisions cibles, contenir de réponses ou fabriquer des actions. Les adaptateurs et verifiers personnalisés doivent écrire le dossier réponse/action cible, preuve verifier, verdict/raison, reward et erreurs vers les artifacts Harbor ou logs verifier. N'ajoutez pas audit.json ou un autre ledger de résultats.

Utilisez un juge LLM pour le succès sémantique et des contrôles déterministes pour l'exécution, le parsing, les fichiers ou l'état. Lisez references/verifier-design.md. Émettez une reward primaire.

5. Testez, exécutez et auditez

Démarrez l'environnement minimum avant de compléter le scénario. Testez le verifier directement avec un résultat clairement valide qui passe et un résultat réaliste incorrect qui échoue.

Exécutez le runtime cible approuvé via Harbor. Inspectez :

réponse et trajectoire cibles ;
appels d'outils observés par le harness, actions et état ;
preuves verifier, verdict, raison, reward et erreurs ;
configuration cible et environnement résolues.

Corrigez et réexécutez quand la tâche est peu claire, l'environnement est irréaliste, le verifier est faux ou l'infrastructure a échoué. Avant l'approbation, confirmez que la cible a exercé la capacité sélectionnée et le verifier a noté ce comportement, pas une défaillance d'environnement ou verifier. Si l'environnement a retourné la réponse avant que la cible n'utilise l'outil prévu, révisez la tâche.

6. Examinez avec l'utilisateur

Expliquez le chemin de la tâche et la commande run, la capacité et le scénario, la limite de dépendance et runtime, le comportement cible, la décision verifier et la limitation. Demandez à l'utilisateur d'approuver, réviser, abandonner ou choisir la direction suivante. Si vous continuez, réutilisez la carte et les découvertes de trace, puis proposez une capacité distincte.

Invariants

Une capacité par tâche Harbor sous evals/.
Pas d'écritures en production ; réinitialisez l'état mutable entre les essais.
Gardez la vérité cachée et les credentials de jugement indisponibles pour la cible.
Traitez les défaillances de build, credential, reset, timeout, judge et verifier comme des erreurs d'infrastructure.

eval-engineering