このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.1.2 を使用してください。

再帰アドバイザー

再帰アドバイザーとは何ですか ?

Advisors Recursive 再帰アドバイザは、下流のアドバイザチェーンを複数回ループできる特殊な型のアドバイザです。このパターンは、たとえば次のような特定の条件が満たされるまで LLM を繰り返し呼び出す必要がある場合に便利です。

呼び出す必要がなくなるまでツール呼び出しをループで実行する
構造化された出力を検証し、検証が失敗した場合は再試行する
リクエストを変更して評価ロジックを実装する
リクエストを変更して再試行ロジックを実装する

CallAdvisorChain.copy(CallAdvisor after) 法は、再帰アドバイザパターンを可能にする重要なユーティリティです。この手法は、元のチェーンで指定されたアドバイザの後に続くアドバイザのみを含む新しいアドバイザチェーンを作成し、再帰アドバイザが必要に応じてこのサブチェーンを呼び出すことを可能にします。このアプローチにより、以下のことが保証されます。

再帰アドバイザーはチェーン内の残りのアドバイザーをループすることができる
チェーンの他のアドバイザーは各反復を観測しインターセプトすることができる
アドバイザーチェーンは適切な順序と観測性を維持する
再帰アドバイザーはそれ以前に実行されたアドバイザーを再実行しない

組み込みの再帰アドバイザー

Spring AI には、このパターンを示す 2 つの組み込み再帰アドバイザーが用意されています。

ToolCallAdvisor

ToolCallAdvisor は、モデル内部のツール実行に依存するのではなく、アドバイザーチェーンの一部としてツール呼び出しループを実装します。これにより、チェーン内の他のアドバイザーがツール呼び出しプロセスをインターセプトして監視できるようになります。

主な機能:

setInternalToolExecutionEnabled(false) を設定してモデルの内部ツール実行を無効にする
ツール呼び出しがなくなるまでアドバイザーチェーンをループします
「直接返す」機能をサポート - ツール実行に returnDirect=true がある場合、ツール呼び出しループを中断し、ツール実行結果を LLM に送り返すのではなく、クライアントアプリケーションに直接返します。
callAdvisorChain.copy(this) を使用して再帰呼び出しのサブチェーンを作成します
チャットレスポンスが null になる可能性がある場合に対処するための null 安全性チェックが含まれています
conversationHistoryEnabled による設定可能な会話履歴管理をサポート

使用例:

var toolCallAdvisor = ToolCallAdvisor.builder()
    .toolCallingManager(toolCallingManager)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
    .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(toolCallAdvisor)
    .build();

会話履歴管理

ToolCallAdvisor には、ツール呼び出しの反復中に会話履歴を管理する方法を制御する conversationHistoryEnabled 構成オプションが含まれています。

デフォルト（conversationHistoryEnabled=true）では、アドバイザーはツール呼び出しの反復中に完全な会話履歴を内部的に保持します。つまり、ツール呼び出しループ内の後続の LLM 呼び出しには、以前のすべてのメッセージ（ユーザーメッセージ、アシスタントのレスポンス、ツールのレスポンス）が含まれます。

Use the .disableMemory() method to disable internal conversation history management. When disabled, only the last tool response message is passed to the next iteration. This is useful when:

You have a Chat Memory Advisor registered next in the chain that already manages conversation history
You want to reduce token usage by not duplicating history management
You’re integrating with external conversation memory systems

Example with conversation history disabled:

var toolCallAdvisor = ToolCallAdvisor.builder()
    .toolCallingManager(toolCallingManager)
    .disableMemory()  // Disable internal history - let ChatMemory handle it
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
    .build();

var chatMemoryAdvisor = MessageChatMemoryAdvisor.builder(chatMemory)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 200)  // Positioned before ToolCallAdvisor
    .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(chatMemoryAdvisor, toolCallAdvisor)
    .build();

リターンダイレクト機能

"Return Direct" 機能を使用すると、ツールは LLM をバイパスし、結果をクライアントアプリケーションに直接返すことができます。これは以下の場合に便利です。

ツールの出力は最終的な答えであり、LLM 処理を必要としない。
追加の LLM 呼び出しを回避することでレイテンシを削減したい
ツールの結果は解釈せずにそのまま返される必要があります

ツール実行に returnDirect=true がある場合、ToolCallAdvisor は次のようになります。

通常通りツール呼び出しを実行します
ToolExecutionResult 内の returnDirect フラグを検出する
ツール呼び出しループからの脱出
ツールの出力を生成コンテンツとして、ツール実行結果を ChatResponse としてクライアントアプリケーションに直接返す

StructuredOutputValidationAdvisor

StructuredOutputValidationAdvisor は、生成された JSON スキーマに対して構造化された JSON 出力を検証し、検証が失敗した場合は指定された回数まで呼び出しを再試行します。

主な機能:

予想される出力型から JSON スキーマを自動的に生成します
LLM レスポンスをスキーマに対して検証する
検証に失敗した場合、設定可能な試行回数まで呼び出しを再試行します。
LLM が出力を修正できるように、再試行時に検証エラーメッセージをプロンプトに追加します。
callAdvisorChain.copy(this) を使用して再帰呼び出しのサブチェーンを作成します
オプションで JSON 処理用のカスタム ObjectMapper をサポート

使用例:

var validationAdvisor = StructuredOutputValidationAdvisor.builder()
    .outputType(MyResponseType.class)
    .maxRepeatAttempts(3)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 1000)
    .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(validationAdvisor)
    .build();