プロンプトを少し直すだけでは、本番のAIエージェントは安定しません。実行ログを残し、評価テストに変え、ハーネスを更新する一連のループが、実務で使われ始めています。

2026年7月3日、Jokker氏のX投稿が「エージェントループ・harness・evalsを20分で学べる」内容として拡散しました。投稿が指す実体は、OpenAIが公開したCookbook「Build an Agent Improvement Loop with Traces, Evals, and Codex」です。著者はOpenAIのWesley Pasfield氏で、2026年5月11日にopenai-cookbookへマージされています。

この記事では、公式Cookbookが示す改善ループの全体像と、各ステップで何が起きるかを整理します。

この記事でわかること

  • harness（ハーネス）が指す具体的な範囲
  • トレース→フィードバック→Evals→HALO→Codexの7ステップ
  • デフォルト設定で約20分かかる理由と必要環境
  • 人手レビューと自動化の切り替え方

プロンプト調整だけでは足りない理由

AIエージェントは、モデル本体に加えてプロンプト、ツール、ルーティング、出力形式、検証ロジックなどの「周辺契約」で動きます。Cookbookでは、この周辺契約全体をharness（ハーネス）と呼びます。指示文だけを書き換えても、ツールポリシーや検証器の穴は残ります。

OpenAIのTax AI事例でも、本番トレース（入力から最終出力までの実行履歴）と専門家フィードバックをEvalsに変換し、Codexがトレース・Evals・リポジトリをまとめて調査して修正する、という自己改善ループが紹介されています（参考）。プロンプト最適化は有効ですが、ハーネス全体を対象にしたループ設計が次の段階です。

OpenAI Cookbookが示す改善ループ

https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop

Cookbookは、OpenAI Agents SDKで動く買収デューデリジェンス（企業買収前の調査）アナリストを題材に、実行から改善案生成までを1本のノートブックで回します。デフォルトでは5回のトレース実行を前提に、フル実行に約20分を見込むと明記されています。時間の大半はStep 3のエージェント実行とStep 7のHALO分析にかかります。

ループの流れは次の7段階です。

  1. 合成データの準備 — 財務エクスポートや契約書など、矛盾を含む調査資料を生成する
  2. Agents SDKアナリストの定義 — システムプロンプト、モデル設定、ツールポリシー、Evalメタデータをharnessとして明示する
  3. トレース付き実行 — エージェントを5回走らせ、OpenTelemetry形式のJSONLに変換して保存する
  4. フィードバック収集 — 人間のレビューコメントとLLM生成の所見をトレースに紐づける
  5. Promptfoo Evalsの自動生成 — フィードバックを再利用可能なテストケースに変換する
  6. Promptfooゲート — 現行harnessの出力をEvalsで採点し、合格・不合格を記録する
  7. HALO分析とCodexハンドオフ — 失敗パターンを診断し、codex_handoff.mdに改善案を書き出す

各実行で得た知見が次のサイクルに引き継がれる設計です。トレースは「何が起きたか」、フィードバックは「何が重要だったか」、Evalsは「次回も満たすべき条件」、Codexは「コードとして何を直すか」を担います。

harness・Evals・HALOの役割

harnessは、Cookbookの定義どおり「モデルを囲む契約全体」です。プロンプト、ツール、ルーティング、出力要件、検証チェックがセットでharnessを構成します。HALOへの入力には、現在のharness設定が合成トレースとして渡され、改善対象が明示されます。

Evals（評価テスト）は、Promptfooで実行します。CookbookではLLMがトレースとフィードバックからEvalsを動的生成し、決定論的チェックとllm-rubric（LLMによる採点基準）を組み合わせます。生成したEvalsはリグレッション（退行）テストとしてリポジトリに残すことが推奨されています。実際の実行例では、ランウェイ計算・ARRソース・顧客集中度・SOC 2表記・未サポート指標の拒否など5件のEvalsが生成され、すべて合格したケースが示されています。

HALO（Hierarchical Agent Loop Optimization）は、context-labsが公開するトレース分析エンジンです。GitHub上では「RLM-based agent optimizer using production traces」と説明され、PyPIパッケージ halo-engine として提供されています（参考）。Cookbookでは5本のSDK実行トレースに加え、harness設定とPromptfooゲート結果の2本の合成トレースを渡し、合計7トレースを分析します。出力はランク付けされた改善提案と、Codex向けの実装ガイドを含む codex_handoff.md です。

Codexでharnessを更新する

Step 8以降、HALOのレポートをCodexなどのコーディングエージェントに渡し、harnessのコード変更を適用します。Cookbookの実行例では、上位3件の推奨として「デューデリジェンス用ファクト台帳の追加」「検証器を出力アーティファクトまで監査する強化」「生成Evalsのリポジトリへの永続化」が挙げられています。

自動化の度合いは開発者が選べます。初期はPRレビューを人手で行う「reviewed loop」が一般的で、Evalsゲートへの信頼が高まれば、ハンドオフ検知→Codex実装→デプロイまで自動化する構成も同じアーキテクチャで可能です。Cookbookは意図的にライブ実行のみの設計で、スクリプト化されたプレビューではなく実際のモデル呼び出しでループを体験させます。

実行に必要な環境

Cookbookの前提条件は次のとおりです。

  • Pythonパッケージ: openai, openai-agents, halo-engine
  • Node.js（Promptfooをnpxで実行するため）
  • 環境変数 OPENAI_API_KEY
  • オプションでモデル名を AGENT_MODEL, ANALYSIS_MODEL, EVAL_GENERATION_MODEL, JUDGE_MODEL, HALO_MODEL から個別指定可能

コストを抑える場合、各ステージのモデルを安価なものに差し替えることが推奨されています。Promptfooのバージョンはデフォルトで0.121.9です。

LangChainのBetter Harnessとの共通点

LangChainも「Better Harness」として、Evalsを学習信号にharnessを段階的に改善する手法を公開しています（参考）。トレースからEvalsを生成し、1変更ずつharnessを更新して過学習を避ける、という考え方はOpenAI Cookbookと同系統です。利用するSDKやEvals基盤は異なりますが、「トレース→Evals→harness更新」のループ設計自体が、エージェント開発の実務標準になりつつあります。

ループ設計を始めるときの着眼点

まず本番またはステージングでトレースを必ず残すことが出発点です。トレースがなければ、フィードバックもEvalsも根拠を失います。次に、人間の専門家コメントをEvalsに変換する工程を省略しないこと。Cookbookの例では、人間フィードバックが「ランウェイ11ヶ月」「ARRは財務管理ソースを正とする」といったドメイン固有の不変条件を最も強い証拠として扱っています。

最後に、生成Evalsを一度きりの採点に留めず、リグレッションスイートとしてリポジトリに組み込むことが重要です。Evalsゲートが信頼できるほど、Codexへの自動ハンドオフを安全に広げられます。X投稿が強調する「trace→eval→diagnose→fix→deploy→repeat」のサイクルは、OpenAI公式Cookbookが具体コードと手順で示している、現時点で最も参照しやすい実装例です。