エージェンティック・ハーネス設計ガイド — Part 1
エージェンティック・
ハーネスとは?
定義・7つの層・原理原則12箇条を、9枚の図で。
エージェンティック・ハーネス(agentic harness)とは、AIモデルに「仕事を最後までやり切らせる」ための周辺機構をまとめて与える実行基盤です。実行ループ、ツール接続、実行環境(サンドボックス)、記憶・コンテキスト管理、停止条件、承認ゲート、実行の記録などが含まれます。モデルが「頭脳」だとすれば、ハーネスは手・作業場・記憶・規律を備えた「体」にあたります。
AIエージェントの話題は、ほとんどが「どのモデルを使うか」に集まります。しかし実際に業務へ載せようとすると、詰まるのはモデルの賢さではありません。途中で止まる・失敗が握り潰される・二重に実行される・再起動で作業が消える——こうした問題は、モデルの外側にある実行基盤の設計で決まります。
この記事では、その実行基盤——エージェンティック・ハーネス——が何であり、どんな要素からできていて、設計上どんな原則があるのかを、図を使って一通り解説します。特定の製品の説明ではなく、業界で共有されつつある一般的な設計論として整理しています。
7層
ハーネスの構成レイヤー
12箇条
設計の原理原則
4種
タイムアウトの分類
93%
承認プロンプトが承認される割合
1.ハーネスとは、モデルに与える「体」である
「ハーネス(harness)」は、もともと馬具や安全帯を指す言葉です。力そのものではなく、力を目的の方向に働かせるための装具を意味します。AIの文脈でも同じで、推論能力そのものはモデルが持っており、ハーネスはそれを「仕事」に変換する装具を指します。
モデルは、与えられた文脈から次の一手を出力するだけの存在です。ファイルを読むことも、システムを呼ぶことも、前回の続きを覚えていることも、それ自体ではできません。それらを与えるのがハーネスです。
重要なのは、この体はモデルとは独立して設計・改善できるということです。モデルを新しいものに差し替えても体は残りますし、逆に同じモデルを使っていても、体の設計次第で完遂率・安全性・運用コストは大きく変わります。「どのモデルを使うか」より「どんな体を与えるか」のほうが、業務での結果を左右する場面は少なくありません。
2.なぜ必要か — 対話型AIとの構造的な差
読む・調べる用途の対話型AIと、自ら手順を決めて作業を完了させる自律型エージェントの間には、実装上の大きな隔たりがあります。これはモデルや検索の延長では埋まりません。
違いを整理すると、次のようになります。
| 観点 | 対話型AI | 自律型エージェント |
|---|---|---|
| 求められること | 問いに答える | 作業を完了させる |
| 実行の単位 | 1回の応答 | 数十回のツール呼び出し |
| 手順の決定 | 人が都度指示する | エージェントが自ら組み立てる |
| 出力の届く先 | 依頼した本人 | 他システム・他者 |
| 失敗の現れ方 | 回答の品質が低い | 途中で停止する/二重に実行される |
| 必要な実装 | モデル・検索・プロンプト | 左記に加え、実行・統制・記録の機構 |
要素が増えるのではなく、実行の前提が変わる
対話型AIは「答えを返して終わる」ことを前提に組まれます。自律型では、途中で止まる・失敗する・再開することが常態です。これらは後から足せる部品ではなく、最初から基盤側の設計に含める対象になります。
3.ハーネスは、7つの層でできている
実装は製品ごとに違いますが、層の分け方はおおむね共通です。この7つは、どの製品・どのフレームワークを評価するときにも比較の軸になります。
- <b>L1 実行環境</b> — サンドボックス、通信制御、資格情報。ここが弱いと、そもそも止められない。
- <b>L2 メモリ・状態</b> — 作業ファイル、短期/長期の記憶、書き込みの統制。覚え違いがここで定着する。
- <b>L3 ツールとスキル</b> — ツール設計、段階的開示、エラー設計。選べない・直せないはここ。
- <b>L4 コンテキスト管理</b> — 予算配分、圧縮とリセット、不変条件の再注入。長い作業が崩れるのはここ。
- <b>L5 制御ループ</b> — 停止条件、予算、チェックポイント。終わらない・落ちたら消えるはここ。
- <b>L6 検証・可観測性</b> — 成果の採点、トレース、CI ゲート。「できたつもり」が通るのはここ。
- <b>L7 統制・監査</b> — 台帳、権限、監査ログ。誰が何をしたか説明できないのはここ。
事故は、層をまたいだときに起きる
個々の層の作り込みより、責務が層をまたいで混ざることのほうが事故を生みます。典型は権限の判断をモデルに任せてしまうこと——L7 で決めるべきことを L4(プロンプト)で書いてしまう形です。設計をレビューするときは「この判断は、どの層が持っているか」を先に問うと早く見つかります。
このうち対話型AIですでに揃っているのは L3 の一部と L4 の一部だけです。残りは、自律化にあたって新たに設計・実装する対象になります。
4.原理原則、12箇条
層の分け方が「どこに何を置くか」だとすれば、原則は「何を守るか」です。以下の12は、公開されている一次情報を横断して繰り返し現れるもので、本シリーズ全体の背骨にあたります。詳しく扱う回を右に添えました。
| # | 原則 | なぜ | 詳しくは |
|---|---|---|---|
| 01 | まずワークフローを試し、エージェントは必要なときだけ使う | 手順が決まっているなら、決定的な処理のほうが速く安く確実 | Part 7 |
| 02 | 制御フローを自分のコードで持つ | これが無いと、再開も監査も予算制御も成立しない | Part 3 |
| 03 | 文脈の前半は書き換えず、足すだけにする | 先頭を1つ動かすとキャッシュが全部無効になり、費用が跳ねる | Part 2 |
| 04 | コンテキストは「注意の予算」として配分し、劣化点を自分で測る | 劣化はモデル固有。公称の窓長ではなく、自社タスクでの飽和点を測る | Part 2 |
| 05 | 目標・制約・現在状態は、毎回そのまま再注入する | 要約は最も希少なものから落とす。制約が消えると静かに違反する | Part 2 |
| 06 | ツールは API の写経ではなく、業務の一単位で作る | 説明が重複して選択が鈍り、往復が増えて文脈を圧迫する | Part 4 |
| 07 | 数が増えたら「読み込む」のをやめ「探す」に変える | 全件提示は枠を食い、選択精度を下げる | Part 4 |
| 08 | 隔離できるなら、操作の表現はコードにする | モデルはツール呼び出しよりコードを多く見てきている | Part 4 |
| 09 | 検証はエージェント自身以外に行わせ、環境の状態を採点する | 自分の成果を採点させると、自信をもって称賛する | Part 6 |
| 10 | 権限はモデルの外で、決定的に強制する | プロンプトは意図であって制御ではない | Part 5 |
| 11 | 機密・不信入力・外部送信の3つを同じ文脈に重ねない | 揃うと、プロンプトによる防御では原理的に守れない | Part 5 |
| 12 | 耐久性はセキュリティ属性である | 再開できないと、二重実行も、事故後の復元も、補償もできない | Part 3 |
このうち 01 は、しばしば飛ばされます。エージェントを作る前に「そもそも要るのか」を確かめる——ここを省くと、後段の投資がまるごと無駄になります。Part 7で、着手の順番として扱います。
5.脳と手を分ける — そして、その外にログを置く
ハーネス設計でいま最も重要な構造が、制御プレーン(脳)・実行プレーン(手)・永続層(セッション)の三層分離です。Anthropicが自社のマネージド・エージェントの設計として公表しており、耐久実行の分野(DBOSやTemporalなど)が別ルートで到達していた結論とも一致します。
この分離が効くのは、失敗の「層」を保ったままモデルに返せるようになるからです。実行環境のコンテナが落ちたとき、それを「生成の失敗」として扱うと、エージェントは自分の出力が悪かったと解釈して同じ生成をやり直します。正しくは「ツール呼び出しが失敗した=回復可能な失敗」として返すべきで、そのためには手が脳の外にある必要があります。
状態を外のイベントログに置くことの効果はさらに大きく、脳のインスタンスが死んでも、ログを再生すれば別のインスタンスが同じ続きから再開できます。実行環境は「ペット」から「家畜」になり、位置を指定して過去を取り出せるため、「戻せない要約」を強いられる場面も減ります。
実務上の効き目
実行環境を前払いで確保せず、ツール呼び出しが必要になった時点で起動する(オンデマンド供給)ことで、最初の応答までの時間が中央値で6割削減されたと報告されています。また、認証情報はサンドボックスに入れず、外部の保管庫とプロキシ経由で代行するのが定石です。
6.コンテキスト設計 — 要約は最後の手段
長い作業をさせると、必ずコンテキストの上限に当たります。ここで反射的に「要約して畳む」を選ぶ実装が多いのですが、推奨される順序は逆です。安い手・損失の少ない手から順に使い、要約は最後に置きます。
要約を行う場合も、何を逐語で残すかを指定することが重要です。残すべきは、文脈付きの数値、タスクの状態(どこまで終わり、どこが未着手か)、未解決の論点。捨ててよいのは、付録的な表、逐語引用、低レベルな推論過程です。
さらに長時間の作業では、要約して続けるよりも引き継ぎ書をファイルに書き、文脈は完全に捨てて新しいセッションで入り直すほうが結果が良い場合があります。残量を意識したエージェントが仕事を早仕舞いしてしまう挙動を避けられるためです。エージェント間の受け渡しは、会話の連続ではなくファイルで行う——これが長時間タスクの定石になりつつあります。
並行して動くサブエージェントについても同じ原則が適用されます。探索の生ログを親に返さず、凝縮した結果だけを返す。親のコンテキストは、子の作業量に比例して膨らんではいけません。
7.耐久実行 — 落ちても、途中から再開できる
自律型エージェントの実行は、数分から数時間に及びます。その間には、デプロイもあれば再起動も障害もあります。中断は例外ではなく前提として設計する必要があります。
耐久実行の分野が処方する不変条件は、おおむね次の4つです。
- ステップ境界でチェックポイントを取り、完了したステップは二度と再実行しない(各ステップは冪等に、全体の流れは決定的に)。
- 待機を永続化する。人の承認を数時間〜数日待つ間、プロセスを保持し続けない。起床の条件を保存しておき、必要になったら起こす。
- heartbeat は「進捗ペイロード付きの生存証明」にする。単なる打刻では、リトライ後の試行が何も引き継げない。
- 再開はIDから行う。同じIDの仕事は一度しか実行されないようにし、未完了のものを検出して同じ入力で再開する。
このとき見落とされやすいのが、タイムアウトを1種類で扱ってしまうことです。「応答がない」には、キューが詰まっているだけの場合と、本当に死んでいる場合があります。両者を区別できないと、生きている仕事を殺すか、死んだ仕事を待ち続けるかのどちらかになります。
8.ツールとスキル — 読ませすぎない設計
接続先が増えるほど、エージェントはツールを選べなくなります。原因はモデルの能力ではなく、全件を常に提示している設計にあることがほとんどです。人間のエンジニアが選択肢を見て迷うなら、モデルも迷います。
- ツールのエラーは、不透明なコードではなく「具体的で実行可能な次の一手」を伝える。切り詰めやページングも、「結果が限られていること」と「次はクエリを絞れ」を本文で伝える。
- 簡潔版と詳細版を引数で選べるようにし、後続の呼び出しにIDが必要なときだけ詳細を取らせる。
- 名前空間で境界を作る。曖昧な名前は、そのまま選択の失敗になる。
- 返す識別子は、意味の読み取れるものにする。ランダムなIDだけでは、モデルは文脈を復元できない。
繰り返す手順を「スキル」として持たせる場合も、同じ発想が使われます。全部を最初から読ませるのではなく、必要になった分だけ開く——段階的開示(progressive disclosure)です。
もうひとつの原則は、決定性が必要な処理は、指示ではなくスクリプトとして同梱することです。毎回モデルに考えさせると結果が揺れます。手順が確定しているなら、コードとして書いて実行させたほうが、速く・安く・確実です。
9.封じ込めと承認 — 人の確認は、境界の代わりにならない
「重要な操作は人が承認する」は、多くの導入計画に書かれます。しかしこれを唯一の防護にしてはいけないことが、実測で示されています。
設計上のポイントは、許可リストの捉え方を変えることです。ドメインの許可リストは「宛先のフィルタ」ではなく能力(capability)の付与として読むべきで、あるサービスへの接続を許すことは、そのサービスでできること全部を許すことに等しくなります。
隔離の強度も、一律ではなく利用者の専門性に合わせます。開発者はコマンドの内容を精査できますが、一般の業務利用者にはそれを期待できません。後者には、精査ではなく絶対的な境界が要ります。
そのうえで、人の承認の使い方も変わってきています。承認を待つ間エージェントを止めるのではなく、先に進ませておいて、承認が下りた分だけ確定させるという非同期の方式や、同じターンの承認をまとめて一度に判断させる束ね方が現れています。承認の回数を減らすことが、そのまま承認の質を上げます。
統制基盤とハーネスの役割の違い
APIゲートウェイなどのAI統制基盤は「誰がどのAPIに到達してよいか」を扱い、ハーネスは「そのAPIを呼ぶ前に人が確認するか」を扱います。境界側の記録に残るのは主に「どのAPIが呼ばれたか」であり、判断の経緯と承認の記録をどちらの層で保持するかは、設計時に決めるべき論点になります。
10.検証と、ハーネスの賞味期限
エージェントの挙動は、モデル単体ではなくモデル・ハーネス・ツール・実行環境・ポリシーの組み合わせで決まります。したがって検証も、その単位で設計する必要があります。応答文の妥当性ではなく、実行後の環境の状態で合否を判定する——結果で採点する層を持つことが要点です。
このとき、生成する側と評価する側を分けることが強いレバーになります。自己評価は甘くなります。評価は静的なレビューではなく、実際に動かして触って採点するほうが機能します。実装前に「何をもって成功とするか」を検証可能な形で先に合意しておくと、評価の基準がぶれません。
最後に、しばしば見落とされる論点があります。ハーネスの各部品は、その時点のモデルの弱さを前提に置いた回避策を含んでいるということです。モデルが改善されると、その回避策は不要になり、ときには足を引っ張ります。モデル更新のたびに部品を外して再テストし、四半期程度の頻度で構成そのものを見直す——ハーネスには賞味期限がある、という前提で運用するのが現実的です。
Summary
この記事の要点
- 1エージェンティック・ハーネスとは、モデルに「手・作業場・記憶・規律」を与える実行基盤である。モデルが頭脳なら、ハーネスは体にあたる。
- 2対話型AIとの差は機能の多寡ではなく、実行の前提そのもの。「途中で止まる・失敗する・再開する」を常態として設計する。
- 3構成は7層 — 実行環境/メモリ・状態/ツールとスキル/コンテキスト管理/制御ループ/検証・可観測性/統制・監査。事故は層をまたいで責務が混ざったときに起きる。
- 4脳(推論)・手(実行環境)・セッション(追記専用ログ)を分ける。状態を外に置けば、インスタンスが死んでも再開できる。
- 5コンテキストは安い手から。要約は最後の手段で、長時間作業では「引き継ぎ書を書いて入り直す」ほうが良いこともある。
- 6耐久実行の要点は、ステップ境界のチェックポイント・永続化された待機・進捗を運ぶ heartbeat・IDによる再開。タイムアウトは1種類では足りない。
- 7ツールもスキルも「読ませすぎない」。段階的開示と、決定性が要る処理のスクリプト化。
- 8人の承認は環境境界の代替にならない(約93%は承認される)。先に境界を敷き、承認は不可逆な操作に絞る。
- 9ハーネスには賞味期限がある。部品はモデルの弱さの仮定を含むため、定期的に外して再テストする。
Deeper
実装の視点で、さらに深く
この記事は製品に依存しない設計論として書いています。実装としてどう組んだかは、homula.ai の技術解説で扱っています。
Sources
出典・参考文献
本記事は、以下の一次資料をもとに整理しています。数値・仕様は各出典の公開時点のものです。
- Anthropic — Effective harnesses for long-running agents
- Anthropic — Harness design for long-running application development
- Anthropic — Effective context engineering for AI agents
- Anthropic — Writing effective tools for agents
- Anthropic — Equipping agents for the real world with Agent Skills
- Anthropic — Scaling Managed Agents: Decoupling the brain from the hands
- Anthropic — How we contain Claude across products
- Claude Cookbook — Context engineering: memory, compaction, and tool clearing
- LangChain — Deep Agents (JS) ドキュメント
- DBOS — Architecture / Workflow / HITL
- Temporal — Detecting activity failures
- Cloudflare OS
FAQ
よくある質問
エージェンティック・ハーネス(agentic harness)とは、AIモデルに「仕事を最後までやり切らせる」ための周辺機構をまとめて与える実行基盤です。実行ループ、ツール接続、実行環境(サンドボックス)、記憶・コンテキスト管理、停止条件、承認ゲート、実行の記録などが含まれます。モデルが「頭脳」だとすれば、ハーネスは手・作業場・記憶・規律を備えた「体」にあたります。日本語では「AIエージェント実行基盤」とほぼ同義で使われます。
AIエージェントは「自ら手順を決めて作業を完了させるAI」という振る舞いを指す言葉で、エージェンティック・ハーネスはその振る舞いを成立させている実装層を指します。エージェントは「何をするか」、ハーネスは「それをどう成立させるか」です。同じモデルを使っても、ハーネスの設計次第で完遂率・安全性・コストが大きく変わります。
モデルが賢くなっても、いつ止めるか・失敗をどう分類するか・完了をどう判定するか・中断からどう再開するかは、モデルの外側で決める必要があるためです。これらはモデルの推論品質ではなく、実行基盤の設計で決まります。また、コード生成が速くなっても短縮できるのは「記述」であって「検証」ではないため、工数の大半は実装ではなく設計と検証に向かいます。
要約は最後の手段です。推奨される順序は、①再取得できるツール実行結果を外科的に捨てる(無損失)、②進捗や決定事項をファイルに書き出して必要な時に読み戻す、③会話全体を要約して畳む(損失あり)、の順です。長時間の作業では、要約して続けるより「引き継ぎ書を書いて文脈は捨て、新しいセッションで入り直す」ほうが結果が良い場合もあります。
承認だけでは不十分です。Anthropicの報告によれば、Claude Codeの許可プロンプトは約93%が承認されており、人間の監督は決定論的な環境境界の代替にはなりません。まず既定でゼロアクセスとし、必要な能力だけを与える境界を環境側で敷いたうえで、人の承認は金銭・削除・外部送信・公開といった不可逆な操作に絞るのが現実的な設計です。
定期的な見直しが要ります。ハーネスの各部品は「その時点のモデルの弱さ」を前提に置いた回避策を含んでおり、モデルが改善されると不要になったり、かえって足を引っ張ったりします。モデル更新のたびに部品を外して再テストし、四半期程度の頻度で構成を見直すことが推奨されています。
Next
次に読む
Learn
AIエージェントとは?— 定義・分類・構成要素
「何をするか」の側から、AIエージェントそのものを整理したガイド。本記事の前提知識にあたります。
Learn
AIエージェントのセキュリティ設計
本記事が「止める・再開する」を扱うのに対し、こちらは「守る」側の設計。あわせて読むと全体像が揃います。
実行基盤を、自社で持ちたい方へ
homulaは、AIエージェント実行基盤の要件定義から設計・構築・運用までを支援しています。内製および自社環境でのホスティングを前提としたご相談も承っています。