ハーネス設計の原則10本

AIエージェントはモデルで壊れるのではない

はじめに

AIエージェントの議論は、ついモデル比較に流れやすい。
どのモデルが強いか。どのベンチマークで勝ったか。どのAPIが速いか。

もちろん、それは大事です。
ただ実務でエージェントを壊している主因は、しばしばモデルそのものではありません。

本当の差が出るのは、モデルの外側です。
どんな道具を持たせるか。どの順で動かすか。何を覚えさせ、何を捨てるか。どこで止め、どこで検証し、どこで人間を介入させるか。
Anthropic は Claude Agent SDK を「Claude Code を支える tools・agent loop・context management」と説明し、OpenAI は Codex harness を複数サーフェスで再利用する中核実装として位置づけ、LangChain も「Agent = Model + Harness」と明示しています。
つまり、いま競争の主戦場になっているのは、モデル単体ではなく、モデルを仕事に変える実行基盤です。

ここでいうハーネスは、単なるラッパーではありません。
オーケストレーション、ツール呼び出し、状態保持、コンテキスト編集、権限制御、検証、再開、追跡まで含めた、実務用の運転席です。
OpenAI Agents SDK は Runner の loop、Sessions、guardrails、HITL、tracing を標準機能として持ち、LangGraph は checkpoints・interrupts・thread 単位の persistence を中核に据えています。
Perplexity の Agent API も、preset ごとに model・token limits・reasoning steps・tools を束ねて提供しており、これも「管理された harness」をAPIとして出している形です。

重要なのは、これは抽象論ではないということです。
LangChain は 2026年2月、同じ gpt-5.2-codex のまま harness だけを変えて Terminal Bench 2.0 を 52.8 から 66.5 へ改善し、Top 30 圏外から Top 5 まで引き上げたと報告しました。
OpenAI も、agent-first な開発では「環境が underspecified だと進まない」と書いています。
つまり、モデル性能は天井を決めるが、ハーネス設計は歩留まりを決める、という理解の方が現場に近い。

では、何を原則として設計すればよいのか。
ここからは、いまの主要実装群を見て、production の Agent Harness に必要だと考える原則10本を述べます。

1. ハーネスを「周辺機能」ではなく「仕事の本体」として扱う

エージェント設計で最初に捨てるべき誤解は、ハーネスを prompt の外側に付ける付属品だと見る姿勢です。
LangChain は harness を「model 以外の code, configuration, execution logic 全体」と定義し、Anthropic も SDK の中核を tool・loop・context management として説明しています。
つまり、prompt は部品の一つであって、仕事の本体はその外側の実行系にあります。

この認識に切り替わると、設計の重心が変わります。
「どんな魔法の指示を書くか」ではなく、
「どんな環境なら失敗しにくいか」
「どんな証跡なら途中から再開できるか」
「どんな確認手段なら自己満足の完了を防げるか」
が主題になります。
OpenAI が internal beta を“手書きコードゼロ”で進めたときも、焦点はコード生成そのものより、環境、feedback loops、control systems の設計に移っていました。

2. まず単一エージェントを完成させる

multi-agent は見栄えが良い。
ですが、最初からそこへ飛ぶと壊れやすい。

OpenAI Agents SDK の基本 loop は単純です。LLM を呼び、tool calls があれば実行し、結果を足して再ループし、final output なら終わる。
Anthropic の Claude Agent SDK も gather context → take action → verify work → repeat を基本形にしています。まずはこの単一ループを壊れず回せることが先です。

multi-agent が効くのは、役割分離、依存関係、共有状態、停止条件が明示されているときだけです。
Anthropic の multi-agent research system でも、tool selection や search strategy に明示的ヒューリスティクスを与えていますし、並列 C compiler 実験も shared codebase・task coordination・repo hygiene が前提でした。
境界のない並列化は賢さではなく混線を増やす。
最初は一体で勝ち、そのあと必要なところだけ分割するのが筋です。

3. ツールは「能力」ではなく「契約」として設計する

ツールを増やせば強くなる、は半分だけ正しい。
実際には、ツールが増えるほど、説明の曖昧さ、選択ミス、権限の広がり、文脈コストが増えます。

Anthropic は tool descriptions の質が agent の成否を大きく左右すると書いており、Claude の tool use でも tool description に基づいて呼び出しが判断されます。さらに MCP では hundreds of tools に接続できる一方で、第三者ツールの安全性や prompt injection に注意が必要だと明記しています。
つまり、ツールは「ある」だけでは不十分で、役割、引数、失敗時の振る舞い、破壊性、信頼境界まで含めて契約化しなければいけません。

ここで効く設計は二つあります。
一つは、最小公開です。必要な局面で必要な道具だけ見せる。
Anthropic は Tool Search や MCP Tool Search によって、膨大なツールを context window に全部載せず、必要時に探索・利用する方向へ進めています。もう一つは、権限分離です。モデルには「やりたいこと」を考えさせ、実際に許可するかどうかは別の policy layer で決める。
この分離がないと、賢くなるほど危なくなります。

4. コンテキストは貯めるものではなく、編集するものだ

長い context window は便利です。
でも長いことと、使えることは別です。

「Lost in the Middle」は、重要情報が文脈の先頭や末尾にあるときに性能が高く、中間に沈むと有意に落ちることを示しました。
OpenAI も AGENTS.md を巨大化させると task や relevant docs を押しのけると書き、Anthropic も large files を丸ごと読むのではなく grep や tail で必要部分だけ引く実践を示しています。
したがって production の context engineering は、全部渡すことではなく、何を残し、何を落とし、どこへ配置するかを決める編集行為です。

この原則を守ると、設計は変わります。
巨大な運用マニュアルを毎ターン渡すのではなく、短い入口を渡し、その先は agent に探させる。
OpenAI は短い AGENTS.md を table of contents として使い、詳細は repo 内 docs に逃がしています。
Perplexity の Presets も、使い道ごとに tools・steps・token budgets を絞り込んだ管理済み設定です。
良い harness は情報を足すより、ノイズを減らす。