Agent ハーネス(エージェントハーネス)は、LLM の応答からツール呼び出しを取り出して実行し、結果を LLM に返す処理を繰り返す仕組みです。「LLM 呼び出し + ツール実行 + ループ制御」だけで成り立っています。この記事では、Theo が公開した実装例の考え方を、最小の Python コードで読み解きます。ここでの「ハーネス」は LLM を包む実行基盤を指し、Claude Code 固有の話ではありません。ハーネスを設計して育てる取り組み全体(ハーネスエンジニアリング)の意味と具体例は ハーネスエンジニアリングとは?AIエージェントのハーネスの意味・具体例・始め方 で扱います。Claude Code 側から見る場合は Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き を参照してください。

AGENT LOOPハーネスの中身

ハーネスは 4ステップのループを回しているだけ

履歴

毎回まるごと送る

  1. LLMに送る
  2. 応答を解析
  3. ツール実行
  4. 結果を返す
出典: 本文の最小実装(Theo の実装例の解説)

30秒でわかる Agent ハーネス

  • ・中核は、LLM の出力を解析し、ツールを実行し、結果を返すループ。
  • ・主な部品は、ツール定義、呼び出しの解析、メッセージ履歴、ループ制御の4つ。
  • ・無限ループとトークン枯渇を防ぐため、反復回数とトークン予算の両方に上限を置く。
  • ・基本を一度自前で書くと、フレームワーク選びとデバッグの判断軸ができる。

Agent ハーネスとは何か:背景と文脈

OpenAI の Function Calling や Anthropic の Tool Use など、多くの LLM プロバイダーがツール連携の機能を提供しています。外から見ると複雑な魔法のようですが、中身は順番に処理を並べたものです。

Agent ハーネスとは、LLM がツール呼び出しを判断し、実行結果をループで返して推論を続けるための基盤です。LangChain、AutoGen、CrewAI などのフレームワークは、この基盤を内部に持ち、実装の詳細を隠しています。その結果、どこで何が起きているのか分からないまま API だけ呼ぶ状況になりがちです。

OpenHands のような本格的なエージェント基盤も、この構造を応用しています。実装例を読む価値は、フレームワークの選択、トラブルシューティング、カスタマイズの判断ができるようになる点にあります。

Agent ハーネスの基本構造:4ステップのループ

動作は次の4ステップの繰り返しです。

  1. LLM にプロンプトを送る:ユーザー入力、過去の履歴、ツール定義を含める。
  2. 応答を解析する:ツール呼び出しが含まれるかを判定する。
  3. ツールを実行する:指定されたツールをパラメータ付きで実行する。
  4. 結果を返す:実行結果を新しいメッセージとして LLM に渡す。

以下は、この4ステップに上限と例外処理を加えた最小の実装です。OpenAI 形式の Chat Completions を想定しており、MODEL には利用するモデル名を入れます。ツール呼び出しが無い応答を最終回答とみなして終了します。スタブのクライアントで、ツール1回→最終回答の流れと、反復上限で止まる流れを動かして確認しています。実際の API では動かしていません。

import json

def run(client, tools, schemas, user_input, max_iterations=10, token_budget=4000):
    messages = [{"role": "user", "content": user_input}]
    used = 0
    for _ in range(max_iterations):
        res = client.chat.completions.create(
            model="MODEL", messages=messages, tools=schemas, max_tokens=500)
        used += res.usage.total_tokens
        if used > token_budget:
            return "トークン予算を超えたため停止"
        msg = res.choices[0].message
        if not msg.tool_calls:
            return msg.content
        messages.append(msg)
        for call in msg.tool_calls:
            try:
                out = tools[call.function.name](**json.loads(call.function.arguments))
            except Exception as e:
                out = f"tool error: {e}"
            messages.append({"role": "tool", "tool_call_id": call.id, "content": str(out)})
    return "反復回数の上限に達した"

ツール実行の失敗は、例外で落とさずエラー文として履歴に積みます。LLM が失敗を読んで別の手を打てるためです。

ツール定義・メッセージ履歴・ループ制御

ツール定義は、Agent が「どんなツールが使えるか」を知るためのスキーマです。OpenAI の Function Calling では次のような JSON で渡します。

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "与えられた都市の現在の天気情報を取得",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {"type": "string", "description": "都市名"},
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
      },
      "required": ["location"]
    }
  }
}

LLM はこれを見て、get_weather があり、location が必須で unit は任意だと判断します。説明文が不正確だと、誤ったツール選択や不正な引数を生む可能性が高まります。実装と説明文を一致させ、制約条件も書いてください。

