コンテンツにスキップ

Guide

Cookbook

Reference

Concepts

ツール使用スキーム

agent のツールを LLM にどのように見せるか、そして LLM の呼び出しをディスパッチされたアクションに戻す方法は、プラガブルなスキームです。Reyn は 4 種類を同梱しており、reyn.yaml でレイヤーごとに 1 つを選択します。デフォルトは chat レイヤーが enumerate-all、step / phase が universal-category です。レイヤーごとに別のスキームに切り替えられます。

重要な不変条件：スキームは LLM 向けのサーフェスのみを変更します。どのスキームが生成したツール呼び出しであっても、同一の OS ゲート（除外チェック → パーミッションチェック → ディスパッチ）を通ります。スキームを変えても許可される内容は変わらず、LLM への表現方法だけが変わります。詳細はパーミッションモデルを参照してください。

4 つのスキーム

横断的な知見（H1）：ツール名の可視性が呼び出し成功率を左右します。呼び出し可能な名前を LLM 向けサーフェスに直接置くスキーム（enumerate-all、CodeAct）はモデルが推測なしに呼び出せます。名前を迂回路の後に置くスキーム（universal-category の discover→invoke、retrieval の search-first）はホットリスト外のツールで名前幻覚を誘発します。これが chat デフォルトを enumerate-all に変更した理由です。

enumerate-all（chat デフォルト）

使用できるすべてのツールをフラットに LLM のツールリストに提示し、名前でディスパッチします。発見の迂回路のないシンプルなネイティブ JSON ベースラインです。chat レイヤーのデフォルト：アクションをフラットに列挙することで LLM が直接呼び出せるようになり、discover-then-call の迂回路が誘発していた invoke_action の名前幻覚が解消されます（chat パスで非ホットリストのツール使用が ~30%→100% に改善）。tool_use.chat を未設定のままにするとこのスキームが使われます。

使いどころ： chat のデフォルト。直接的で決定論的な名前→ディスパッチ。トレードオフは可視性コストであり、弱いモデルへのペナルティではありません：カタログが大きくなると（H1 では ~67 ツール ≈ ~50KB のツールサーフェス、universal-category の ~3.2 倍）リクエストサイズが線形増加します。この可視性こそが弱いモデルのツール使用を改善する要因であり、コストはトークンであって、非常に大きなカタログでのみ問題になります（universal-category を参照）。

universal-category

ユニバーサルアクションカタログ：スキル、MCP ツール、メモリエントリ、ファイル op、インデックス済みコーパスがすべて単一の修飾名でアドレス指定でき、少数の固定ラッパー（discover → describe → invoke）経由で到達します。LLM 向けのツールリストはカタログが成長しても一定のままです。step / phase レイヤーのデフォルト。tool_use.chat: universal-category を設定すると chat でも使えます。

使いどころ： ツールセットが非常に大きく / 高速に成長しており、すべてのアクションをフラットに列挙するとリクエストのトークンコストが高くなりすぎる場合。ラッパーで LLM 向けツールリストが一定に保たれます。

retrieval

ツール上の RAG。カタログ全体を提示する代わりに検索ツールを提示し、LLM が検索するとマッチしたアクションだけが呼び出し可能なツールとして再提示されます。action_retrieval.embedding_class に設定済みの埋め込みプロバイダーが必要です（検索はセマンティック）。マッチングがセマンティックなため品質は埋め込みインデックスに依存し、安定した well-indexed カタログに適しています。

使いどころ： ツールセットが非常に大きく、全件を提示するとトークンコストが大きすぎる場合。検索で候補を絞ってから呼び出します。

測定結果（弱モデル 4-way リフレッシュ）： retrieval は単一ステップの読み取りや read→transform→write チェーンではクリーンです。しかし読み取りが多いマルチファイルタスクでは、弱いモデルが順次ファイルを読み、ラウンドごとの search→re-present オーバーヘッドで遅くなります（タイムアウト傾向）。正確だが遅いという特性でありチューニングコストです（上限なしなら同じタスクを完了します）。よって retrieval はカタログスケールの opt-in であり、弱モデルのデフォルト代替ではありません：enumerate-all が弱モデルの chat デフォルトのまま（比較でタスク完了率最高・最速終了）です。

CodeAct

コードとしてのツール。LLM が短い Python スニペットを書き、ツール呼び出しはコード内の tool(...) 呼び出しとして行われます。スニペットはサンドボックス化されたサブプロセスで実行され、各コード内呼び出しは JSON ツール呼び出しと同一のパーミッションゲートをラウンドトリップします。CodeAct の呼び出しは同等の JSON 呼び出し以上に厳格なゲートを通り、さらにサンドボックスの封じ込めが加わります。

使いどころ： 弱い / 低コストモデルを実行する場合。ツール使用をコードとして表現することが JSON ツール呼び出しを有意に上回るモデルに対して。

レイヤーごとの選択

スキームは agent が実行する 3 つのレイヤーごとに独立して選択されます：

# reyn.yaml
tool_use:
  chat: enumerate-all         # トップレベル chat ルーター（デフォルト）
  step: universal-category    # プラン / スキルステップ（デフォルト）
  phase: universal-category   # OS フェーズ（デフォルト）

どのレイヤーでも登録済みのスキームを使えます。他のレイヤーには影響しません。完全なキーリファレンス：reyn.yaml § tool_use。

スワップが安全な理由

スキームは表現とパースのみです。プラガブルなデータとして OS が読み込みます。本質的な部分はスキームの一部ではありません：

  • LLM は OS が有効化したツール（候補セット）のみ呼び出せます。スキームはそれを広げることはできません。
  • すべての呼び出しはディスパッチ前に除外 + パーミッションゲートを通ります。
  • 呼び出しとその結果の検証は変更されません。

つまり enumerate-all、retrieval、CodeAct の選択はモデルのツール使用方法を変えるのみであり、許可されることは変わりません。表現は変わってもゲートは一定です。

参照

On this page