AI 開発

AI Coding Agent の Agent Harness とは何か：Model、Harness、Tools、JSON State で読む 2026 の Agent アーキテクチャ

JSONSort 公開 2026-09-28 更新 2026-09-28 約 16 分

DeepSeek の稿は一製品の宿主を書いた。本稿は汎用の四層だけを割る：Model、Harness、Tools、JSON State。モデルが引数を埋める。宿主が環を回す。ツールは Schema を通る。状態は再生できる。

読む前の早見

層	何を鎖すか	誰が実行するか
Model	tool_use / arguments	モデルが JSON を埋める。副作用は走らせない
Harness	環 / 権限 / 圧縮	宿主が文脈を組み、実行する
Tools	inputSchema	Schema が門。宿主が呼ぶ
State	session / turn / JSONL	再建できねば状態ではない

四層は対象だ。Prompt はアーキテクチャではない。

Harness は環であり、モデルではない

2026 の Coding Agent は「一つのモデルが倉庫を直している」ように見える。割ると四つの対象になる。モデルが出すのは次の動作の JSON だけだ。文脈を載せ、Schema を通し、権限を評し、ツールを走らせ、結果を書き戻し、窓が満杯に近づくと履歴を圧縮するのは Harness だ。この環が無ければ、モデルは会話でしかない。Claude Code 公式は同じ事実を環として書く：提示を受け、評し、ツールを実行し、また評し、ツール呼び出しが無くなるまで続ける。Codex は連続性を Thread とセッション記録へ書く。Cursor も宿主の環だ。モデルがディスクに触れるのではない。

Model：lookup_order と A-1042 を埋めるだけ。ソケットは見えず、過程も生まない。
Harness：システム提示、ツール表、権限、圧縮、予算、max_turns。それは宿主の状態であり、モデルの重みではない。
Tools と State：ツールには Schema がある。セッションには点検できる JSON がある。会話文は状態ではない。

組み込みツールが JSON をどう埋めるかは AI Coding Agent と JSON ツール呼び出し。MCP の一跳びは Coding Agent は MCP をどう呼ぶか。Schema が門である理由は AI に JSON Schema が必要な理由。一製品のプラグイン宿主は DeepSeek Harness の稿。本稿はその製品を語り直さない。四層の重ね方だけ書く。

第一層：Model は JSON だけ埋める

モデルが見るのは、宿主が出したツール表と、ここまでのメッセージだ。出力はテキストか、ツール呼び出しか、両方だ。架空の照会。本物の秘密は貼らない：

{
  "type": "tool_use",
  "id": "call_3c91",
  "name": "lookup_order",
  "input": { "order_id": "A-1042" }
}

この対象は HTTP ではない。MCP の tools/call でもない。モデルが宿主へ「A-1042 を調べて」と伝えることだ。宿主が形を確かめてから実行か阻止を決める。モデルを実行器だと思うと、その跳びを落とす。

第二層：Harness が環を回す

セッションは状態機械であり、一回の補完ではない。公式の環は一枚の対象に収まる。不変なのはモデル名とツール表。可変なのはメッセージ数、待ちツール、予算。2 から 8 への輪は宿主が数えている。モデルが日記を書いているのではない：

{
  "session_id": "sess_7f2a",
  "turn": 2,
  "max_turns": 8,
  "immutable": {
    "model": "coding-agent",
    "tools": ["lookup_order", "Read", "Bash"]
  },
  "mutable": {
    "messages": 6,
    "pending_tool": "lookup_order",
    "budget_tokens": 128000
  }
}

Claude Code の一巡：モデルがツール付きの返信を出し、宿主が実行し、tool_result を書き戻し、また尋ねる。ツール呼び出しが無いと環は終わり、使用量と session_id を渡す。フックは実行前に遮れる。Codex は承認のあと砂箱を選び、実行する。権限を規則として書く話は Coding Agent の権限モデル。Harness は権限を呼ぶ。権限そのものではない。

第三層：Tools は Schema を通る

ツール表はモデルの献立だ。各行に名前、説明、JSON Schema が要る。広い object は鍵の発明を招く。照会に返金の欄を載せない：

