300件のエージェント失敗ログを調べた。問題はプロンプトではなかった。

300件のエージェント失敗ログを2週間かけて調べ、それぞれの根本原因をタグ付けしていきました。結果は予想外でした。プロンプトの問題は全体の約12%にすぎず、残りはすべてコンテキストの汚染、オーバーフロー、または欠如が原因でした。モデルを変えても解決しませんでした。ツールを変えても同じでした。このパターンは一貫していました。

コンテキストエンジニアリングにはずっと深く関わってきたので、Agent Skills for Context EngineeringというオープンソースプロジェクトがGitHubスター1万件を突破したとき、すぐに注目しました。MITライセンスで、Muratcan Koylanというコンテキストエンジニアが開発し、北京大学のAIラボの論文でも引用されています。最後の点が、実際にクローンする決め手になりました。

コンテキストウィンドウは小さいほど精度が上がる

トークンをたくさん詰め込めば込むほど良いと思っていました。これは間違いでした。このスキルセットが最初に教えるのは「情報の量ではなく、情報の密度」という原則です。

コンテキストが長くなるほど、モデルは中間部分の内容を見失います。これはU字カーブ効果と呼ばれるもので、モデルは先頭と末尾はうまく読めますが、その間はざっと流し読みします。実際に128Kトークンまでコンテキストを埋めてから、同じ情報を32Kに圧縮して比較してみました。圧縮したほうが精度スコアで上回りました。

処理コストはトークン数に対して線形ではなく指数的に増加します。コンテキストを半分に削ると、レスポンスのレイテンシが40〜60%短縮されました。プレフィックスキャッシングを使っても、長い入力はコストがかさみます。一言でまとめると、決められたトークン予算の中にどれだけ有用な情報を詰め込めるかが重要です。

ツールの説明文がエージェントのパフォーマンスの80%を決める

完璧なプロンプトを書いても、ツールの説明が雑だとエージェントは間違ったツールを選びます。このスキルセットは「ツールは人間ではなくLLMが読む契約書だ」と的確に表現しています。チームでMCPサーバーを構築したとき、このガイドに沿ってツールの説明文を書き直しました。その結果、ツール選択の失敗が目に見えて減りました。

各ツールの説明には、いつ使うのか、何を返すのかを明示する必要があります。2つのツールの機能が重複していると、人間でも混乱しますが、エージェントはさらに混乱します。機能を絞った複数のツールより、包括的な1つのツールのほうが大抵うまくいきます。そしてエラーメッセージは、何が問題だったかだけでなく、次に何をすべきかをエージェントに伝える必要があります。

マルチエージェントシステムはエージェントより先にアーキテクチャが必要

複数のエージェントを立ち上げ、自動的に協調してくれると期待するのは夢物語です。このリポジトリでは3つのパターンが明確に定義されています。オーケストレーターが配下のエージェントを指揮するパターン、エージェントが対等に通信するピアツーピアモデル、そして階層的な委任チェーンです。

3つすべてを本番環境で試した結果、オーケストレーターパターンが最も予測可能でデバッグしやすいことが分かりました。配下のエージェントはファイルシステムを通じて結果を渡します。ピアツーピアモデルはクリエイティブなタスクには向いていましたが、無限ループのリスクがありました。構造化されたクエリでは、ベクトル検索よりも共有ファイルのほうが効果的でした。実際に使ってみると、安定して動作する上限はエージェント3体でした。

ベクトル検索だけではメモリを扱えない

ベクトル検索は「顧客Xが商品Yを日付Zに購入した」という情報は簡単に見つけられます。しかし「商品Yを購入した顧客が他に何を買ったか」という問いには答えられません。関係性の情報はエンベディングの中で失われてしまいます。

このスキルセットは4層のメモリアーキテクチャを提案しています。コンテキストウィンドウ内のワーキングメモリ、セッション内のショートタームメモリ、セッションをまたぐロングタームメモリ、そしてアーカイブとしての永続メモリです。実際に試した中で最も実用的だったのは、ファイルシステムをメモリとして使うパターンです。エンベディングクエリの代わりにlsやgrepでコンテキストを探索します。ツールの実行結果をスクラッチパッドファイルに書き出すことで、コンテキストウィンドウの消費を大幅に抑えられました。

評価はエージェント開発で最も軽視されているスキル

ほぼスキップしそうになったセクションが、結局最も有益でした。このリポジトリにはLLMをジャッジとして使うTypeScriptの評価フレームワークが含まれており、採点ルーブリックを自動生成することもできます。

特に印象的だったのが、ポジションバイアスへの対策です。2つの回答を並べて比較する際、順番を入れ替えて2回評価します。これにより、最初に表示された回答を有利に評価してしまう傾向を打ち消します。直接採点とペアワイズ比較の両方に対応しています。評価パイプラインを構築したことで、プロンプトの変更が実際にパフォーマンスを改善したのかを、勘に頼らず測定できるようになりました。

1点、このリポジトリが解決していないことがあります。評価ルーブリックは最終的に人間によるキャリブレーションが必要です。自動生成されたルーブリックは出発点としては十分でしたが、結果が信頼できるものになるまでは、自分のドメインに合わせて採点の重みを調整しなければなりませんでした。

エージェントが間違いを犯したとき、モデルを責める前にコンテキストを確認してください。リポジトリはこちらです。