LangChain4j ツール & 関数呼び出しパターン

LangChain4j アプリケーションで、メソッドをツールとしてアノテーションする、ツール実行器を構成する、AI サービスにツールを登録する、パラメータを検証する、ツール実行エラーを処理するためのパターンを提供します。

概要

LangChain4j は @Tool アノテーションを使用して、Java メソッドを AI エージェント用の呼び出し可能な関数として公開します。AiServices ビルダーはツールをチャットモデルに登録し、LLM がテキスト生成を超えたアクション（データベースクエリ、API 呼び出し、計算、ビジネスシステム統合）を実行できるようにします。パラメータは @P を使用して、LLM を導くための説明を指定します。

使用時機

• 外部ツール（天気、株価、データベースクエリ）を呼び出す AI エージェントを構築する
• LLM ツール使用のための関数仕様を定義する（@Tool、@P アノテーション）
• AiServices.builder().tools() でツールセットを登録・管理する
• ツール実行エラー、タイムアウト、幻覚ツール名を処理する
• @ToolMemoryId 経由でユーザー状態を注入するコンテキスト対応ツールを実装する
• 大規模または条件付きツールセット用の動的ツールプロバイダーを構成する

手順

1. @Tool でメソッドにアノテーションを付ける

@Tool アノテーション付きメソッドを持つツールクラスを定義します。最初のパラメータとして説明を指定します。各パラメータの説明に @P を使用します。

public class WeatherTools {
    private final WeatherService weatherService;

    public WeatherTools(WeatherService weatherService) {
        this.weatherService = weatherService;
    }

    @Tool("Get current weather for a city")
    public String getWeather(
            @P("City name") String city,
            @P("Temperature unit: celsius or fahrenheit") String unit) {
        return weatherService.getWeather(city, unit);
    }
}

検証: インスタンスを作成し、クラスがエラーなく読み込まれることを確認します。

2. AiServices でツールを登録する

AiServices.builder() を使用してツールインスタンスをチャットモデルに登録します。

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new Calculator(), new WeatherTools(weatherService))
    .build();

検証: assistant.chat("What is 2 + 2?") を呼び出し、LLM が例外をスローせず応答することを確認します。

3. ツール呼び出しをエンドツーエンドでテストする

ツール使用をトリガーするプロンプトを送信し、ツールが実行されて結果が組み込まれることを確認します。

String response = assistant.chat("What is the weather in Rome?");
System.out.println(response);

検証: ログでツール呼び出しを確認し、応答がツール出力を使用していることを確認します。

4. ツール実行エラーを処理する

スタックトレースを公開せずに失敗を適切に管理するエラーハンドラーを追加します。

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        logger.error("Tool '{}' failed: {}", request.name(), exception.getMessage());
        return "An error occurred while processing your request";
    })
    .hallucinatedToolNameStrategy(request ->
        ToolExecutionResultMessage.from(request,
            "Error: tool '" + request.name() + "' does not exist"))
    .toolArgumentsErrorHandler((error, context) ->
        ToolErrorHandlerResult.text("Invalid arguments: " + error.getMessage()))
    .build();

検証: エラー条件をトリガーし、LLM が安全なエラーメッセージを受け取ることを確認します。

5. パフォーマンスとスケーラビリティのために最適化する

並行ツール実行を有効にし、長時間実行ツールのタイムアウトを設定します。

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new DbTools(), new HttpTools())
    .executeToolsConcurrently(Executors.newFixedThreadPool(5))
    .toolExecutionTimeout(Duration.ofSeconds(30))
    .build();

検証: 並行リクエストを実行し、スレッド競合やデッドロックがないことを確認します。

例

完全なクラスの電卓ツール

public class Calculator {
    @Tool("Perform basic arithmetic")
    public double calculate(
            @P("Expression like 2+2 or 10*5") String expression) {
        // Parse and evaluate expression
        return eval(expression);
    }
}

Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(ChatModel.builder()
        .apiKey(System.getenv("API_KEY"))
        .model("gpt-4o")
        .build())
    .tools(new Calculator())
    .build();

即座返却ツール（LLM 応答なし）

