AI エージェント向けのハーネス設計: その仕組みを説明する実際のリンク

実際のハーネスリンク: 実行してから出力します。

コードレビューエージェントを構築しているとします。その中心的なタスクは、LLM を使用して PR の差分を分析し、合格または不合格の結論を生成することです。文字通りエディターを開いて PR を作成し、テストするたびに GitHub Webhook を待つ必要はありません。ハーネスが必要です。

AI エージェント向けの Harness Design の中心的なアイデアは、エージェントの実行プロセスを外部の世界から隔離し、制御可能な入力とアサーションを使用してその動作を検証することです。このリンクは、モック入力→エージェント実行→アサーション出力の 3 つのステップに分かれています。

ステップ 1: 実際の外部呼び出しの代わりに入力を模擬する

最も一般的な間違いは、エージェントを実際の API に直接接続することです。ハーネスは、事前に外部応答を記録するか偽装することでこれを実現します。たとえば、コードレビューエージェントの場合、GitHub の PR データ、差分コンテンツ、さらには LLM の戻り値をモックする必要があります。

簡単な失敗: モックデータがきれいすぎる。実環境における PR コメントには @mention、空行、文字化けが含まれる場合があります。ハーネスが適切にフォーマットされたサンプルのみを使用している場合、エージェントは本番環境でさまざまな事故を起こすことになります。正しいアプローチは、通常の差分、多くのコメントを含む差分、およびいくつかのファイルが削除された差分という、少なくとも 3 つのバリエーションを含めることです。

ステップ 2: Harness でエージェントを実行し、完全なログを収集します

ターミナルで印刷出力をただ見るだけではありません。ハーネスは、エージェントの思考チェーンのすべてのステップ、すべてのツール呼び出し、および最終的な決定をキャプチャする必要があります。たとえば、エージェントは 2 つのツール analyze_diff と check_style を内部的に呼び出す可能性があり、ハーネスは各ツールの入力、出力、および消費時間を記録する必要があります。

実行可能なアプローチ: 構造化ログをエージェントコードに埋め込み、各ステップのコンテキストを JSON 形式で出力します。テスト時に、Harness は最終結果をアサートすることと、中間ステップが妥当かどうかをチェックすることの両方を行うことができます。たとえば、analyze_diff の戻り値に関数シグネチャの変更が含まれているかどうかをアサートします。

ステップ 3: 単なる「合格/不合格」ではなく出力をアサートする

エージェントの最終出力が合格か失敗かを単に表明するだけでは十分ではありません。ハーネスを使用すると、出力の構造、内容、さらにはトーンを検討できるようになります。たとえば、コードレビューエージェントの場合、次のようにアサートできます。

出力には approved: true/false フィールドが含まれている必要があります
差分にセキュリティ上の脆弱性がある場合、コメントには「脆弱性」という単語が含まれている必要があります。
差分にドキュメントのみが含まれる場合、エージェントはレビューをスキップする必要があります

簡単な失敗: アサーションが具体的に記述されすぎているため、ハーネスとエージェントの間に強い結合が生じます。エージェントの出力形式が調整されると、ハーネスは完全にダウンします。アサーションは、ハードコーディングされたフィールドパスの代わりにスキーマ (Pydantic や JSON スキーマなど) を使用して、インターフェイス層で定義することをお勧めします。

実際のシナリオ: GitHub PR からローカルハーネスまで

私の同僚の 1 人は Harness を使用してコードレビューエージェントをテストしました。彼は、エージェントの承認が真実であり、コメントに「LGTM」が表示されることを期待して、SQL インジェクションの修正を含む PR の差分を嘲笑しました。最初の実行では、エージェントは承認しましたが、出力は「良さそうです」となり、ケースのケースが一致しないためハーネスアサーションは失敗しました。彼は、エージェントが常に「LGTM」を使用することを要求するプロンプトを修正しました。

この小さな例は、Harness が機能の正しさを検証するだけでなく、動作の一貫性も検証できることを示しています。これらの境界がハーニーに設定されていない場合、エージェントはオンラインになった後、異なる表現でユーザーを混乱させる可能性があります。

モック化されたテスト実行がエディターに表示され、コードにはモックデータとアサーションロジックが含まれています。

簡単な失敗と誤解

誤解: Harness はテストフレームワークです。実際、Harness は単なるアサートツールというよりも、制御可能で反復可能なランタイム環境に近いものです。モック、ロギング、アサーション、さらにはエージェントのライフサイクルを管理します。
トラップ: モックデータにエッジケースが欠落しています。実際の LLM は非常に長いテキストまたは空のコンテンツを返す場合があり、モックするときにこれらの値を上書きする必要があります。
トラップ: タイミング依存関係の無視。一部のエージェントはステップ間の時間間隔に依存しており、ハーネスが加速されると動作が変化する可能性があります。必要に応じて、仮想クロックをハーネスに導入できます。

ハーネス設計でカバーされる境界条件をリストした QA チェックリストがラップトップに表示されます。

今すぐ着陸したい場合、最初のステップは何ですか?

単一ツール、単一タスクのエージェント (天気をクエリするエージェントなど) など、単純なエージェントを選択します。
Python を使用して、3 つのメソッド set_mock_response、run、assert_output を含む Harness クラスを作成します。
3 つの異なる実際のユーザークエリを記録し、対応する模擬入力を手動で構築します。
Harness を実行し、エージェントの出力が期待どおりであるかどうかを確認します。
意図的にエラーを導入し (たとえば、モックに必要なフィールドが欠落しているなど)、ハーネスがエラーをキャッチできるかどうかを観察します。

これらの 5 つの手順を完了すると、再利用可能なハーネスベースラインのセットが完成します。その後、アサーションの粒度を拡張したり、ログ収集を導入したりすることができます。

体系的な学習を続けるために次はどこに行くべきか

上記の手順をすでに実践している場合は、次に、Harness を CI/CD パイプラインに統合する方法、マルチエージェントコラボレーションシナリオ向けに Harness を設計する方法、Harness と可観測性ツール (Langfuse など) を組み合わせる方法を学習する必要があります。高品質のオリジナルの有料記事と AI の高度なプログラミングコースはこれらのコンテンツをカバーし、通常の開発者からエージェントエンジニアへ体系的に変身するのに役立ちます。

実際のハーネス リンク: 実行してから出力します。