{
  "name": "lookup_order",
  "description": "Look up an order by ID. Confirm before any refund.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

門を通したあと、宿主が実行し、結果を対象として戻す。モデルが読むのは書き戻しであり、端末の巻戻しではない。失敗も対象だ。散文の一文だけを捨てない：

{
  "type": "tool_result",
  "tool_use_id": "call_3c91",
  "content": "{\"order_id\":\"A-1042\",\"status\":\"paid\"}"
}

第四層：JSON State は再生できる

状態は「さっき何を話したか」ではない。状態はメッセージ、ツール結果、セッション番号、圧縮の境界だ。Codex はセッションを JSONL へ追加し、resume で記録から再建する。一行でどの照会かを指せねばならない：

{"ts":"2026-09-28T01:12:04.221Z","type":"tool_result","id":"call_3c91","name":"lookup_order","ok":true,"order_id":"A-1042"}

文脈は満杯になる。Claude Code は上限の近くで自動圧縮し、流れに compact_boundary を出す。初期の細部は要約に食われることがある。プロジェクト根の CLAUDE.md は再注入される。残すべき規則はファイルへ書け。最初の提示だけに書くな。圧縮は状態の遷移であり、静かな忘却ではない：

{
  "type": "system",
  "subtype": "compact_boundary",
  "session_id": "sess_7f2a"
}

Harness を対象にする五手順

「より強いモデルへ換える」から始めない。対象を書く：

まずツール表を列ぶ。各ツールに Schema。additionalProperties: false。Schema の無いツールはモデルへ渡さない。
環の停止条件を書く。max_turns か予算。開口の仕事を裸で走らせない。
権限を規則として書く。読み取りの照会は allow。書き込みは ask。返金は deny。「すべて自動承認」を既定にしない。
状態を JSON として残す。少なくとも tool_use、tool_result、session_id。id が揃えば環は通っている。
圧縮を事象として扱う。compact は要約が古いメッセージを置き換えた印だ。残すべき規則はディスクのファイルへ。

Schema を門にする話は Agents API + JSON Schema。本稿が求めるのは、四層が対象であり、宿主が副作用を走らせることだ。

Agent を見直すなら、四つの JSON を広げる

失敗の多くは、ツール表、権限、状態が揃っていないことだ。モデルが「賢くない」ことではない。

inputSchema と input を整形し、欠けと余分な鍵を見る。
JSONPath 抽出で $.name、$.input.order_id、$.session_id を抜く。
成功した書き戻しと拒まれた呼び出しを JSON Diff。Schema と規則を先に直し、指示は後。
call_3c91 が tool_use と tool_result で同じ id かを照らす。
セッション JSONL、トークン、倉庫の道を公開フォーマッタに貼らない。JSONSort はブラウザ内で動く。

四つの対象が Schema で再建できて初めて、アーキテクチャを集めている。「ファイルを直したように見えた」を集めているのではない。

よくある落とし穴

Harness を新しいモデルだと思う。モデルは代わる。環、門、状態を先に安定させる。評定のずれはここから始まる。
長い system prompt をアーキテクチャだと思う。提示は圧縮に食われる。ツール表、権限、セッション記録は食われない。
Schema を飛ばして実行する。Harness は環を持つ。二度目の検証を免除しない。広い object は発明された鍵を副作用へ送る。
会話窓を状態だと思う。窓は描画だ。状態は JSON だ。resume が読むのは記録であり、スクリーンショットではない。
圧縮を何事も無かったと思う。公式は境界の事象を出す。入れ子の規則は、ファイルを読み直すまで戻らないことがある。
一製品のプラグイン語を汎用語にする。dsh と Capability Seam はその稿の対象だ。汎用の四層は Model / Harness / Tools / State だ。

FAQ

Harness と Agent Framework は同じか？

同じ層ではない。Framework は業務倉庫の中で節を編むことが多い。Harness は宿主の環だ：文脈を載せ、門を通し、実行し、状態を残す。Harness の上に業務 Agent を書いてよい。二層を混ぜない。

モデルは自分でファイルを直すか？

直さない。モデルが埋めるのはツール JSON だけだ。読み書き、Shell、MCP は宿主が実行する。宿主が無ければ倉庫は変わらない。

JSON State は JSONL でなければならないか？

必須ではない。Codex はセッション JSONL を権威の記録にする。Claude Code はセッション文書と事象の流れを使う。要るのは、id で当時のモデルが見た対象を再建できることだ。接尾辞ではない。

圧縮は Schema を落とすか？

ツール定義は安定した接頭として再注入されることが多い。落ちるのは初期の会話の細部だ。残すべき規則はプロジェクトのファイルへ書け。最初の利用者メッセージだけに書くな。

モデルを換えたら Harness を書き直すか？

書き直すべきではない。モデルの適応器は換えられる。ツール Schema、権限表、状態の形は先に据える。モデルの交換は JSON を埋める層の交換であり、四層の交換ではない。

結論

Coding Agent のアーキテクチャは「より大きなモデル」ではない。Model が JSON を埋め、Harness が環を回し、Tools が Schema を通り、State が再生できることだ。

A-1042 がどのツール、どの輪、どの状態記録へ入るかを先に書く。四層の対象を指せれば、Harness はある。モデルは代わる。四層を先に安定させる。

続きを読む

DeepSeek Harness は何を変えたか一製品の宿主。汎用の四層ではない
Coding Agent は MCP をどう呼ぶか宿主が JSON-RPC を送り、モデルは引数だけ埋める
Coding Agent に権限制御が必要な理由 Shell / Git / ファイルシステムの三門
AI Coding Agent は JSON でどうツールを呼ぶか組み込みツールの JSON。まだ環は割っていない
Agents API + JSON Schema 実践安定、検証、実行
AI に JSON Schema が必要な理由 Schema / Function Calling / Structured Output
JSONSort のローカル道具箱整形、検証、Diff
すべての記事 JSON と AI 開発のメモ

更新記録： 2026-09-28 初回公開