Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【ITニュース解説】AI agent tool schemas cut 47%: the duplicate YAML key that disabled nothing

2026年10月15日に「Dev.to」が公開したITニュース「AI agent tool schemas cut 47%: the duplicate YAML key that disabled nothing」について初心者にもわかりやすく解説しています。

作成日: 更新日:

ITニュース概要

AIエージェントの処理遅延は、使わないツールの情報がプロンプトを肥大化させていたのが原因だった。不要ツールを削減し高速化したが、YAML設定の重複キーやCLIでの入力ミスで、変更が適用されない落とし穴があった。設定変更時はgrepではなく実際にパースして確認し、効果を測定することが重要だ。

ITニュース解説

AIエージェントのパフォーマンス問題は、多くのシステム開発現場で遭遇する課題の一つだ。今回のケースでは、自己ホスト型AIエージェントの動作が非常に遅く、開発者は当初、AIモデルそのものに原因があると考えていた。しかし、詳細な調査の結果、問題の根源は別のところにあった。

このAIエージェントは、様々な専門分野を持つプロファイル(コーダー、レビューアー、セキュリティなど)ごとに設定され、6GBのGPUを搭載したローカルマシン上で動いていた。エージェントが処理を一度行うのに1分半以上もかかっており、この遅延の責任がAIモデルにあると疑うのは自然なことだった。だが、いくつかの代替モデルを試しても状況は改善せず、モデルの性能だけではこの遅延を説明できないことが判明した。

特に時間がかかっていたのは、「prefill」と呼ばれる処理だった。これは、AIモデルが応答を生成する前の段階で、プロンプト、つまりAIへの指示や情報全体を処理するフェーズを指す。このprefillの段階で、AIエージェントは自身の持つ「ツール」に関する情報を大量にモデルに送り続けていたのだ。具体的には、約18,400ものプロンプトトークンのうち、実に13,541トークン、つまり74%が、エージェントが利用できる27個のツールの詳細な説明(JSONスキーマ形式)で占められていた。これらのツールスキーマは、各エージェントプロファイルの固定プロンプトの約58%から67%を構成しており、これが毎回、AIが思考を始める前に大量の時間を消費していた。

この分析により、ボトルネックはAIモデルの性能そのものではなく、AIエージェントが自身に与えられたツールリストを過剰に詳細に説明している点にあることが明らかになった。そこで、解決策はモデルの交換ではなく、ツールリストの最適化、つまり不要なツールを削減することに焦点を移した。

まず、現状を正確に把握するために、Hermesエージェントに搭載されているprompt-size --jsonコマンドを使った。このコマンドは、エージェントがAIモデルに送る固定プロンプトの内訳を詳細に示してくれる。システムプロンプト、スキルインデックス、メモリ、そしてツール数とスキーマの合計バイト数、さらにツールセットごとの内訳までが明らかになる。より正確なトークン数を把握するためには、Ollamaというツールを使って、実際のテキストからプロンプトが何トークンになるかを測定した。これにより、prompt-sizeコマンドで得られるバイト数を実際のトークン数に変換する目安を得ることができた。また、以前から構築していた「ワイヤーキャプチャリグ」という仕組みも活用した。これは、エージェントがOpenAI互換のエンドポイントとやり取りする際に、送受信されるデータをすべて記録するもので、実際にどのような情報がモデルに送られているかを視覚的に確認できた。

次に、どのツールを削減すべきかを決定する段階に入った。単なる推測でツールを削除するのではなく、エージェントが実際にどのツールをどれだけ使っているかをデータに基づいて判断した。Hermesエージェントは、各プロファイルのメッセージ履歴をローカルのSQLiteデータベースに保存している。この履歴、約1,900メッセージを分析し、各ツールの呼び出し回数をカウントした。その結果、「browser_*」という一連のブラウザ関連ツール、text_to_speech(音声合成)、clarify(明確化)、processといったツールは一度も呼び出されていないことが判明した。また、session_searchとdelegate_taskは使用されていたが、これらはデフォルトの「チーフオブスタッフ」プロファイルのみが限定的に利用していた。

この明確なデータに基づき、各プロファイルで無効化するツールのリストを作成した。例えば、専門家プロファイルからはbrowserツール群、tts、clarify、session_search、delegationを削除し、デフォルトプロファイルからはttsのみを削除するといった具合だ。ただし、注意が必要な点として、browserツールセットの中にはweb_searchという重要な機能も含まれていた。テストの結果、web_searchはコアツールとして保護されており、browserツールセットを無効化してもweb_searchは残ることが確認できたため、安心して削減を進めることができた。

ツールの無効化は、各プロファイルのコンフィグレーションファイルで行う。設定項目はagent.disabled_toolsetsで、これに無効化したいツールのリストを記述する。しかし、ここで二つの大きな落とし穴に直面した。

