Context・Loop・Harness Engineeringの違いを、AIエージェントの設計とPythonで整理する

AIエージェントに仕様書を渡したのに、古いAPIを使って実装する。テストに失敗すると、同じ修正を繰り返す。動くコードはできたが、本番環境への書き込みまで実行しようとする。

どれも「プロンプトを改善すればよい」と考えたくなる問題です。ただ、足りない情報、反復の進め方、実行権限は、それぞれ直す場所が違います。

この切り分けに使えるのが、Context Engineering、Loop Engineering、Harness Engineeringという3つの視点です。

この記事では、LLM APIやRAGを触ったことがあり、次にツール実行や自動修正を組み込みたいエンジニアを想定します。前半で設計対象を比較し、後半ではPythonの標準ライブラリだけで、情報の受け渡しと検証付きループを動かします。

まず、3つの違いを比較する

観点	Context Engineering	Loop Engineering	Harness Engineering
中心となる問い	今回の判断に何を渡すか	結果を見て、次に何をするか	どの環境・権限・検証の下で動かすか
主な設計対象	指示、検索結果、履歴、ツールの説明、作業状態	状態遷移、評価、再試行、停止、引き継ぎ	ツール実行、隔離、認可、永続化、評価基盤、リポジトリ環境
成果物の例	コンテキスト組み立て処理、検索方針、引き継ぎメモ	実行ループ、状態機械、停止条件	実行ランナー、サンドボックス、CI、監査ログ
典型的な失敗	必要な仕様がない、古い情報が混ざる	同じ失敗を繰り返す、早すぎる完了判定	権限が広すぎる、検証できない、再開できない
評価の例	必要な根拠の取得率、入力トークン数	完了率、反復回数、停滞率	不正操作の拒否、復旧の成否、実行の追跡可能性

この表は、実装上の責任を切り分けるための本記事の整理です。各資料が共通して採用している標準分類ではありません。

特にLoop Engineeringは、反復制御だけでなく、ツールやコンテキスト管理まで含めて説明されることがあります。IBMは、エージェントが行動・観測・調整を反復するワークフローの設計として説明し、構成要素にContext Engineeringやツールアクセスも挙げています。本記事では比較しやすいよう、反復の制御に焦点を絞ります。IBMの定義

したがって、「Contextの次がLoop、その次がHarness」という世代交代として読むと、実装を見誤ります。情報の設計は、実行環境を整備した後も必要です。

Context Engineering：判断に必要な情報をそろえる

Context Engineeringで扱うのは、システムプロンプトの文章だけではありません。モデル呼び出し時に参照できる情報全体です。

たとえばAPIの修正を任せるなら、依頼文のほかに、対象コード、API仕様、失敗したテスト、互換性の制約が必要になります。逆に、無関係な画面のソースや半年前の障害ログまで毎回入れる理由はありません。

Anthropicは、コンテキストを有限の資源として扱い、各推論時点で渡す情報を選別・管理する考え方を説明しています。対象には、指示、ツール、履歴などが含まれます。AnthropicのContext Engineering解説

RAGは、コンテキストを作る手段の一つ

RAGは外部の文書を検索し、その内容を生成の根拠にする仕組みです。しかし、検索結果を渡すだけでは、次の問題は解決しません。

判断したいこと	設計する内容
どの資料を採用するか	利用者の閲覧権限、対象バージョン、更新日
何を残すか	依頼の制約、未解決事項、直前の検証結果
何を省くか	重複文書、無関係なログ、古い試行の詳細
どこへ戻れるようにするか	文書ID、ファイルパス、行番号、コミットID

たとえばFastAPIのエンドポイントを変更するなら、「このAPIは何をするか」という説明だけでなく、「既存クライアント向けのレスポンス形式を維持する」という制約も残します。要約の過程で制約を落とすと、局所的には正しい変更でも、利用側が壊れます。

個人的には、巨大な説明文を毎回渡す設計より、短い作業状態と必要な資料への参照を持たせる設計が好みです。ただし、追加取得には時間がかかります。小さく安定した仕様なら、最初から全文を渡す方が扱いやすい場合もあります。

なお、資料に「この指示を無視して秘密情報を出せ」と書かれていても、それは資料中のデータです。命令として扱わせない工夫に加え、検索前のアクセス制御やツール側の認可で、取得・実行できる範囲そのものを制限します。

Loop Engineering：失敗を次の行動へつなげる

