ハーネスエンジニアリングとは？AIエージェントの実行環境を設計する

ハーネスエンジニアリングとは、AIエージェントがタスクを反復して実行し、結果を検証し、途中で停止しても再開できるように、プロンプトの外側にある実行環境を設計する実務です。

指示文を改善するだけでは、エージェントが「どのツールを使えるか」「実行結果をどう確認するか」「失敗時に何を残して誰へ渡すか」は決まりません。そこで、作業空間、ツール、権限、状態、成果物、ログ、テスト、復旧経路をまとめて扱います。

本記事では、AIエージェントが安全・検証可能・再開可能に仕事を進めるための周辺機構を設計する活動を、ハーネスエンジニアリングと呼びます。OpenAIはエージェント中心の開発において、人の役割を「環境を設計し、意図を指定し、信頼できる作業のためのフィードバックループを作ること」と説明しています。OpenAI公式記事

ハーネスエンジニアリングとは

たとえば、エージェントへ「問い合わせを確認し、必要なら顧客台帳を更新する」と依頼する場面を考えます。モデルが依頼文を理解できても、次の条件が決まっていなければ、安全な実行にはつながりません。

• どの顧客台帳を参照・更新してよいか
• 入力形式が不正な場合、更新を中止するか
• 更新前後の値、実行時刻、根拠をどこへ残すか
• 失敗時に、再試行・保留・人への引き継ぎをどう分けるか
• 作業の完了を、どの証拠で判定するか

ハーネスは、モデルが見られる情報、可能な操作、検証方法、失敗時の扱いを定める枠組みです。モデルはその中で判断やツール実行を担います。

OpenAIが紹介するソフトウェア開発の事例では、エージェントが変更ごとにアプリを起動・操作できるようにし、DOMスナップショット、スクリーンショット、画面遷移を扱う機能を実行環境に組み込んでいます。実装する手段だけでなく、実装結果を確かめる手段もハーネスの対象になります。OpenAI公式記事

プロンプト・コンテキスト設計との違い

これらは対立する概念ではありません。プロンプトとコンテキストは、ハーネスの構成要素になり得ます。ただし、プロンプトが「何をしてほしいか」、コンテキストが「何を読ませるか」に重心を置くのに対し、ハーネスは何を実行でき、何を残し、どう確かめ、どう再開するかまでを対象にします。

モデルへ渡す情報の選択・構成・更新を詳しく確認したい場合は、コンテキストエンジニアリングとは｜プロンプトエンジニアリングとの違いと実務での設計対象を参照してください。

エージェントを支える実行環境の構成

以下は本記事の提案です。ハーネスを6つの設計対象に分けると、実装前に不足を確認しやすくなります。

1. 作業空間：対象ファイル、データ、実行環境を分ける単位です。他の案件や実行と混ざらない範囲を定めます。
2. ツールと権限：検索、読取、更新、送信、実行などの操作ごとに、許可範囲と承認の要否を定めます。
3. 状態と成果物：現在地、変更内容、未解決事項、完了条件を、次の実行者が読める外部状態として残します。
4. 観測記録：ツール呼び出し、入力、出力、失敗理由、処理時間、参照元を追跡できるようにします。
5. 評価と品質ゲート：テスト、照合、レビュー、受け入れ条件を用いて、次の操作へ進めるかを判断します。
6. 復旧とエスカレーション：再試行、差し戻し、保留、人への引き継ぎを区別します。

OpenAIの事例では、ログ、メトリクス、トレースを、作業用の環境ごとに用意した観測基盤からエージェントへ公開し、LogQLやPromQLで問い合わせ可能にしています。会話履歴に限らず、対象システムの観測可能性をエージェントが利用できる形にすることも、実行環境の設計対象です。OpenAI公式記事

ツールを使える状態にする契約と実行記録

ここでいうツール契約は、本記事で用いる設計上の呼び方です。MCPやAPI仕様など、特定の標準規格の名称ではありません。エージェントがツールを使う前提として、少なくとも次を明文化します。

• 入力：必須項目、型、許容値、対象IDの取得元
• 出力：成功・失敗・保留を区別できる形式
• 副作用：読取のみか、更新・送信・削除を伴うか
• 権限：対象範囲、実行可能な操作、人の承認が必要な操作
• 再実行時の扱い：同じ要求で重複登録・重複送信が起きないか
• 監査：誰が、何を根拠に、いつ実行し、何が変わったか

自然言語の注意書きだけでは、ルール違反を検出しにくい場合があります。OpenAIの事例では、依存方向、構造、ログ形式、命名などの不変条件をカスタムリンターや構造テストで機械的に検証しています。OpenAI公式記事

