HuggingFace が「Is it agentic enough? Benchmarking open models on your own tooling」という記事を出した（2026/6/18）。これが意味するのは、モデルが自分のツール環境でどれだけ動くかを自分で測れ、という話だ。

ただ、自分が現場でハマったのはそこじゃない。ベンチマークはモデルの賢さを測る。でもエージェントが本番で落ちるバグの大半は、モデルじゃなくて自分のループ側にある。引数を取り違える、ツールのエラーをモデルに戻し忘れる、止まらない。これはベンチを何回回しても出てこない。

Q. なぜエージェントのテストは書きにくいのか

毎回モデルを叩くからだ。遅いし、課金されるし、同じ入力でも出力が揺れる。非決定的なものを CI に乗せると、たまに落ちるテストになって誰も信じなくなる。

解決は単純で、LLM クライアントを細い抽象にして、テストのときだけ台本（スクリプト）に差し替える。

ループ側を抽象に依存させる

エージェント本体が依存するのは「messages を渡したら次の一手が返る」という1メソッドだけにする。

# agent.py
from dataclasses import dataclass
from typing import Callable, Protocol

@dataclass
class ToolCall:
    name: str
    args: dict

@dataclass
class Step:               # モデルの1ターン。tool_call が無ければ最終回答
    text: str | None = None
    tool_call: ToolCall | None = None

class LLM(Protocol):
    def respond(self, messages: list[dict]) -> Step: ...

class AgentError(RuntimeError):
    pass

def run_agent(llm, user_input, tools: dict[str, Callable[..., str]], max_steps=6):
    messages = [{"role": "user", "content": user_input}]
    for _ in range(max_steps):
        step = llm.respond(messages)
        if step.tool_call is None:
            return step.text or ""
        call = step.tool_call
        if call.name not in tools:
            raise AgentError(f"unknown tool: {call.name}")
        try:
            result = tools[call.name](**call.args)
        except Exception as e:                 # ツール失敗もモデルに戻して回復させる
            result = f"ERROR: {e}"
        messages.append({"role": "tool", "name": call.name, "content": result})
    raise AgentError(f"max_steps={max_steps} を超えました")

本番では respond の中で実プロバイダを呼び、返ってきた tool_call を Step に詰め替えるアダプタを書く。テストはここを丸ごと差し替える。

台本フェイクを差し込む

決められた Step を順に返すだけ。渡された messages も記録しておく。

# fake_llm.py
class ScriptedLLM:
    def __init__(self, script):
        self._script = list(script)
        self.seen = []                 # 各ターンで渡された messages を保存

    def respond(self, messages):
        self.seen.append([dict(m) for m in messages])   # コピーして残す
        return self._script.pop(0)

dict(m) でコピーするのが地味に大事だ。messages はループ中に書き換わるミュータブルなリストなので、参照のまま持つと全ターンが最終状態に化けて、検査が成立しない。最初これで30分溶かした。

自分のループのバグを名指しで撃つ

# test_agent.py（抜粋）
def make_tools(log):
    return {
        "get_weather": lambda city: log.append(("get_weather", city)) or f"{city} is sunny, 22C",
        "boom": lambda: (_ for _ in ()).throw(ValueError("backend down")),
    }

class TestAgentLoop(unittest.TestCase):
    def test_calls_tool_then_answers(self):
        log = []
        llm = ScriptedLLM([
            Step(tool_call=ToolCall("get_weather", {"city": "Tokyo"})),
            Step(text="東京は晴れ、22度です。"),
        ])
        out = run_agent(llm, "東京の天気は?", make_tools(log))
        self.assertEqual(out, "東京は晴れ、22度です。")
        self.assertEqual(log, [("get_weather", "Tokyo")])   # 正しい引数で1回だけ

    def test_tool_result_is_fed_back(self):                 # 戻し忘れの検出
        llm = ScriptedLLM([Step(tool_call=ToolCall("get_weather", {"city":"Osaka"})), Step(text="done")])
        run_agent(llm, "?", make_tools([]))
        self.assertEqual(llm.seen[1][-1]["role"], "tool")
        self.assertIn("Osaka is sunny", llm.seen[1][-1]["content"])

    def test_tool_exception_becomes_error_message(self):    # 例外→回復
        llm = ScriptedLLM([Step(tool_call=ToolCall("boom", {})), Step(text="復旧")])
        run_agent(llm, "?", make_tools([]))
        self.assertIn("ERROR: backend down", llm.seen[1][-1]["content"])

    def test_infinite_loop_is_bounded(self):                # 止まらないモデルでも打ち切る
        llm = ScriptedLLM([Step(tool_call=ToolCall("get_weather", {"city":"X"}))] * 99)
        with self.assertRaises(AgentError):
            run_agent(llm, "?", make_tools([]), max_steps=4)
        self.assertEqual(len(llm.seen), 4)

手元で走らせた結果がこれ。

$ python -m unittest test_agent -v
test_calls_tool_then_answers ... ok
test_infinite_loop_is_bounded ... ok
test_tool_exception_becomes_error_message ... ok
test_tool_result_is_fed_back ... ok
test_unknown_tool_raises ... ok
----------------------------------------------------------------------
Ran 5 tests in 0.000s
OK

5本で 0.2ms、ネットワーク呼び出し 0回、課金 $0.00。標準ライブラリの unittest だけで動くので追加インストールも要らない。

Q. これで何が嬉しいのか

ここで撃っているバグを並べると、性格がはっきりする。引数を取り違えていないか。ツール結果が次ターンの messages に戻っているか。ツールが例外を投げてもモデルに渡って回復できるか。未知のツール名で死ぬか。止まらないモデルでも max_steps で打ち切れるか。

どれもモデルの賢さとは無関係だ。配線（オーケストレーション）の正しさを問うている。そして配線のバグは、自分のコードにしか無い。ベンチマークは相手のモデルを評価する道具で、自分のループのこの手のミスは絶対に映さない。役割が違う。

実運用ではこの台本テストを土台に、回帰用のシナリオを足していけばいい。「このツールが空配列を返したとき」「2回目の呼び出しで別の引数になったとき」を Step の列として書き起こすだけで、再現テストになる。バグ報告が来たら、その会話列を台本に落として赤いテストを1本作り、緑にする。モデルを1回も叩かずに、だ。

ベンチで賢さを測るのは大事だが、出荷を守るのは決定論テストのほうだと思っている。賢いモデルに替えても、戻し忘れのループは直らない。最初に作るべきは評価スクリプトより、この台本1本だった。