optimize-agent-prompt

エージェントのプロンプトを最適化する

タスク、結果スキーマ、変数、評価基準を固定したまま、Browserbase Agent の systemPrompt を最適化します。外側のエージェントを教師、各 Browserbase Agent の実行を内側のエージェントのロールアウトとして扱います。

Node.js 18 以降を使用し、BROWSERBASE_API_KEY を設定してください。ハーネスで使用するのは Node.js の組み込みモジュールのみです。

実験を設定する

短い実験名を選び、デモまたは POC のリポジトリ内に独立したワークスペースを作成します。

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

生成されたファイルを編集します。

• task.json：反復を重ねても、task、resultSchema、変数、ブラウザー設定、評価オラクルを一定に保ちます。
• prompts/iteration-001.md：最小限のベースラインとなるシステムプロンプトを記述します。該当する場合は、取り消せない操作に対するガードレールを含めます。

具体的な成功基準を設定してください。必須フィールドを指定し、取得できない事実には null を使う厳格な JSON Schema を推奨します。真実のオラクルがある場合は、evaluation の下に既知のフィールド用正規表現と、事実性に関する警告用正規表現を追加します。タスクまたはスコアを設計する際は、references/evaluation.md を読んでください。

ベースラインを実行する

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

ハーネスは再利用可能な Browserbase Agent を 1 つ作成し、以降の反復ではその systemPrompt を更新して、実行を開始し、メッセージとステータスをポーリングし、次のファイルを書き込みます。

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

ハーネスは、成果につながらない悪循環にコストをかけ続けないよう、設定したメッセージ予算に達した時点で実行を停止します。--max-messages、--timeout-ms、--proxies、または --verified は、タスクで task.json と異なる値が必要な場合にのみ使用してください。

観察可能な証拠から原因を診断する

まず、簡潔な軌跡を確認します。

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

次に summary.json を読み、誤りまたは無駄が最初に発生したターンを messages.json で詳しく調べます。エージェントのメッセージには、順序付けられたツール呼び出し、ツールの結果、エラー、最終出力が記録されます。reasoning パートには、読み取れるテキストが含まれていない場合があります。教師ループで、非公開の思考連鎖を必要としてはいけません。

ブラウザレベルの証拠によって原因を特定できる場合に限り、session-logs.json を確認します。たとえば、リダイレクト、403、リクエストの失敗、コンソールエラー、非表示のエンドポイントなどです。セッションログが空の場合、エージェントが検索／取得ツールで処理を完了し、ブラウザーを操作しなかったことを意味する場合があります。

エンドポイントの形式、ページネーション、結果の正規化、トレースに関する注意点については、references/api.md を参照してください。

ヒューリスティックを 1 つ改善する

結果に大きく影響した最初の失敗を見つけ、次の反実仮想を 1 つ述べます。

システムプロンプトで X を指示していれば、エージェントは Y を回避できていたはずです。その根拠はツールの結果 Z です。

現在のプロンプトを prompts/iteration-NNN.md にコピーし、変更は原因を特定できるもの 1 つにとどめます。改善例は次のとおりです。

• 同じブロックまたは同一のエラーが繰り返された後の再試行を制限する。
• 公開識別子と非公開／内部 ID を区別する。
• 操作が不要な場合は、ブラウザーを起動する前に検索／取得を優先する。
• 現在のスナップショットと日付のある過去の出来事を分ける。
• 条件付きの代替手段を完了とみなす条件を定義する。
• 値を推測せず null にするよう求める。
• ツール呼び出しまたは証拠に予算を設ける。

効果のあった変更は維持します。新しい実行で性能が低下した場合は、ルールをさらに積み重ねるのではなく、以前のプロンプトに戻し、別の仮説を試してください。

評価して収束させる

実行のたびに比較表を生成します。

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

フィールドの完全性だけでなく、次の点も評価してください。

• 終了ステータスが COMPLETED であること。
• 必須フィールドに値が入力されているか、明示的に null 許容となっていること。
• 利用可能な場合、既知の事実のチェックに合格していること。
• 事実性に関する警告に該当しないこと。
• 出典情報と安全性の制約が維持されていること。
• 品質を損なわずにメッセージ数または所要時間が減っていること。

プロンプトの成果が確認できたら、新しいラベルを付け、変更せずにもう一度実行します。直近 3 回のうち少なくとも 2 回に合格し、そのうち 1 回が変更なしの確認実行となった場合にのみ、収束したと判断してください。1 つのタスクだけを根拠に、プロンプトが全般的に最適だと述べてはいけません。テストしたタスク分布に対する最良のプロンプトとして説明してください。

デモへ進む

確認済みのプロンプトを、エージェントの本番用 systemPrompt として使用します。厳格な結果スキーマと実行ごとの変数を維持します。各指示が存在する理由をレビュアーが監査できるよう、実験用ワークスペースまたはそのレポートを保存します。

最終的な引き継ぎでは、次の内容を報告します。

• ベースラインと最高スコアのスコア、所要時間、メッセージ数；
• 各プロンプト変更で修正された最初の誤った判断；
• セッションログによって新たな証拠が得られたかどうか；
• 採用プロンプトのパス；
• 確認実行の結果；
• 制限事項と次のホールドアウトマトリックス。