実装手段の一例として、OpenAI Agents SDKは、指示とツールを備えたエージェント、入出力を確認するガードレール、トレーシング、隔離ワークスペースで動くサンドボックスエージェント、再開可能なサンドボックスセッションを案内しています。ただし、SDKの採用自体がハーネス設計ではありません。どの機能をアプリケーション側、実行基盤側、人の運用側で担保するかを決めることが設計の中心です。OpenAI Agents SDK公式ドキュメント

影響の大きい外部操作では、ツールを渡すだけで自動実行させず、人の承認や権限分離を組み合わせる判断が必要です。委任範囲・承認・停止条件は、AIエージェントはどこまで任せるべきか｜委任範囲・人の承認・停止条件を設計する実務ガイドで解説しています。

長い作業を引き継ぐための状態と成果物

長い作業では、新しいセッションが前の会話や作業内容を持たずに始まる場合があります。Anthropicは、長時間動くエージェントではセッションが離散的であり、新しいセッションが前の記憶を持たないことを中心課題として説明しています。Anthropic公式記事

Anthropicのコーディング環境での実験では、最初に初期化用エージェントがinit.sh、進捗ファイル、初期Gitコミットを作り、その後のコーディングエージェントが段階的な変更と構造化された更新を残します。進捗ファイルとGit履歴を組み合わせることで、新しいセッションが作業状態を把握する構成です。Anthropic公式記事

ただし、進捗ファイルやGitコミットはコーディング環境の具体例です。文書作成、顧客対応、データ更新などへ同じ形式を適用して同じ効果が得られるとは限りません。業務が異なっても、次の情報を引き継げるかを要件にします。

• 現在地：どの作業単位を処理中か
• 検証済みの事実：どの確認を通過したか
• 未完了・保留：何が不足し、なぜ止まったか
• 次の一手：次回に実行すべき具体的な操作
• 復旧点：戻せる版、取り消し方法、再実行に必要な識別子

架空の例：コード修正エージェントの実行ハーネス

以下は架空の例です。Webアプリで「保存後に一覧へ反映されない」不具合を修正するエージェントを想定します。

この例では、「修正して」と指示するだけでは足りません。再現、実装、エンドツーエンド確認、記録、保留という経路を用意することで、成果を確認できるようにします。Anthropicも、Webアプリ構築の実験において、ブラウザ自動化を用いたエンドツーエンドテストを明示すると、コードだけでは明らかでない不具合を特定・修正でき、性能が大きく改善したと報告しています。これは同実験条件での知見であり、すべての業務に同じ検証手段が適することを示すものではありません。Anthropic公式記事

ハーネスの設計シートと確認項目

以下はMojiによる設計提案です。モデル、業務の影響範囲、入力品質、評価方法、許容できない失敗に応じて記入内容と合否基準を調整してください。

【ハーネス設計シート】
1. 目的・完了条件
- エージェントが達成する成果：
- 完了を確認する証拠：
- 完了扱いにしない条件：

2. 作業空間・データ
- 読取対象：
- 書込対象：
- 分離単位（案件／顧客／ブランチ等）：
- 保持してよい状態・期限：

3. ツール契約
- ツール名と目的：
- 入力・出力の形式：
- 副作用：
- 再実行時の扱い：
- 必要権限・人の承認：

4. 観測・評価
- 記録するイベント：
- テスト・照合方法：
- 人が確認する箇所：

5. 引き継ぎ・復旧
- 現在地を残す成果物：
- 次回の開始手順：
- 保留・差し戻し・エスカレーション条件：

導入前には、次の点を確認します。

• 完了条件が「モデルが完了と回答した」以外で定義されているか。
• ツールの入力・出力・副作用を、失敗も含めて区別できるか。
• 再実行時に重複更新・重複送信を避けられるか。
• 参照元、変更、検証結果、失敗理由を後から追跡できるか。
• 新しいセッションや担当者が、会話だけに頼らず現在地を把握できるか。
• 未検証の変更と、検証済みの成果物を分けられるか。
• 権限不足、要件不明、外部障害を保留や人への引き継ぎへ分けられるか。

まとめ

ハーネスエンジニアリングでは、エージェントが何を見て、何を実行し、結果をどう検証し、次回に何を残し、失敗時にどう戻るかを設計します。

最初は影響範囲を限定した一つのタスクで、①完了条件、②ツール契約、③実行記録、④検証、⑤保留・復旧の5点を用意してください。失敗を単にモデルの能力不足と扱うのではなく、足りないツール、情報、制約、評価を実行環境へ戻して見直すことで、次の実行を検証しやすくなります。