Agent ハーネス(エージェントハーネス)は、LLM の応答からツール呼び出しを取り出して実行し、結果を LLM に返す処理を繰り返す仕組みです。「LLM 呼び出し + ツール実行 + ループ制御」だけで成り立っています。この記事では、Theo が公開した実装例の考え方を、最小の Python コードで読み解きます。ここでの「ハーネス」は LLM を包む実行基盤を指し、Claude Code 固有の話ではありません。ハーネスを設計して育てる取り組み全体(ハーネスエンジニアリング)の意味と具体例は ハーネスエンジニアリングとは?AIエージェントのハーネスの意味・具体例・始め方 で扱います。Claude Code 側から見る場合は Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き を参照してください。
AGENT LOOPハーネスの中身
ハーネスは 4ステップのループを回しているだけ
履歴
毎回まるごと送る
- LLMに送る
- 応答を解析
- ツール実行
- 結果を返す
30秒でわかる Agent ハーネス
- ・中核は、LLM の出力を解析し、ツールを実行し、結果を返すループ。
- ・主な部品は、ツール定義、呼び出しの解析、メッセージ履歴、ループ制御の4つ。
- ・無限ループとトークン枯渇を防ぐため、反復回数とトークン予算の両方に上限を置く。
- ・基本を一度自前で書くと、フレームワーク選びとデバッグの判断軸ができる。
Agent ハーネスとは何か:背景と文脈
OpenAI の Function Calling や Anthropic の Tool Use など、多くの LLM プロバイダーがツール連携の機能を提供しています。外から見ると複雑な魔法のようですが、中身は順番に処理を並べたものです。
Agent ハーネスとは、LLM がツール呼び出しを判断し、実行結果をループで返して推論を続けるための基盤です。LangChain、AutoGen、CrewAI などのフレームワークは、この基盤を内部に持ち、実装の詳細を隠しています。その結果、どこで何が起きているのか分からないまま API だけ呼ぶ状況になりがちです。
OpenHands のような本格的なエージェント基盤も、この構造を応用しています。実装例を読む価値は、フレームワークの選択、トラブルシューティング、カスタマイズの判断ができるようになる点にあります。
Agent ハーネスの基本構造:4ステップのループ
動作は次の4ステップの繰り返しです。
- LLM にプロンプトを送る:ユーザー入力、過去の履歴、ツール定義を含める。
- 応答を解析する:ツール呼び出しが含まれるかを判定する。
- ツールを実行する:指定されたツールをパラメータ付きで実行する。
- 結果を返す:実行結果を新しいメッセージとして 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.反復回数の上限
実装例では最大10回で打ち切る
-
2.トークン予算の上限
合計が超えたら強制終了する
-
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 の実装例は、ブラックボックスに見えたエージェントの仕組みを、読める形に開いてくれます。ここでの比較表とコードは、その考え方を整理したものです。







