Outsider Notes

中級向け

エージェントハーネスとは

エージェントハーネスは、AI モデルの外側で、道具・手順・許可・やりとりの記録を受け持つ仕組みです。Anthropic は、Claude Code を動かしている仕組みをこう呼んでいます。

同じモデル（Claude Haiku 4.5）・同じデータで、n8n の「手順を組む」と「AI Agent ノード」を比べたら、ハーネスが違うだけで、費用は約3倍になり、空き枠があるお客様を断る回も出ました。

ハーネスが毎回送っているもの、渡している権限、業務でどれを選ぶかの順番を書きます。

公開

先に結論を書きます。AI エージェントの出来は、モデルだけでは決まりません。モデルの周りの仕組み（ハーネス）を変えただけで、同じモデルでも、費用も正確さも変わりました。 業務で AI エージェントを選ぶときは、モデルより先に、ハーネスを見ます。

約28秒の予告編（音声あり。音声：VOICEVOX:雨晴はう）

この記事では、資料を読んだだけのこと（言葉の定義）と、自分で動かして測ったこと（費用と正確さ）を、分けて書きます。

エージェントハーネスとは：モデルの外側の仕組み

ここは、公式の資料を読んだだけの内容です。

Anthropic は、Claude Code を動かしている仕組みを「agent harness」（エージェントハーネス）と呼んでいます。Claude Code の SDK を Claude Agent SDK に改名したときの公式ブログに、「Claude Code を動かしているエージェントハーネスは、ほかの種類のエージェントも動かせる」という文があります（Building agents with the Claude Agent SDK、2025年9月29日。2026年10月17日に読みました）。

同じブログでは、エージェントの動きを「情報を集める → 行動する → 結果を確かめる → 繰り返す」というループとして説明しています。そして、Agent SDK の公式ドキュメントには、Claude Code から受け継いでいる機能として、次のものが並んでいます（Agent SDK overview、同日に読みました）。

  • 組み込みの道具（ファイルの読み書き、コマンドの実行、Web の検索）
  • MCP（外の道具やデータにつなぐ仕組み）
  • 許可（どの道具を自動で動かし、どれに承認を求めるか）
  • セッション（やりとりの記録を持ち越す）
  • フック、サブエージェント、スキルなど

まとめると、モデルは「考えて、文章を書く」部分で、ハーネスはそれ以外のすべてです。どの道具を渡すか、何回まで繰り返すか、何を許可するか、これまでのやりとりをどう渡すか。解説記事では「エージェント ＝ モデル ＋ ハーネス」という式もよく使われます。

n8n で AI を動かすとき、ハーネスは3つの形がある

このサイトで使ってきた作り方を、ハーネスの見方で並べると、こうなります。

作り方 ハーネス（モデルの外側）を決めているのは AI がすること
手順を組む（n8n のワークフロー） 人。n8n の手順と分岐が、順番と道具を決める 決められた1か所で、文章を読む・書く
AI Agent ノード（n8n の部品） n8n の AI Agent ノード。道具の一覧、繰り返しの上限、記憶を持つ どの道具を、どの順で使うかを自分で決める
Claude Code ＋ n8n の MCP Claude Code。n8n は、Claude Code から使う道具の1つ ワークフローを作る、動かす、結果を読む

同じモデルでも、ハーネスで結果が変わった（実測）

ここからは、自分で動かして測った内容です。

お客様の問い合わせメール7通に返信の下書きを作る仕事を、「手順を組む」と「AI Agent ノード」で比べました。モデル（Claude Haiku 4.5）、在庫と来店枠のデータ、返信のルールは同じです（AI Agent に任せるか、手順を組むか）。

7通あたり 手順を組む AI Agent ノード
モデルの呼び出し 19回 20〜21回
入力トークン 11,410 38,476〜40,999
1通あたりの費用（1ドル150円） 約0.4円 約1.2円
空き枠があるお客様を断った 6回中0回 4回中3回
来店できない日を「予約できます」と書いた 6回中0回 4回中1回

呼び出しの回数は、ほとんど変わりません。違うのは、1回の呼び出しで、ハーネスがモデルに送っている量です。

ハーネスが毎回、モデルに送っているもの（実測）

n8n の AI Agent ノードで、何が送られているかを1回ずつ測りました（n8n AI Agent ノードの使い方）。

  • 道具を1つつなぐだけで、呼び出しのたびに578トークン増えた。 道具の説明と、道具を使わせるための指示が、毎回付く
  • 道具を呼ぶたびに、それまでのやりとりを全部送り直す。 10回繰り返すと、入力の合計は1回目の約19倍（11,494トークン）になった
  • 繰り返しの上限（初期値は10回）に当たると、エラーで止まり、途中経過は返ってこない。 それまでの費用は払い済み
  • 道具をつなぎ忘れると、AI は「道具を呼んだつもりの文字列」を書いて、成功扱いで終わった（1回だけの観察）

ハーネスが渡している権限

ハーネスは、AI に「何をしてよいか」も決めています。

Claude Code から、VPS の上の n8n に MCP でつないだとき、n8n の側には51個の道具が並んでいました。ワークフローの作成・実行のほかに、認証情報の一覧（list_credentials）や、コミュニティノードのインストール（install_community_node）もありました。許可に使ったのは n8n のオーナーのアカウントで、Claude Code は、そのアカウントでできることを、MCP を通してできるものとして扱う必要があります（VPS の n8n に Claude Code から MCP でつなぐ。使ったのは51個のうち8個だけで、ほかは試していません）。

Claude Code の側には、道具ごとに「自動で動かす」「承認を求める」を決める許可の仕組みがあります（公式ドキュメントを読んだだけで、この記事のために設定を比べてはいません）。モデルが同じでも、どの道具を渡し、どれに人の承認を挟むかで、起こりうる事故の大きさが変わります。

業務で選ぶときの順番

ここまでのことから、私は次の順で選んでいます。実測から導いた決まりではなく、私のやり方です。

  1. 手順を書き出せる仕事は、手順を組む。 「在庫の質問なら在庫を調べて答える」のように分かれ道が決まっているなら、その判断を毎回 AI にさせる理由はありません。安くて、正確でした
  2. 何をどの順に調べるかを、前もって書き出せない仕事だけ、AI Agent に任せる。 そのときは、繰り返しの上限を決め、途中経過を残す設定にして、道具は必要なものだけにします
  3. Claude Code は、作るための道具として使う。 このサイトの実例は、Claude Code で n8n のワークフローを作り、MCP で動かして結果を確かめました。毎日動く本番は、AI Agent ではなく、手順を組んだワークフローです

確認していないこと

  • Claude Code のハーネスの中身。 Claude Code が1回の呼び出しで何をどれだけ送っているかは、測っていません。測ったのは n8n の AI Agent ノードだけです
  • Claude Agent SDK と Managed Agents。 公式の資料を読んだだけで、使っていません
  • ほかのモデル。 比べたのは Claude Haiku 4.5 だけです。大きなモデルなら、AI Agent の正確さは変わるかもしれません
  • 言葉の定義。 「エージェントハーネス」は新しい言葉で、製品全体（Claude Code など）を指すことも、評価のための仕組みを指すこともあります。この記事は、Anthropic の使い方に合わせました

次に読む

次に読む