AIエージェントのハーネス・ループ・グラフエンジニアリングを順に理解する ==================================== ハーネスはエージェントが働く環境と統制手段を、ループは反復と終了のルールを、グラフは許容する状態と遷移経路を設計する。3つの用語は、公認された標準分類というより、AIエージェントの自律性とリスクを扱うための実務的な観点として理解するのが正確だ。 - ハーネスエンジニアリングは、モデル外部のコンテキスト、ツール、権限、検証、ログ、承認手順を1つの実行環境として設計することである。 - ループエンジニアリングは、エージェントが計画・実行・検証・修正を反復する条件と予算、終了基準を定義する。 - グラフエンジニアリングは、状態と遷移ルールを用いて、エージェントが選択できる経路を明示的に制限または調整する。 - 多くの組織では、複雑なマルチエージェントグラフよりも、単一エージェントのハーネスと評価体系を先に改善する方が効率的である。 - AIが作成した要約レポートだけを承認する方式では、高リスクのコードには不十分であり、テスト、変更範囲、セキュリティ境界、元の成果物を併せて検証しなければならない。 AIエージェントが長期タスクを担い始めたことで、プロンプトをうまく書くだけでは安定した結果を得ることが難しくなった。エージェントがどの情報を参照し、どのツールを使い、いつ反復し、どの経路へ進み、どこで人の承認を得るべきかまで設計する必要があるためだ。 この問題を説明する際によく登場する表現が、ハーネスエンジニアリング、ループエンジニアリング、グラフエンジニアリングだ。これらは国際標準でも、厳密に合意された学術的分類でもない。互いに重複する部分があり、製品や開発チームによって意味も異なり得る。したがって、年ごとの流行語として覚えるより、それぞれが答えようとしている制御上の問いによって区別するほうが有用だ。 3つの概念を一目で比較する 概念 核心となる問い 主な設計対象 代表的な失敗防止策 ハーネスエンジニアリング エージェントはどのような環境とルールの中で働くのか？ コンテキスト、ツール、権限、サンドボックス、フック、ログ、承認、評価 最小権限、危険なコマンドの承認、テスト実行、コンテキストの選別 ループエンジニアリング 何を反復し、いつ停止するのか？ 計画・実行・検証のサイクル、イベント処理、再試行、予算、終了条件 最大反復回数、時間・トークン上限、進捗判定、失敗時の引き継ぎ グラフエンジニアリング どの状態と経路を許可するのか？ ノード、状態、遷移、分岐、並列処理、チェックポイント 禁止遷移、状態検証、承認ノード、復旧経路 簡潔に表現すると、ハーネスは環境と境界、ループは反復ルール、グラフは可能な経路の構造だ。実際のシステムでは、グラフの1つのノード内にループが入り、グラフ全体が1つのハーネス内で実行されることがある。 エージェントの制御方式はどのように変化してきたか 初期のエージェント：定められたワークフローが自律性を補完した 初期の生成AIエージェントは、長いタスクで目標を忘れたり、誤ったツール呼び出しを繰り返したり、根拠のない結果を生成したりすることが多かった。そこで開発者は、大きなタスクを小さな段階に分け、各段階の入力と出力を固定した。 この方式では、人が手順全体をチェーン、フローチャート、またはステートマシンとして記述し、LLMは分類、抽出、要約、下書き作成のような限定されたタスクを担当する。LangGraphのようなフレームワークは、状態を維持しながら分岐、循環、チェックポイント、人の介入を表現するために使われる。 ただし、グラフベースのオーケストレーションは、特定の年に終わった古い方式ではない。現在も、監査可能性、再現性、規制遵守、または正確な復旧手順が重要な業務では、明示的なグラフが適している。 モデル性能の向上：固定経路から動的なツール使用へ ツール使用と推論能力が改善されたことで、1つのエージェントが状況に応じて検索、コード編集、テスト、ファイル読み込みなどの行動を選択できるようになった。ReAct系のアプローチは、推論と行動、観察を交互に行う代表的な構造だ。 この変化により、人がすべての分岐を事前に記述しなければならない負担は減った。一方で、エージェントが読む情報、保有する権限、実行コスト、エラー復旧方式を管理する問題がさらに重要になった。ここで、コンテキストエンジニアリングとハーネスエンジニアリングが実務の中心に入ってくる。 長期タスクとマルチエージェント：ループとグラフの再結合 長期タスクでは、1回のモデル呼び出しより、反復的な計画・実行・検証が重要だ。複数のエージェントが参加する場合は、役割、成果物の形式、権限、終了条件も明示しなければならない。同時に、自律ループを完全に放置すると、コストの急増、無限の再試行、報酬ハッキング、誤った目標の最適化が発生し得る。 そのため、現代的なエージェントシステムは、自律性をなくすのではなく、自律性を許可する区間と決定論的に制御する区間を組み合わせる方向で設計される。これは過去の固定チェーンへの単純な回帰ではなく、柔軟な実行を状態・遷移・ポリシーで囲む方式だ。 こうした変化は、正確な年表というより、設計上の重点の変化だ。グラフ、ループ、ハーネスは当初から共存しており、現在も併用されている。 ハーネスエンジニアリングが扱うもの ハーネスは基盤モデルそのものではなく、モデルが実際の業務を遂行できるように周囲を取り囲む実行体系だ。同じモデルを使用しても、ハーネスによって成功率、コスト、セキュリティ、再現性が大きく異なり得る。 ハーネスの主な構成要素 指示体系：システム指示、リポジトリのルール、コーディング標準、優先順位と禁止行動 コンテキスト供給：検索、ファイル選択、要約、メモリ、必要なタイミングでの文書注入 ツールインターフェース：ファイル編集、ターミナル、ブラウザ、データベース、外部API 権限と隔離：読み取り・書き込み範囲、機密情報へのアクセス、ネットワーク制限、サンドボックス 検証手段：テスト、リンター、型チェック、スキーマ検証、ファクトチェック 人の承認：デプロイ、決済、削除、外部送信など、元に戻すことが難しい行動の承認 可観測性：呼び出し記録、コスト、遅延時間、エラー、変更履歴、判断根拠 復旧ポリシー：再試行、以前の状態への復元、タスクの中断、担当者への引き継ぎ Claude Codeのプロジェクト指示ファイルやフックは、ハーネスの構成要素の事例と見なせる。しかし、特定の製品機能1つがハーネス全体を意味するわけではない。 コンテキストエンジニアリングとの違い コンテキストエンジニアリングは、現在のモデル呼び出しにどの情報と指示を入れるかを最適化する。検索によって関連文書だけを取得すること、古い会話を要約すること、タスクの状態を外部ファイルに保存すること、サブタスクごとにコンテキストを分けることなどが含まれる。 ハーネスエンジニアリングは、それより範囲が広い。コンテキストだけでなく、ツール権限、実行環境、承認、検証、ロギング、コスト制限まで扱う。したがって、コンテキストエンジニアリングはハーネスの中核部分ではあるが、両者を完全に同じ意味で使うのは正確ではない。 ループエンジニアリングの核心は終了条件だ ループは、エージェントが結果を生成した後に検査し、不十分であれば再試行するようにする。重要なのは反復そのものではなく、進捗の定義と停止条件だ。 代表的なループの種類 検証ループ：下書きを作成した後、テストや評価基準で検査し、失敗した項目を修正する。 イベントベースのループ：メール、通知、コード変更、センサーデータなどの外部イベントが発生したときにタスクを開始する。 探索ループ：複数の仮説や情報源を調査し、証拠が十分になるまで探索範囲を調整する。 改善ループ：以前の結果と評価値に基づいて次の戦略を選択する。単一のスコアだけを最適化すると報酬ハッキングが発生し得るため、複数の評価基準と人によるレビューが必要だ。 復旧ループ：エラー原因を分類し、許可された範囲内で再試行した後、解決しなければ人に引き継ぐ。 安全なループに必要な契約 エージェント間の契約は法的契約ではなく、入出力と責任を明示した実行仕様だ。次の項目を含めることが望ましい。 契約項目 明示する内容 目標 完了すべき結果と対象外の範囲 入力 使用可能なデータ、鮮度、信頼水準 出力 JSONスキーマ、文書形式、必須の根拠とテスト結果 権限 許可するツール、ファイル範囲、外部送信と変更の権限 検証 合格すべきテストと評価基準 予算 トークン、時間、呼び出し回数、並列タスク数 終了 成功、進捗なし、予算消化、リスク検知の条件 引き継ぎ 失敗時にどの人またはエージェントが引き継ぐか 完了条件が曖昧だと、エージェントは文章を変えたり、同じ検索を繰り返したりしながらも、タスクが進展していると判断することがある。最大反復回数だけを設けるより、結果の品質、新しい情報の増加量、エラーの変化、コストを併せて見るほうがよい。 グラフエンジニアリングは自律性の境界を構造化する グラフは、タスクをノードと接続線で表現する。ノードはモデル呼び出し、ツール実行、人の承認、または検証プロセスになり得て、接続線は状態に応じた次の行動を示す。 チェーンとグラフの違い チェーンは、AからB、BからCへと続く線形手順に適している。 グラフは、条件分岐、反復、並列実行、失敗からの復旧、中間保存が必要なタスクに適している。 動的グラフでは、実行中にモデルが次のサブタスクや経路を提案する。 制約付きグラフでは、モデルが選択する場合でも、許可されたノードと遷移の範囲内だけを移動させる。 現代的なグラフ設計の目的は、すべての行動を人が事前に決めることではない。データ削除前に必ず承認ノードを通過させたり、テスト失敗状態ではデプロイ状態へ移行できないようにしたりする形で、守るべき不変条件を構造に組み込むことにある。 グラフが必要な兆候 次の条件のうち複数が当てはまるなら、明示的なグラフを検討する価値がある。 失敗後に戻るべき復旧地点が明確だ。 人の承認が必須となる段階がある。 複数のタスクを並列実行した後、結果を統合する必要がある。 状態に応じて使用可能なツールや権限が異なる。 実行経路全体を監査または再現する必要がある。 単一エージェントのループが同じ失敗を繰り返す。 単純な文書要約や1回限りのデータ変換までグラフにすると、複雑さが増すだけになり得る。 実務への適用手順：ハーネスから始め、必要なだけ拡張する 多くのチームにとって、次の手順が現実的だ。 単一のタスクと成功基準を定める。 まず入力、期待する出力、失敗事例を集める。 最小限のハーネスを作る。 必要なコンテキストとツールだけを提供し、権限、テスト、ログ、コスト上限を設定する。 評価セットを構築する。 正常な事例だけでなく、曖昧な依頼、誤った文書、ツールエラー、権限超過の試みも含める。 反復が必要な箇所をループにする。 検証と修正が実際に品質を高める区間に限って再試行を許可する。 分岐と復旧が複雑な場合はグラフへ昇格させる。 状態と遷移を明示し、危険な行動の前に承認ノードを置く。 業務分担にメリットがある場合に限ってマルチエージェントを使う。 並列探索や異なる専門的役割が必要でなければ、単一エージェントのほうがシンプルで安価な場合がある。 コーディングとリサーチにおける適用の違い 項目 コーディング作業 リサーチ作業 検証可能性 テスト、ビルド、型チェックなどの自動検証が比較的容易 情報源の品質、抜け、相反する証拠を総合的に判断する必要がある 動的探索の価値 変更範囲が明確なら限定的な場合がある 多様な検索経路と仮説の比較において大きい 主なリスク 誤った変更、セキュリティ脆弱性、テストだけに合わせたコード 出典のない主張、重複資料、確証バイアス 適切な制御 リポジトリ範囲の制限、テスト、diffレビュー、デプロイ承認 出典の記録、独立した検索、反証の探索、引用の検証 コーディングでは動的ワークフローが常に非効率で、リサーチでは常に有利だと断定することはできない。テスト可能な大規模マイグレーションは自律エージェントに適する場合があり、答えが明確な事実照会は固定されたリサーチ手順のほうが効率的な場合がある。核心となる変数は分野よりも、目標の明確さ、自動検証可能性、探索空間、エラーコストだ。 コードレビューはなくなるのではなく、レビュー単位が変わる エージェントがコードを書くと、開発者はすべての行を自分で入力する代わりに、要件、設計、テスト結果、変更範囲、リスクを監督する役割をより多く担うことになる。Pull Requestの要約とエージェントのレポートは、レビュー速度を高めることができる。 しかし、要約だけを読んで承認する方式は、安全なデフォルトではない。エージェントが見落とした変更や誤解したロジックは、要約にも現れない場合がある。次の状況では、元のdiffと関連コードを直接レビューしなければならない。 認証、決済、個人情報、暗号化、アクセス制御の変更 データベーススキーマの変更や不可逆的なマイグレーション パフォーマンスと並行性に敏感なコード テスト範囲を超える大規模なリファクタリング 外部依存関係、デプロイ設定、機密情報処理の変更 エージェントの説明と実際のdiffが一致しない場合 Human-in-the-loopとは、人が形式的にボタンを押すことではない。人が判断できるよう、変更の証拠、テスト結果、失敗の可能性、ロールバック手順を提供することまで含む。 陥りやすい罠 目的のないマルチエージェント エージェントを増やすと、役割の調整、重複した呼び出し、コンテキストの受け渡し、結果の統合にコストがかかる。異なる観点からの並列探索が必要、またはコンテキストを分離すべき理由がないのであれば、単一エージェントのほうがよい。 無制限の動的ワークフロー エージェントがサブタスクを作り続けられるようにすると、トークンとツール呼び出しのコストが急速に増加する。コストはおおむね、各段階の入出力トークンコスト、ツールコスト、並列エージェント数、反復回数の合計によって決まる。呼び出し回数、同時実行数、総予算、最大実行時間をそれぞれ制限しなければならない。 1つの評価指標だけを最適化する テスト合格率だけを目標として与えると、テストを弱めたり、例外処理を隠したりするような誤った最適化が生じ得る。品質、セキュリティ、変更規模、コスト、遅延時間、人による評価を併用しなければならない。 文書注入をファインチューニングと混同する 文書検索やプロジェクト指示によって結果が継続的に変化することはあるが、モデルの重みが変わるわけではない。これは広い意味ではシステムの学習効果として説明できるが、厳密には外部メモリとコンテキストを利用した適応だ。文書や検索インデックスを保持してこそ、次回の実行でも変化が維持される。 運用段階で見落としやすい評価・セキュリティ・経済性 エージェント設計は、アーキテクチャ図で終わるものではない。実際の運用では、何を許可したかより、実際に何が起きたかを測定する仕組みが重要だ。 最低限の運用指標 タスク成功率と人による修正率 タスク当たりのモデル・ツールコストと総実行時間 反復回数と進捗なしに消費された呼び出しの割合 承認要求、拒否、権限超過の試行回数 誤ったツール呼び出しと復旧成功率 出典またはテストなしで提出された結果の割合 同一入力で結果が変化する程度 セキュリティ上必要な不変条件 外部文書の指示がシステムポリシーより高い優先順位を持たない。 機密情報をモデル入力とログに不必要に露出させない。 読み取り権限と、書き込み・削除・デプロイ権限を分離する。 外部送信と不可逆的な行動には、別途の承認またはポリシーチェックを設ける。 エージェントが自身の評価基準、テスト、または監査ログを任意に変更できないようにする。 こうした不変条件は、プロンプトの一文よりも、サンドボックス、アクセス制御、グラフ遷移、独立した検証器によって強制するほうが安全だ。生成AIのリスク管理には、モデルの精度だけでなく、運用環境、人の監督、インシデント対応まで含めなければならない。 どの概念から学ぶべきか 現在の実務で最初に習得すべきなのは、ハーネスエンジニアリングだ。正確なコンテキスト、最小権限、自動検証、ログ、承認、コスト上限を備えれば、単一エージェントの多くの失敗を減らすことができる。 次に、反復が品質を高めるタスクへ、終了条件のあるループを追加する。分岐、並列処理、復旧、承認手順が複雑になったときに、グラフとして明示する。複雑な用語を採用することより、エージェントの目標、権限、証拠、コスト、停止条件を測定可能な形にすることが優先される。 FAQ Q. ハーネスエンジニアリングはプロンプトエンジニアリングと何が違うのですか？ A. プロンプトエンジニアリングは主に、モデルに渡す指示と表現を扱う。ハーネスエンジニアリングは、プロンプトだけでなく、コンテキスト検索、ツール、権限、サンドボックス、テスト、ログ、人による承認、エラー復旧まで含む、より広範な実行環境の設計である。 Q. コンテキストエンジニアリングとハーネスエンジニアリングは同じ意味ですか？ A. 同じではない。コンテキストエンジニアリングは、モデルが現在知るべき情報を選択・検索・要約・配置することに重点を置く。ハーネスエンジニアリングは、コンテキスト管理に加えて、権限、ツール、検証、コスト制限、運用ポリシーも併せて扱う。 Q. ループとグラフの最も重要な違いは何ですか？ A. ループは、計画・実行・検証・修正のように、何を繰り返し、いつ停止するかを定義する。グラフは、どのような状態が存在し、ある状態から別の状態へどのように遷移できるかを定義する。グラフ内に1つ以上のループが含まれることがある。 Q. すべてのAIエージェントにLangGraphのようなグラフフレームワークが必要ですか？ A. いいえ。単純で短いタスクは、単一のエージェントと最小限のハーネスで十分な場合がある。条件分岐、並列処理、中間保存、障害復旧、人による承認、または実行経路の監査が必要な場合、グラフの価値が高まる。 Q. マルチエージェントは単一エージェントより常に性能が良いのですか？ A. いいえ。マルチエージェントは、並列調査、異なる専門的役割、コンテキストの分離が必要な場合に有用である。役割が重複していたり、目標が曖昧だったりすると、作業の重複、引き継ぎエラー、遅延、コストが増えるだけになり得る。 Q. エージェントループの無限反復はどのように防ぎますか？ A. 最大反復回数だけでなく、時間、トークン、ツール呼び出し、コストの予算も設定する必要がある。新しい情報がない、またはエラーが減少していない状態を進展なしと判定し、一定の基準に達したら停止するか、人に引き継ぐように設計する必要がある。 Q. AIが作成したコードのPull Requestの要約だけをレビューしてもよいですか？ A. 要約は補助資料にすぎず、元の変更に代わるものではない。認証、決済、個人情報、データ移行、デプロイ設定のようなリスクの高い変更は、実際のdiff、テスト範囲、依存関係、ロールバック手順を直接レビューする必要がある。 Q. 会社の文書を継続的に入力すれば、モデルが学習したことになりますか？ A. 結果が継続的に変わることはあり得るが、モデルの重みが更新されたわけではない。外部文書、検索インデックス、メモリ、指示を保持し、次回の実行時に再び提供するシステムレベルの適応であり、厳密な意味でのファインチューニングとは区別する必要がある。 Q. グラフエンジニアリングは、初期の固定ワークフローに戻ることなのですか？ A. 必ずしもそうではない。現代的なグラフは、エージェントが一部の区間で自律的に計画し、ツールを選択することを許可しながらも、危険な遷移と必須の承認ポイントを明示的に制限するハイブリッド型の制御に近い。 Q. ハーネスを設計する際、最初に決めるべきことは何ですか？ A. まず、タスクの成功基準と失敗コストを決める必要がある。次に、必要なコンテキストとツールだけを提供し、最小権限、自動検証、実行ログ、コスト上限、停止条件を設定することが望ましい。 Sources - Anthropic — 効果的なエージェントの構築: https://www.anthropic.com/research/building-effective-agents - Anthropic — AIエージェントのための効果的なコンテキストエンジニアリング: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents - Anthropic — マルチエージェント研究システムをどのように構築したか: https://www.anthropic.com/engineering/multi-agent-research-system - LangGraphの概要: https://docs.langchain.com/oss/python/langgraph/overview - ReAct：言語モデルにおける推論と行動の相乗効果: https://arxiv.org/abs/2210.03629 - NIST AI 600-1 — 人工知能リスク管理フレームワーク：生成型人工知能プロファイル: https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf Images - 中央のAIシステムを循環矢印と成功・失敗ノードのグラフが囲む図: https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6ODI0NSwicHVyIjoiYmxvYl9pZCJ9fQ==--3a03e254c3d24990df4c3fc46145a5db24e457ba/ai-eb0e40fe.webp - 保護されたAIロボットがツールのループと分岐グラフを経て検証と警告ゲートへ進む流れ: https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6ODI1MSwicHVyIjoiYmxvYl9pZCJ9fQ==--cea797c99aabaa4b8f760264327fe2ee8b34b423/ai-23d7d97a.webp --- Category: ナレッジベース Source: https://injoys.com/ja/articles/ai-agent-harness-loop-graph-engineering License: cc_by Translation-Status: reviewed