Optimiser le Prompt d'un Agent

Optimise le systemPrompt d'un Agent Browserbase tout en gardant sa tâche, son schéma de résultat, ses variables et ses critères d'évaluation fixes. Traite l'agent externe comme l'enseignant et chaque exécution d'Agent Browserbase comme un déroulement d'agent interne.

Utilise Node.js 18 ou ultérieur et définis BROWSERBASE_API_KEY. Le harness n'utilise que des modules Node.js intégrés.

Configurer l'expérience

Choisis un nom d'expérience court et crée un espace de travail isolé dans le dépôt demo ou POC :

node <skill-dir>/scripts/optimize_agent_prompt.mjs init \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --name <experiment-name>

Édite les fichiers générés :

task.json : conserve task, resultSchema, les variables, les paramètres du navigateur et l'oracle d'évaluation stables d'une itération à l'autre.
prompts/iteration-001.md : écris le prompt système de base minimal. Inclus les garde-fous contre les actions irréversibles le cas échéant.

Utilise des critères de succès concrets. Préfère un schéma JSON strict avec des champs obligatoires et null pour les faits indisponibles. Ajoute des regex de champs connus et des regex d'avertissement de factualité sous evaluation quand un oracle de vérité existe. Lis references/evaluation.md lors de la conception de la tâche ou du score.

Exécuter la base de référence

node <skill-dir>/scripts/optimize_agent_prompt.mjs run \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --prompt prompts/iteration-001.md \
  --label iteration-001

Le harness crée un Agent Browserbase réutilisable, met à jour son systemPrompt lors des itérations ultérieures, démarre l'exécution, interroge les messages et le statut, et écrit :

runs/<label>/
├── system-prompt.md
├── created-run.json
├── run.json
├── messages.json
├── session-logs.json
└── summary.json

Il arrête une exécution après le budget de messages configuré au lieu de payer pour une spirale improductive. Utilise --max-messages, --timeout-ms, --proxies ou --verified uniquement quand la tâche nécessite des valeurs différentes de task.json.

Diagnostiquer à partir des preuves observables

Commence par la trajectoire compacte :

node <skill-dir>/scripts/optimize_agent_prompt.mjs inspect \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --label iteration-001

Puis lis summary.json et approfondis messages.json au premier tour incorrect ou mal utilisé. Les messages d'Agent exposent les appels d'outils ordonnés, les résultats d'outils, les erreurs et la sortie finale. Une partie reasoning peut ne contenir aucun texte lisible ; ne nécessite jamais une chaîne de raisonnement cachée pour la boucle d'enseignant.

Lis session-logs.json seulement quand les preuves au niveau du navigateur peuvent distinguer la cause — par exemple une redirection, un 403, une requête échouée, une erreur console ou un endpoint caché. Des logs de session vides peuvent signifier que l'Agent s'est terminé avec des outils search/fetch et n'a jamais piloté son navigateur.

Voir references/api.md pour les formes d'endpoints, la pagination, la normalisation des résultats et les avertissements de trace.

Améliorer une heuristique

Trouve la première défaillance conséquente et énonce un contrefactuel :

Si le prompt système avait instruit X, l'Agent aurait évité Y, comme le montre le résultat d'outil Z.

Copie le prompt actuel vers prompts/iteration-NNN.md et fais un changement attribuable. Les améliorations typiques sont :

limiter les tentatives après un bloc répété ou une erreur identique ;
distinguer les identifiants publics des ID privés/internes ;
préférer search/fetch avant de lancer un navigateur quand l'interaction est inutile ;
séparer les snapshots actuels des événements historiques datés ;
définir quand un fallback qualifié compte comme terminé ;
exiger null au lieu de valeurs devinées ;
ajouter un budget d'appel d'outil ou de preuve.

Conserve les victoires. Si la nouvelle exécution régresse, restaure le prompt précédent et teste une hypothèse différente au lieu d'accumuler d'autres règles.

Juger et converger

Génère la table de comparaison après chaque exécution :

node <skill-dir>/scripts/optimize_agent_prompt.mjs report \
  --workspace ./agent-prompt-optimization/<experiment-name>

Juge au-delà de la complétude des champs. Exige :

statut terminal COMPLETED ;
champs obligatoires remplis ou explicitement nullables ;
vérifications de faits connus passant quand disponibles ;
aucune correspondance d'avertissement de factualité ;
contraintes de provenance et de sécurité préservées ;
moins de messages ou durée inférieure sans perte de qualité.

Une fois qu'un prompt gagne, exécute-le à nouveau inchangé avec un nouveau label. Converge seulement après qu'il passe au moins deux des trois dernières exécutions et qu'un passage soit une confirmation inchangée. N'appelle pas un prompt globalement optimal à partir d'une seule tâche ; décris-le comme le meilleur prompt pour la distribution de tâche testée.

Passer à la démo

Utilise le prompt confirmé comme systemPrompt de production de l'Agent. Conserve le schéma de résultat strict et les variables par exécution. Préserve l'espace de travail d'expérience ou son rapport pour que les relecteurs puissent auditer pourquoi chaque instruction existe.

Dans la remise finale, rapporte :

score de base versus score gagnant, durée et nombre de messages ;
le premier tour incorrect que chaque changement de prompt a corrigé ;
si les logs de session ont ajouté une preuve ;
le chemin du prompt gagnant ;
les résultats de la confirmation ;
les limitations et la prochaine matrice de points faibles.

optimize-agent-prompt