@Tool(value = "Send email notification", returnBehavior = ReturnBehavior.IMMEDIATELY)
public void sendEmail(@P("Recipient email address") String to,
                     @P("Email subject") String subject,
                     @P("Email body") String body) {
    emailService.send(to, subject, body);
}

動的ツールプロバイダー

ToolProvider provider = request -> {
    if (request.userContext().contains("admin")) {
        return List.of(new AdminTools());
    }
    return List.of(new UserTools());
};

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .toolProvider(provider)
    .build();

ベストプラクティス

• 説明的な @Tool 名: 明確なスコープを持つ命令型動詞（"Get"、"Send"、"Calculate"）を使用する
• 正確な @P 説明: 形式、制約、有効な値を含める — 曖昧な説明は LLM の不正な呼び出しを引き起こす
• 安全なエラー処理: スタックトレースを公開しない；ユーザーフレンドリーなエラー文字列を返す
• タイムアウト構成: 外部サービス呼び出しに対して常に .toolExecutionTimeout() を設定する
• 並行実行: ツールが独立している場合は .executeToolsConcurrently() を有効にする
• 入力検証: ツールメソッド内でパラメータを検証；説明的なエラーを返す
• パーミッションチェック: AI サービスレベルではなく、ツール内で認可を実行する
• 監査ログ: デバッグとコンプライアンスのためにツール名、パラメータ、実行結果をログに記録する

一般的な問題と解決策

問題	解決策
LLM が存在しないツールを呼び出す	安全なエラーメッセージを返す .hallucinatedToolNameStrategy() を追加する
ツールが間違ったパラメータを受け取る	@P 説明を改善；.toolArgumentsErrorHandler() を追加する
ツール実行がハング状態になる	.toolExecutionTimeout(Duration.ofSeconds(N)) を設定する
外部 API からのレート制限エラー	リトライロジックまたはレート制限をツールメソッド内に追加する
LLM がツール出力を無視する	ツールが LLM が解釈できる文字列を返すことを確認する

復元力パターンは references/error-handling.md を、パラメータと戻り値の型の詳細は references/core-patterns.md を参照してください。

クイックリファレンス

アノテーション / API	目的
@Tool	メソッドを呼び出し可能なツールとしてマークする
@P	LLM のためのツールパラメータを説明する
@ToolMemoryId	会話/ユーザー ID をツールに注入する
AiServices.builder()	登録されたツールを持つ AI サービスを作成する
ReturnBehavior.IMMEDIATELY	LLM 応答を待たずにツールを実行する
ToolProvider	コンテキストに基づく動的ツール提供
executeToolsConcurrently()	独立したツール呼び出しを並列実行する
toolExecutionTimeout()	個別ツール呼び出しのタイムアウト

制約と警告

• 機密データ: @Tool や @P 説明に API キー、パスワード、認証情報を絶対に渡さない
• 副作用: データを変更するツールは説明で警告する；AI モデルは複数回呼び出す可能性がある
• 大規模ツールセット: 過剰なツールは LLM モデルを混乱させる — 条件付き登録には ToolProvider を使用する
• ブロッキング操作: ツールは長い同期 I/O をタイムアウト構成なしで実行しない
• スタックトレース公開: 例外を常に安全な文字列を返すエラーハンドラーを経由してルートする
• パラメータ精度: 曖昧な @P 説明は直接不正なツール呼び出しを引き起こす — 形式と制約について具体的に指定する
• 並行安全性: executeToolsConcurrently() を使用する場合、ツールクラスがステートレスまたはスレッドセーフであることを確認する

関連スキル

• langchain4j-ai-services-patterns — 高レベル AI サービス構成
• langchain4j-rag-implementation-patterns — ツール統合を使用した RAG 取得
• langchain4j-spring-boot-integration — Spring Boot アプリケーションでのツール登録

参考資料

• references/setup-configuration.md — Maven セットアップ、チャットモデル構成、最初のツール登録
• references/core-patterns.md — 基本的なツール定義、複雑なパラメータ、戻り値の型
• references/advanced-features.md — メモリコンテキスト、動的ツールプロバイダー、ストリーミング、即座返却
• references/error-handling.md — エラーハンドラー、リトライロジック、監視
• references/integration-examples.md — データベース、REST API、コンテキスト対応ツール例