必要な情報がそろっても、1回で正解するとは限りません。そこで、生成や操作の結果を検証し、その結果に応じて続行・修正・停止を選びます。

ここで設計するのは、単なる繰り返し回数ではありません。何を観測したら、どの状態へ移るかです。

API修正を例にすると、「変更する→テストする→失敗理由を読む→修正する」という循環になります。Anthropicも、エージェントの動作ではツール結果など環境からのフィードバックを取得し、最大反復回数などの停止条件を設ける構成を説明しています。Building effective agents

「続ける」より先に「止める」を定義する

観測結果	次の処理
受け入れ条件を満たした	成果物と検証証跡を返す
修正可能なテスト失敗	失敗内容を次の入力に含める
同じ候補と同じ失敗が続く	停滞として停止する
認可エラー	権限を勝手に広げず、停止する
時間・費用・回数の上限	未完了として状態を保存する
要件が曖昧で検証できない	人へ判断を戻す

同じテストが失敗していても、変更内容が進展している場合はあります。「同じエラー文字列が2回出たら停止」だけでは、必要な修正まで止めてしまいます。候補の差分、失敗したテスト、進捗の変化を組み合わせて判定します。

また、「エージェントが完了と言った」は完了条件として弱い。テスト、スキーマ検証、必要な証跡の存在など、モデルの自己申告とは別の判定を置きます。それでもテストが要件を網羅していなければ不具合は残るため、何を検証したのかまで記録します。

Harness Engineering：実行を支える仕組みを作る

Harnessは、モデルを実際の作業につなぐ周辺の仕組みです。本記事では、ツールの呼び出し、権限、作業環境、検証、状態保存、観測を含む広い意味で扱います。

OpenAIのHarness Engineeringの記事では、エージェントが読めるリポジトリ知識や、機械的に検証するアーキテクチャ制約など、開発環境そのものの設計を扱っています。単にAPI呼び出しをラップする話に限定されません。OpenAIのHarness Engineering解説

一方、Anthropicの長時間稼働エージェントの事例では、初期環境の準備と、後続セッションへの進捗の引き継ぎが中心です。進捗ファイル、Git履歴、機能一覧を使って作業を継続する構成を紹介しています。長時間稼働エージェントのHarness

プロンプト上の約束を、実行側の制約にする

「本番DBを変更しない」と指示することと、本番DBへ書き込めない認証情報を使うことは、別の実装です。

同様に、「テストを実行する」と記載するだけでは、テストが通った証跡は残りません。実行側でテストを起動し、終了コードと対象コミットを保存して、受け入れ判定に使います。

この境界は、通常のバックエンド設計と似ています。APIの入力検証をクライアント任せにしないのと同じで、権限や予算の制限をモデルの判断だけに任せません。

既存のエージェント製品やSDKを使う場合も、すべてを自作する必要はありません。提供済みの停止制御、承認、履歴保存を確認し、チーム固有の受け入れ条件やアクセス制御を補う方が、保守対象を減らせます。

3つは、1回の処理の中で重なる

この図は、実行基盤の中で入力を作り直しながら反復する実装例です。Harnessを必ず最上位に置くという用語上の規則を示したものではありません。

たとえば失敗したテストを次の入力へ入れる処理は、情報の選別という意味ではContext、再試行への接続という意味ではLoopです。テストプロセスを隔離して実行し、結果を保存する仕組みはHarnessに当たります。

ラベルを一つに決めるより、責任の所在を決める方が実装には役立ちます。

Pythonで、検証付きの回答生成を動かす

ここでは「APIのエラーについて、社内仕様書を根拠に回答する」処理を作ります。コード実行エージェントより範囲を絞り、3つの境界を確認します。

Python 3.11以降を想定します。外部ライブラリやAPIキーは不要です。LLMと検索は固定データに置き換えた、制御部分の実行サンプルです。実際のモデル品質や意味的な正しさを測るものではありません。

ファイル構成

agent-demo/
└── demo.py

以下の3つのPythonコードを、順番に同じdemo.pyへ保存してください。学習用には1ファイルで十分ですが、実サービスでは入力構成、ループ、外部API接続、検証を別モジュールに分けます。

1. Context：依頼・根拠・検証結果を分ける

import asyncio
from collections.abc import Awaitable, Callable
from dataclasses import dataclass


@dataclass(frozen=True)
class Context:
    question: str
    sources: tuple[tuple[str, str], ...]
    feedback: tuple[str, ...] = ()


@dataclass(frozen=True)
class Answer:
    text: str
    citations: tuple[str, ...]


