
AIエージェントの失敗はどの層で直すか~ハーネス・ループ・グラフの切り分け~
最近、beamnxw(@beamnxw)さんの「Agent Harness Engineering vs. Loop Engineering vs. Graph Engineering」を読みました。エージェント開発でよく混ざる三つの言葉を、別々の設計判断として整理した記事です。
面白いのは、三つを用語の違いではなく、「失敗をどこで直すか」の違いとして並べているところです。この記事では、三つの層がそれぞれ何か、従来の考え方と何が違うか、どう入れ子になるかを、公式の資料で裏づけながら説明します。
【発端】 直す場所を間違えると直らない

エージェントの出来はモデルだけでは決まりません。
同じ基盤モデルを使っても、結果は大きく変わることがあります。ツールが整い、作業場所が安定し、権限が絞られ、状態が見えるチームと、曖昧なプロンプトと不安定なAPIだけを渡すチームでは、働く条件が違うからです。
失敗が出たとき、まずプロンプトを書き換える人は多いはずです。しかし原因が「進捗を忘れる」「止まるべきところで止まらない」「実行順が守られない」なら、プロンプトを直しても役に立ちにくくなります。
三つの層は、この「直す場所」を選ぶための地図です。
【基礎】 モデルの外側は三つに分かれる

環境、フィードバック、フローの三つです。
ハーネスは、モデル以外のコード・設定・実行ロジックの全部です。LangChainは「Agent = Model + Harness」と定義しています。
システムプロンプト、ツール、ファイルシステム、サンドボックス、フックなどが含まれます。
LangChainの解説によると、モデルは単体では状態の保持もコード実行もできません。そうした機能は、ハーネスの側に作り込みます。
ループは、実行して確認し、必要なら再実行する周回です。最小の形は、モデルがツールを呼びながら終わるまで回る「エージェントのループ」です。
LangChainは、その外側に検証、イベント起動、改善のループを積む考え方を紹介しています。
グラフは、処理をノード、次に進める道をエッジとして明示する設計です。AutoGenのGraphFlowは、直列、並列、条件分岐、安全な出口つきのループを扱えます。
ここでのグラフは制御の流れの図です。データ中の人や物の関係を表す知識グラフとは別物です。
なお、三つの呼び名はまだ標準化されていません。起点記事も、実務上の整理として読むよう促しています。
【違い】 症状から入ると層が決まる

「どう書くか」ではなく「何がおかしくなっているか」から始めます。
プロンプトは、一回の呼び出しの中で何をするかを指示します。ループは、呼び出しのあとにシステムが何をするかを決めます。
結果をどう観測し、何を返し、続けるか止めるかを設計するのがループです。
設計する対象
ハーネス:作業環境
ループ:周回と停止
グラフ:実行の順序と分岐
典型的な症状
ハーネス:ツールに安全に触れない、進捗を忘れる
ループ:一発目は惜しいが不安定、成功後も続ける
グラフ:複数の専門役を順に動かしたい
直す手段
ハーネス:ツール仕様、権限、永続状態
ループ:外部の採点、再試行の上限
グラフ:ノード、エッジ、合流条件
払うコスト
ハーネス:道具と記憶の管理
ループ:採点や再試行のたびの呼び出し
グラフ:手順を早く固定するリスク
【仕組み】 ハーネスの中にグラフ、その中をループが回る

三層は競合せず、入れ子になっています。
起点記事は、グラフがハーネスの中で動き、ループがグラフの中で回ると整理しています。ハーネスは、ループが使う状態、ツール、評価器を供給します。
層が重なるので、失敗したときに手を入れる場所が三つある、という見方になります。
ハーネスの効果は、長時間の作業で見えやすくなります。Anthropicは、複数セッションにまたがるコーディングで、初期化役のエージェントと進捗ファイルとgitの履歴を使い、次のセッションが前の状況を読み取れるようにしました。
後続の検証では、圧縮だけでは足りず、文脈をリセットして構造化した引き継ぎを渡す方式が必要になったと報告されています。
ループの核は、自信ではなく証拠で止めることです。起点記事は、停止条件に「エージェントが完了と言った」ではなく、テスト通過やリンク解決のような確認可能な事実を置くよう勧めています。
再試行の上限と、尽きたときの人間への引き継ぎも決めておきます。
グラフでは、どの処理を決まった関数、LLM、人の確認に分けるか、状態を誰が更新するか、どこで合流するかを決めます。
【具体例】 ドキュメント修正エージェントを三層で見る

一つの依頼が三層を順に通ります。
LangChainが紹介する社内のドキュメントエージェントは、ループの例としてわかりやすい題材です。Slackチャンネルへの投稿を合図に起動し、リポジトリを取得し、文書を書き、プルリクエストを開きます。
書いたあとは、採点役がリンクが解決するか、CIが通るか、差分が依頼の範囲内かを確認します。落ちたらフィードバックを返して再試行します。
さらに、実行の記録(トレース)を分析して、プロンプトやツールの改善案を出します。
層に当てはめると、次のようになります。
ハーネス:リポジトリ操作のツール、作業場所、権限、実行記録
ループ:採点して差し戻す周回と、Slackによる起動
グラフ:ここは筆者の整理です。「下書き→校閲→承認なら公開、そうでなければ下書きへ戻る」を線で固定すると、AutoGenの書き手と査読者の例のように、戻り先と出口が見える形になります
【関連概念】 層を足す前に、単純さへ戻る道を持つ

三層は全部使うためのものではありません。
AnthropicのBuilding Effective AI Agentsは、まず最も単純な解を探し、必要なときだけ複雑さを足すよう勧めています。ワークフローは決まったコードの道筋で動き、エージェントはモデルが自分で進め方を決めます。
起点記事も、ループは失敗のコストが検証のコストを上回る場所に足すべきだと述べています。
グラフには、手順を早く固定しすぎる危険があります。計画自体をモデルが組み立てる仕事では、全経路を図にするとかえって脆くなります。
まず単純なハーネスで実行記録を集め、安定した経路だけをグラフにする順番が安全です。
ハーネスにも、詰め込みすぎると困ることがあります。ツールが多すぎれば選択を誤りやすくなり、文脈が雑音で膨らめば混乱しやすくなります。
参考情報・参考書籍
本記事をより深く理解するために、概念マップスライドを作成しました。こちらをみることで理解の補助になるはずです。
関連記事
【まとめ】 直近の失敗を一件、三層に振り分ける

新しい仕組みを入れる前に、診断から始めます。
直近で起きたエージェントの失敗を一件選び、一行で書きます。
「ツールや状態の問題」「確認と停止の問題」「順序と分岐の問題」のどれかに振り分けます。
その層で変える点を一つだけ決めます。ループなら、停止条件を「証拠、最大回数、尽きたときの引き継ぎ先」の三点で書きます。
変更の前後で、同じ入力の結果を並べて比べます。
□ 失敗を一件選んだ
□ 層を決めた
□ 変更を一点に絞った
参考情報
Agent Harness Engineering vs. Loop Engineering vs. Graph Engineering(beamnxw)
Harness design for long-running application development(Anthropic)
関連記事
AIエージェントの記憶の設計~コンテキストウィンドウの外で更新し、減衰させる~
AIの「よさそう」を数字に変える~AI Evals Engineerの12段階から読み解く評価の仕組み~