メッセージ履歴は、ユーザー入力、LLM の出力(ツール呼び出し含む)、ツール実行結果の順に積み上がります。LLM は呼び出しのたびに履歴全体を受け取り、それを材料に次の手を決めます。たとえば「東京の天気から洗濯物を干せるか」と聞くと、履歴は user、assistant(get_weather の呼び出し)、tool(気温と降水確率の結果)、assistant(最終回答)の順になります。

無限ループとトークン枯渇を防ぐループ制御

LOOP GUARDS止める仕組み

ループには3つの歯止めを先に入れる

  1. 1.反復回数の上限

    実装例では最大10回で打ち切る

  2. 2.トークン予算の上限

    合計が超えたら強制終了する

  3. 3.ツールのタイムアウトと例外処理

    失敗もエラー文としてLLMに返す

出典: 本文のループ制御の実装例

ツールの結果が曖昧だと、LLM が同じツールを何度も呼び、トークン消費が急速に増える場合があります。反復回数とトークン予算の両方に上限を置き、どちらかに達したら強制終了します。上のコードの max_iterations と token_budget がその実装です。ツール側には実行時間の上限(タイムアウト)も別途必要です。

自前実装とフレームワークの比較

BUILD OR BUY自前かフレームワークか

基本は自前で一度、規模が出たらフレームワーク

自前実装

学習・プロトタイプ・特殊要件

  • すべてが見えてデバッグしやすい
  • カスタマイズの自由度が最大
  • 堅牢性は自分で作り込む

フレームワーク

LangChain・AutoGen・CrewAI など

  • ボイラープレートを減らせる
  • 内部ロジックは隠れやすい
  • チーム開発に載せやすい
出典: 本文の比較表
項目 自前実装(Theo スタイル) LangChain AutoGen CrewAI
学習曲線 低い(基本から始まる) 中~高(抽象度が高い) 高(マルチエージェント対応) 高(ロール分担の概念)
カスタマイズ性 最高(すべて自分で制御) 高(プラグイン拡張可) 中(フレームワーク依存) 中(スキーマ定義に制限)
実装時間 長い(イチから構築) 中(ボイラープレート削減) 短い(テンプレート豊富) 短い(構造化が進む)
デバッグ性 最高(すべてが見える) 中(ロギング機能あり) 中(Agent 間通信が複雑) 低(内部ロジックが隠蔽)
本番環境対応 工数あり(堅牢性確保が必要) 良い(成熟したコード) 良い(多数の本番事例) 良い(エンタープライズ向け)
推奨用途 学習・プロトタイプ・特殊要件 汎用 Agent・Chatbot マルチエージェント・議論型 組織・ワークフロー型

この表は各フレームワークの公式仕様の実測ではなく、特徴の一般的な整理です。まず自前で基本をつかみ、スケールやチーム開発の効率が要るときにフレームワークへ移る流れが無理のない順序です。主要フレームワークの違いは AIエージェントフレームワーク比較2026 にまとめています。

実務への影響

実装を読めるようになると、次の3点が変わります。

・トラブルシューティング:「なぜこの判断をしたか」を履歴から追え、問題箇所を特定しやすくなる。
・カスタマイズ:フレームワーク内部の動きが分かり、独自機能や最適化を入れやすくなる。
・選定:Tool 定義の粒度、エラー処理の方針、コンテキスト管理を理解したうえで決められる。

自前実装では、セキュリティも自分で見ます。確認したいのは次の4点です。

自前ハーネスのセキュリティ確認

  • ・Tool パラメータの検証(LLM が意図しない値を渡す可能性がある)。
  • ・Tool 実行のサンドボックス化。悪意のある呼び出しを防ぐため。
  • ・API キーなどの秘密情報を、メッセージ履歴に入れない。
  • ・Tool 呼び出し頻度の上限(レート制限)。

このループを本番で長く回すための設計パターン(作る役と確かめる役の分離、失敗をルールに変えるラチェット原則)は、AIエージェントのハーネス設計パターン が続きです。

まとめ

この記事の結論

  • ・Agent ハーネスは「LLM 呼び出し + ツール実行 + ループ制御」の組み合わせ。
  • ・ツール定義の精度と、反復回数・トークンの上限が品質と安全性を左右する。
  • ・基本を自前で理解してから、フレームワークを選ぶ。

Theo の実装例は、ブラックボックスに見えたエージェントの仕組みを、読める形に開いてくれます。ここでの比較表とコードは、その考え方を整理したものです。

参照ソース