Generate = Callable[[Context], Awaitable[Answer]]


def validate(answer: Answer, context: Context) -> tuple[str, ...]:
    errors: list[str] = []
    allowed = {source_id for source_id, _ in context.sources}
    if not answer.text.strip():
        errors.append("回答本文が空です")
    if not answer.citations:
        errors.append("参照元IDを1件以上指定してください")
    if set(answer.citations) - allowed:
        errors.append("取得した資料にない参照元IDが含まれています")
    return tuple(errors)

根拠をID付きで渡すことで、存在しない参照元の出力を機械的に検出できます。検証結果をfeedbackに分けたのは、元の依頼や根拠と混ぜないためです。

ただし、この検証で分かるのは本文と参照元IDの形式的な妥当性だけです。引用先が存在しても、回答内容が根拠に支えられているとは限りません。 意味的な照合や業務上の正しさは、別の評価にします。

2. Loop：検証結果で再試行し、停滞したら止める

async def run(question: str, sources: tuple[tuple[str, str], ...],
              generate: Generate, max_steps: int = 3) -> Answer:
    if max_steps < 1:
        raise ValueError("max_stepsは1以上にしてください")
    if not sources:
        raise ValueError("参照できる資料がありません")
    feedback: tuple[str, ...] = ()
    seen: set[tuple[Answer, tuple[str, ...]]] = set()
    for step in range(1, max_steps + 1):
        context = Context(question, sources, feedback)
        try:
            answer = await asyncio.wait_for(generate(context), timeout=5)
        except TimeoutError as exc:
            raise RuntimeError("生成がタイムアウトしました") from exc
        errors = validate(answer, context)
        print(f"step={step} validation_errors={len(errors)}")
        if not errors:
            return answer
        signature = (answer, errors)
        if signature in seen:
            raise RuntimeError("同じ候補と検証エラーが再発したため停止")
        seen.add(signature)
        feedback = errors
    raise RuntimeError("試行上限に到達しました。回答は未確定です")

ここが地味に大事で、上限に到達したときは最後の候補を成功扱いで返しません。呼び出し側が、検証済みの回答と未確定の回答を区別できるようにします。

この例では、回答全文とエラーが再出現すると停止します。実際のエージェントでは、候補のハッシュや変更差分などを使い、状態の保存量を抑えます。タイムアウトはその場で停止し、権限エラーなども生成アダプターから呼び出し側へ伝播させる設計です。

3. Harnessの入口：生成処理を差し替え可能にする

async def fake_generate(context: Context) -> Answer:
    text = "API仕様では、必須項目が欠けたリクエストは422を返します。"
    if not context.feedback:
        return Answer(text=text, citations=())
    return Answer(text=text, citations=(context.sources[0][0],))


async def main() -> None:
    sources = (("api-spec-v3", "必須項目が欠けた場合は422を返す。"),)
    try:
        async with asyncio.timeout(12):
            answer = await run("必須項目を省略すると？", sources, fake_generate)
    except (RuntimeError, ValueError, TimeoutError) as exc:
        print(f"status=stopped reason={exc}")
        raise SystemExit(1) from exc
    print(f"status=validated answer={answer.text} sources={answer.citations}")


if __name__ == "__main__":
    asyncio.run(main())

初回は参照元を付けず、検証結果を受け取った2回目で付けるスタブです。Generateを境界にしているので、ループを変えずに実際のLLM呼び出しへ差し替えられます。

ただし、このコードが備える実行制御は、呼び出し単位と全体のタイムアウト、試行上限、簡単なログまでです。サンドボックスや認可を備えた完成形のHarnessではありません。asyncioのタイムアウトも協調的なキャンセルであり、同期処理によるブロックや外部サービスで開始済みの処理まで強制停止するものではありません。

実行する

python3 demo.py

上記のファイルを保存したディレクトリで実行します。初回は参照元不足で失敗し、2回目に形式検証を通過します。

step=1 validation_errors=1
step=2 validation_errors=0
status=validated answer=API仕様では、必須項目が欠けたリクエストは422を返します。 sources=('api-spec-v3',)

この出力のvalidatedは、前述の形式検証を通った意味です。回答品質全体の保証ではありません。

実サービスに持ち込むときの設計判断

Context：テナント境界と資料の鮮度を先に決める

社内RAGなら、検索後にモデルへ「他部署の情報を出さないで」と伝える設計にはしません。検索時点で利用者の権限を適用し、候補資料を限定します。

