ハーネスの爆発後に学んだ 5 つのエンジニアリングの教訓

1. この問題に最初に遭遇したのは、実際のどのシナリオでしたか?

これは、複数ステップのエージェント ワークフローの単体テストを作成しているときに発生しました。エージェントは MCP ツールを順番に呼び出し、コンテキストを読み取り、条件付きジャンプを行う必要があります。従来の pytest モックは、各ツール呼び出しを固定の戻り値に置き換えますが、テストは常に成功しますが、オンラインになった後に頻繁にタイムアウトします。 2 日間ぐずぐずした後、問題はモックが実際のツールの遅延とエラー応答をシミュレートしていないことであることがわかりました。ハーネスは「テスト環境と本番環境の違い」を解決するために使用されるツールです。

ハーネス (テスト ハーネス) は本質的に、エージェントの入力と出力を引き継ぐ軽量の実行フレームワークであり、モック データの挿入、エラーのシミュレート、隔離された環境での動作の記録を可能にします。しかし、そのときに私が最初に陥った落とし穴は、ハーネスを通常のモックとして使用し、戻り値のみを置き換えて、タイムアウト、リトライ、例外フローを完全に無視していたことでした。

＃＃２ これを実行してから私の判断の仕方を大きく変えたいくつかの結論。

ハーネスを使用してテストを安定させることに成功した後、次の 3 つの重要な結論に達しました。

• ハーネスは万能接着剤ではありません。外部依存関係のシミュレーションには優れていますが、コード ロジック自体を置き換えることはできません。エージェントの意思決定ロジックにバグがある場合、利用することでバグがより早く露呈するだけです。これは良いことですが、多くのチームは、利用することで脆弱なコードがテストに合格できると誤解しています。
• ハーネスの価値は「制御可能な不確実性」にあります。エージェントの動作は、多くの場合、LLM のランダム出力に依存します。ハーネスはプロンプトとツールの出力を修正し、各テスト動作を再現可能にします。これは、コンテキストのアセンブリ プロセスもキャプチャするため、単に LLM エンドポイントをモックするよりも徹底的です。
• 学習曲線はあなたが思っているよりも急です。ハーネスには多くの設定項目 (タイムアウト、再試行、エラー挿入、ロギング) があり、設定段階で新しいバグが発生しやすくなります。最初は最初のハーネスを実行するのに 3 日かかり、実際のテストを書くのにわずか 1 日かかりました。

＃＃３ その時に遭遇した落とし穴とその後の修正方法

最大の落とし穴は過剰なハーネスです。当時、私は定数バージョンを返すだけの静的関数を含め、すべての外部呼び出しをハーネスに詰め込みたいと考えていました。その結果、ハーネス オブジェクトが肥大化し、テストごとに不要なモッ​​クが大量に読み込まれます。修正は簡単です。ハーネス内の真に外部の不安定な依存関係 (LLM 呼び出し、サードパーティ API、ファイル システムなど) のみを管理し、純粋な計算ロジックは通常の単体テストでカバーします。

2 番目の落とし穴は、ハーネスのライフサイクルを無視していることです。通常、ハーネスにはセットアップ フェーズとティアダウン フェーズがあり、最初にテスト間のコンテキストのクリーンアップに失敗したため、複数のテストが同じモック状態を共有し、下流のテストが上流の副作用によって汚染されてしまいました。その後、各テストの前後に明示的にreset()を呼び出すことで解決されました。

3 番目の落とし穴は、不完全なエラー シミュレーションです。通常のリターンとタイムアウトのみをシミュレートしましたが、いくつかのエラー (認証の失敗、レート制限など) は見逃していました。その結果、エージェントはオンラインになった後に 429 エラーが発生し、ハーネス テストではこの状況がカバーされませんでした。教訓は、ハーネスでエラーをシミュレートするときは、タイムアウト、HTTP 4xx/5xx、ネットワーク停止という 3 つの一般的な例外を少なくともカバーすることです。

4. 同様の作業を行っている場合、最初にコピーする最も価値のあるステップ

最も直接的な開始アクション: ハーネスを使用して、エージェント内の最も重要な外部呼び出し (唯一の LLM API など) 用の「テンプレート ハーネス」 を作成します。具体的な操作は次のとおりです。

1. 現在のプロジェクトのコアの不安定な依存関係 (通常は LLM またはデータベース) を選択します。
2. セットアップ (モック サーバーの初期化)、実行 (エージェントの呼び出しと出力のキャプチャ)、および破棄 (モックのクリーニング) を含むハーネス クラスを作成します。
3. ハーネス内の呼び出しの応答を修正し (たとえば、固定された JSON を返す)、実際に呼び出されたプロンプトとパラメーターを記録します。
4. テストを実行して、出力が期待どおりであることを確認します。

この手順により、最初の再利用可能なハーネス テストを 30 分以内に実行でき、プロンプトが正しく接続されているかどうか、およびパラメーターが正しく渡されているかどうかをすぐに確認できます。私の経験では、プロンプト エラーの 90% は、ハーネスを 1 回実行するだけで明らかになります。

＃＃５ いつ投資を続けるべきか、いつ路線を変更すべきでしょうか？

ハーネス シナリオへの投資を継続します。

• エージェントには 3 つ以上の外部依存関係があります。
• 新しい機能を開発しており、新しいコードが既存の動作を壊さないようにする必要があります。
• チームは常に新しいエージェントや新しいツールを追加しています。

ルートを変更する時期が来たことを知らせます。

• ビジネス テストを作成する代わりに、ハーネス構成自体のデバッグに 2 日以上を費やしました。
• 外部依存関係が頻繁に変更されるため、ハーネスのメンテナンス作業がテストの利点を上回ります。
• プロジェクトはまだプロトタイプ段階にあり、API とプロセスは日々変更されています。

このような場合は、まずは軽いモックで支え、安定性が向上してからハーネスを導入してください。

最後に書きます

ハーネスは特効薬ではありませんが、適切な場所で使用すると、エージェント プロジェクトのテストの信頼性を大幅に向上させることができます。重要なのは、適用可能な境界を明確にすることです。つまり、非決定性を制御し、実際の障害をシミュレートし、外部依存関係を分離します。この 5 つのレッスンが、回り道を避けるのに役立つことを願っています。