一つ目の落とし穴は、「重複したYAMLキー」だった。YAMLは設定ファイルを記述するための一般的な形式だが、このファイルにagent.disabled_toolsets: []という行が既に存在していたにもかかわらず、その下に新しくagent: disabled_toolsets: [browser, tts, ...]と追加してしまったのだ。YAMLの仕様では、同じキーが複数回記述された場合、通常は最後に記述された値が有効になる。今回のケースでは、既存の空のリストが後に書かれていたため、追加したはずの新しい無効化リストは無視され、結果として何も変更されていなかった。grepコマンドでファイルの内容を確認した際には、新しく追加した行が確かに存在するように見えたため、問題に気づくのが遅れた。この問題の解決策は、grep -cコマンドで目的のキーが既に存在するかを確認し、存在する場合は既存の行を編集すること、そしてpython3 -c "import yaml; print(yaml.safe_load(open('config.yaml'))['agent']['disabled_toolsets'])"のように、実際にYAMLパーサーを通して設定がどのように読み込まれるかを確認することだった。

二つ目の落とし穴は、「CLI(コマンドラインインターフェース)でのリスト書き込み」の制約だった。手動でのファイル編集を避けるため、hermes config set agent.disabled_toolsets '["browser","tts"]'というコマンドで設定を試みた。しかし、このコマンドは値を単一の引用符で囲まれた文字列としてファイルに書き込んでしまった。つまり、disabled_toolsets: '["browser","tts"]'という形になり、エージェントが期待するYAMLのリスト形式ではなかったため、この設定も無視され、ツールは無効化されなかった。リスト形式の値を設定するには、結局は手動でファイルを編集し、正しいYAMLシーケンスとして記述する必要があった。

これらの二つの落とし穴は、「設定は変更されたように見えるが、実際には何も変わっておらず、システムもエラーを報告しない」という共通の性質を持っていた。このような状況では、実際に変更後のシステム挙動や性能を測定することだけが、問題の有無を確認する唯一の方法となる。

実際にツール削減を実施した後の効果は劇的だった。prompt-sizeコマンドでの測定結果を見ると、専門家プロファイル(5つ)では、ツールの数が27個から13個に半減し、ツールスキーマのバイト数は46,403バイトから24,795バイトへと、実に47%も削減された。これにより、固定プロンプト全体のバイト数も80,057バイトから58,262バイトへと27%削減された。これは、各専門家エージェントの処理ごとに約5,400トークンの削減に相当し、測定されたprefill速度で換算すると、ターンあたり約9秒の処理時間短縮に繋がった。

変更後も、システムは問題なく動作することを確認した。重要な機能、例えばゲートウェイの稼働、コーダーエージェントによるターミナルコマンドの実行、MCPサーバーへのアクセスなどは、ツール削減後も正常に機能していた。デフォルトプロファイルではweb searchやdelegationが引き続き利用可能であり、事前にすべてのファイルをバックアップしていたため、万が一問題が発生した場合でも容易に元の状態に戻せる準備が整っていた。

この経験から、いくつかの重要な教訓が得られた。まず、AIモデルのパフォーマンスが悪いと感じたとき、すぐにモデルを疑うのではなく、まずプロンプトの内容を測定し、どこにボトルネックがあるのかを特定することが重要だ。特に、リソースが限られたGPU環境では、prefillの時間が全体を支配しやすく、ツールスキーマがその大部分を占める可能性がある。次に、ツールの削減は、推測ではなく、メッセージ履歴などの記録された使用状況に基づいて行うべきだ。ゼロ回しか呼び出されていないツールがあれば、それは明確な削減の信号となる。さらに、設定ファイルを編集する際は、grepのようなテキスト検索ツールで確認するだけでなく、必ずYAMLパーサーを通して実際にどのように解釈されるかを検証する必要がある。重複したYAMLキーはエラーを出さずに意図しない結果を招くことがあるからだ。CLIでリスト形式の値を設定する際も、それが正しくYAMLシーケンスとして書き込まれるかを確認する必要がある。最後に、どのような変更を行った後も、必ず再度測定を行い、その変更が意図した結果をもたらしたかどうかを確認することが不可欠だ。数値が減ることだけが、変更が実際に適用された唯一の証明となる。

この一連のプロセスは、AIエージェントの最適化だけでなく、一般的なシステム開発におけるデバッグやパフォーマンス改善の原則を教えてくれる貴重な事例となった。残された課題としては、デフォルトプロファイルに存在する、まだ呼び出されていないもののdisabled_toolsetsで制御できないメモリー統合ツール群の扱いなどがある。これらは製品としての機能の一部であるため、単なる削減ではなく、より上位の意思決定が必要になるだろう。また、残りの固定プロンプトの大部分を占めるシステムプロンプトやスキルインデックスも、今後の最適化の対象となる可能性を秘めている。

関連コンテンツ

関連IT用語