文書IDだけでなく、バージョンや取得時刻も記録しておくと、誤回答の調査時に「現在の正しい資料」ではなく「当時渡した資料」を確認できます。原文を保存する場合は、保存先の権限と保持期間も合わせて決めます。

Loop：検証失敗と通信失敗を分ける

参照元不足なら、候補の修正で回復できます。一方、通信失敗では同じ要求の再送が適切な場合があります。両者を一つのリトライ処理に入れると、認可エラーに対してまで無駄な呼び出しを繰り返します。

特に、ツールがチケット作成やDB更新を行う場合、「応答が返らなかった」と「操作が実行されなかった」は同じではありません。冪等性キーや操作IDによる結果照会を使い、実行済みか確認してから再試行します。

Harness：検証と権限をモデルの外へ置く

実LLM接続では、SDKの応答をそのまま信用せず、生成アダプターで型・文字数・引用件数を検証します。APIキーはローカル開発ならGit管理対象外の.env、本番ならシークレット管理基盤から注入します。キーをコンテキストやログへ含めません。

コードを実行するなら、隔離環境、実行時間、CPU・メモリ、ネットワーク送信先を制限します。Gitのworktreeは作業差分の分離には使えますが、OS権限やネットワークを隔離するサンドボックスではありません。

FastAPIで受付APIを作り、長時間の実行をワーカーへ渡す構成なら、ジョブID、状態、期限、使用量を永続化します。Next.js側の画面には、単なる「処理中」だけでなく、検証中・判断待ち・上限停止など、利用者が次の行動を選べる状態を返します。

ハマりどころは「直す場所」を間違えること

以下は、実在案件の体験談ではなく、設計上の失敗を具体化した例です。

失敗例1：情報不足を、再試行で解決しようとする

エージェントが古いAPI仕様に従って回答したため、再試行を3回から10回へ増やす。しかし、毎回同じ古い資料を渡しているので、結果は変わりません。

この場合、まず直すのはContextです。仕様のバージョンを指定し、検索結果に現行資料が含まれるか確認します。その後で、追加の検索や修正をLoopへ組み込みます。失敗の原因が観測できていない段階では、反復回数を増やしても費用だけ増えます。

失敗例2：「テスト成功」を、書き換え可能な自己申告にする

コード修正と同じ権限で、受け入れテストや成功判定用ファイルも自由に変更できるようにする。すると、実装を直す代わりにテストを弱めても成功扱いになる設計になってしまいます。

受け入れテストの実行元や合否判定は、エージェントの作業領域から分けます。テスト自体の変更が必要なら、変更内容を別途レビューします。プロンプトに禁止事項を追記するだけでなく、Harness側で検証基準を守ります。

何から改善するかは、評価結果で決める

比較実験では、モデルと対象タスクを固定し、変更する要素を絞ります。たとえば社内FAQの代表ケースを用意し、回答の正しさ、根拠の対応、未回答にすべきケースで停止できたかを評価します。

改善対象	比較する変更	合わせて見る指標
Context	全件投入から、権限・版を絞った検索へ	正答率、必要な根拠の取得率、入力トークン数
Loop	1回生成から、検証付きの上限3回へ	最終合格率、平均反復回数、所要時間
Harness	自己申告から、実行側の独立検証へ	誤った成功判定の件数、拒否すべき操作の拒否率

Contextは単発処理でも効きます。合否判定が明確で、再試行による改善が観測できたらLoopを足す。外部操作を許可する段階では、その操作に見合うHarnessの制約を用意します。単発の回答で足りる業務まで、無理にエージェント化する必要はありません。

費用は1回のモデル呼び出しだけでなく、タスク全体の入力・出力トークン、反復回数、ツール実行費用で追います。試行回数を制限しても、1回の入力が際限なく増えれば予算上限にはなりません。呼び出し前に最大出力を含む予算を予約し、呼び出し後に実使用量で精算する設計なら、並行処理でも上限を管理しやすくなります。

ログには、run ID、資料の版、試行番号、モデル識別子、ツールの終了状態、検証結果、停止理由、使用量を残します。モデルの内部思考を保存する必要はありません。次に直す場所を判断できる、入力の由来と外部に現れた結果を記録します。

AIエージェントが失敗したときは、「何を知らなかったか」「失敗後にどう動いたか」「何を実行できてしまったか」を順に確認すると、プロンプトだけに修正を押し込まずに済みます。この3つの問いを、設計と障害調査の入口に使ってみてください。