ツール(関数呼び出し)
テキスト生成に加えて、一部のLLMは操作をトリガーすることもできます。
ツールをサポートするすべてのLLMはこちらで確認できます(「Tools」列を参照)。
すべてのLLMがツールを同等にサポートしているわけではありません。 ツールを理解、選択、正しく使用する能力は、特定のモデルとその能力に大きく依存します。 一部のモデルはツールをまったくサポートしない場合があり、他のモデルは慎重なプロンプトエンジニアリングや 追加のシステム指示が必要な場合があります。
「ツール」または「関数呼び出し」と呼ばれる概念があります。 これは、LLMが必要に応じて1つ以上の利用可能なツール(通常は開発者によって定義され ます)を呼び出すことを可能にします。 ツールは、ウェブ検索、外部APIの呼び出し、特定のコードスニペットの実行など、何でも構いません。 LLMは実際にはツールを自分で呼び出すことはできません。代わりに、応答の中で 特定のツールを呼び出す意図を表現します(プレーンテキストで返信する代わりに)。 開発者である私たちは、その後、提供された引数でそのツールを実行し、 ツールの実行結果をLLMに返す必要があります。
例えば、LLM自体は数学が得意ではないことが知られています。 ユースケースで数学計算が時折必要になる場合、LLMに「数学ツール」を提供するとよいでしょう。 LLMに送信するリクエストで1つ以上のツールを宣言することで、 LLMは適切と判断した場合にそれらの1つを呼び出すことを決定できます。 数学の問題と一連の数学ツールが与えられた場合、LLMは正しく回答するために、 提供された数学ツールの1つを先に呼び出すべきだと判断するかもしれません。
実際にどのように機能するかを見てみましょう(ツールありの場合となしの場合)。
ツールなしのメッセージ交換の例:
Request:
- messages:
- UserMessage:
- text: What is the square root of 475695037565?
Response:
- AiMessage:
- text: The square root of 475695037565 is approximately 689710.
近いですが、正しくありません。
以下のツールを使用したメッセージ交換の例:
@Tool("Sums 2 given numbers")
double sum(double a, double b) {
return a + b;
}
@Tool("Returns a square root of a given number")
double squareRoot(double x) {
return Math.sqrt(x);
}
Request 1:
- messages:
- UserMessage:
- text: What is the square root of 475695037565?
- tools:
- sum(double a, double b): Sums 2 given numbers
- squareRoot(double x): Returns a square root of a given number
Response 1:
- AiMessage:
- toolExecutionRequests:
- squareRoot(475695037565)
... here we are executing the squareRoot method with the "475695037565" argument and getting "689706.486532" as a result ...
Request 2:
- messages:
- UserMessage:
- text: What is the square root of 475695037565?
- AiMessage:
- toolExecutionRequests:
- squareRoot(475695037565)
- ToolExecutionResultMessage:
- text: 689706.486532
Response 2:
- AiMessage:
- text: The square root of 475695037565 is 689706.486532.
ご覧のとおり、LLMがツールにアクセスできる場合、適切なタイミングでそのうちの1つを呼び出すことを決定できます。
これは非常に強力な機能です。
この簡単な例では、LLMに基本的な数学ツールを提供しましたが、
例えば googleSearch や sendEmail ツールを提供し、
「私の友人がAI分野の最新ニュースを知りたがっています。簡単な要約をfriend@email.comに送信してください」のようなクエリを与えた場合を想像してみてください。
LLMは googleSearch ツールを使用して最新ニュースを検索し、
その後 sendEmail ツールを使用して要約を送信することができます。
LLMが正しいパラメータで 正しいツールを呼び出す可能性を高めるために、 明確で曖昧さのないものを提供する必要があります:
- ツール名
- ツールが何をするか、いつ使用すべきかの説明
- 各ツールパラメータの説明
経験則:人間がツールの目的と使用方法を理解できるなら、 LLMもおそらく理解できるでしょう。
LLMは、いつツールを呼び出すか、どのように呼び出すかを検出するために特別に微調整されています。 一部のモデルは一度に複数のツールを呼び出すこともできます。例えば OpenAI などです。
すべてのモデルがツールをサポートしているわけではないことに注意してください。
ツールをサポートするモデルを確認するには、このページの「Tools」列を参照してください。
ツール/関数呼び出しは JSON モード とは異なることに注意してください。
2つの抽象化レベル
LangChain4j はツールを使用するための2つの抽象化レベルを提供します:
- 低レベル:
ChatModelとToolSpecificationAPI を使用 - 高レベル:AI Services と
@Toolアノテーションが付いた Java メソッドを使用
低レベルツール API
低レベルでは、ChatModel の chat(ChatRequest) メソッドを使用できます。
StreamingChatModel にも同様のメソッドがあります。
ChatRequest を作成する際に、1つ以上の ToolSpecification を指定できます。
ToolSpecification はツールに関するすべての情報を含むオブジェクトで す:
- ツールの
name - ツールの
description - ツールの
parametersとその説明 - ツールの
metadata。 デフォルトでは LLM プロバイダーに送信されず、ChatModelを作成する際にどのメタデータキーを送信するかを明示的に指定する必要があります。 現在、ツールメタデータはlangchain4j-anthropicモジュールのみでサポートされています。 ツールが McpToolProvider によって提供される場合、metadataには MCP 固有のエントリを含めることができます。
ツールに関する詳細情報を提供することをお勧めします: 明確な名前、包括的な説明、各パラメータの説明など。
ツール仕様の作成
ToolSpecification を作成するには2つの方法があります:
- 手動で作成
ToolSpecification toolSpecification = ToolSpecification.builder()
.name("getWeather")
.description("Returns the weather forecast for a given city")
.parameters(JsonObjectSchema.builder()
.addStringProperty("city", "The city for which the weather forecast should be returned")
.addEnumProperty("temperatureUnit", List.of("CELSIUS", "FAHRENHEIT"))
.required("city") // the required properties should be specified explicitly
.build())
.build();
JsonObjectSchema の詳細については、こちら を参照してください。
- ヘルパーメソッドを使用する:
ToolSpecifications.toolSpecificationsFrom(Class)ToolSpecifications.toolSpecificationsFrom(Object)ToolSpecifications.toolSpecificationFrom(Method)
class WeatherTools {
@Tool("Returns the weather forecast for a given city")
String getWeather(
@P("The city for which the weather forecast should be returned") String city,
TemperatureUnit temperatureUnit
) {
...
}
}
List<ToolSpecification> toolSpecifications = ToolSpecifications.toolSpecificationsFrom(WeatherTools.class);
JSON シリアライゼーション
ToolSpecification は、toJson() メソッドと fromJson() メソッドを使用して JSON にシリアライズし、元に戻すことができます。
これは、例えばツール仕様をデータベースに保存したり、ネットワーク経由で転送したりする場合に便利です。
String json = toolSpecification.toJson();
ToolSpecification deserialized = ToolSpecification.fromJson(json);
デフォルトでは、専用のJackson ObjectMapperがJSON変換に使用されます。
ToolSpecificationJsonCodecFactoryを実装し、
META-INF/services/dev.langchain4j.spi.agent.tool.ToolSpecificationJsonCodecFactoryに登録することで、
SPIを介して独自のToolSpecificationJsonCodec実装を提供できます。
ChatModel の使用
List<ToolSpecification>を取得したら、モデルを呼び出すことができます:
ChatRequest request = ChatRequest.builder()
.messages(UserMessage.from("What will the weather be like in London tomorrow?"))
.toolSpecifications(toolSpecifications)
.build();
ChatResponse response = model.chat(request);
AiMessage aiMessage = response.aiMessage();
LLM がツール呼び出しを決定した場合、返される AiMessage には
toolExecutionRequests フィールドにデータが含まれます。
このとき、AiMessage.hasToolExecutionRequests() は true を返します。
LLM によっては、1 つまたは複数の ToolExecutionRequest オブジェクトが含まれることがあります
(一部の LLM は複数のツールの並列呼び出しをサポートしています)。
各 ToolExecutionRequest には以下が含まれる必要があります:
- ツール呼び出しの
id。一部の LLM プロバイダー(例:Google、Ollama)ではこの ID が省略される場合があることに注意してください。 - 呼び出すツールの
name(例:getWeather) arguments(例:{ "city": "London", "temperatureUnit": "CELSIUS" })
ToolExecutionRequest の情報を使用して、ツールを手動で実行する必要があります。
ツールの実行結果を LLM に送り返すには、
ToolExecutionResultMessage(各 ToolExecutionRequest につき 1 つ)を作成し、
それを以前のすべてのメッセージと一緒に送信する必要があります:
String result = "It is expected to rain in London tomorrow.";
ToolExecutionResultMessage toolExecutionResultMessage = ToolExecutionResultMessage.from(toolExecutionRequest, result);
ChatRequest request2 = ChatRequest.builder()
.messages(List.of(userMessage, aiMessage, toolExecutionResultMessage))
.toolSpecifications(toolSpecifications)
.build();
ChatResponse response2 = model.chat(request2);
マルチモーダルツール結果
ToolExecutionResultMessage は、画像などの非テキストコンテンツも保持できます。
text() を使用するだけでなく、contents() を備えたビルダーも使用できます:
ToolExecutionResultMessage toolExecutionResultMessage = ToolExecutionResultMessage.builder()
.id(toolExecutionRequest.id())
.toolName(toolExecutionRequest.name())
.contents(
TextContent.from("Here is the photo"),
ImageContent.from(Image.builder()
.base64Data(base64Data)
.mimeType("image/png")
.build())
)
.build();
すべてのLLMプロバイダーがマルチモーダルツール結果をサポートしているわけではありません。 プロバイダーのサポート状況の詳細については、画像とマルチモーダルコンテンツの返却を参照してください。
StreamingChatModel の使用
List<ToolSpecification> を取得したら、モデルを呼び出すことができます:
ChatRequest request = ChatRequest.builder()
.messages(UserMessage.from("What will the weather be like in London tomorrow?"))
.toolSpecifications(toolSpecifications)
.build();
model.chat(request, new StreamingChatResponseHandler() {
@Override
public void onPartialResponse(String partialResponse) {
System.out.println("onPartialResponse: " + partialResponse);
}
@Override
public void onPartialToolCall(PartialToolCall partialToolCall) {
System.out.println("onPartialToolCall: " + partialToolCall);
}
@Override
public void onCompleteToolCall(CompleteToolCall completeToolCall) {
System.out.println("onCompleteToolCall: " + completeToolCall);
}
@Override
public void onCompleteResponse(ChatResponse completeResponse) {
System.out.println("onCompleteResponse: " + completeResponse);
}
@Override
public void onError(Throwable error) {
error.printStackTrace();
}
});
LLM がツール呼び出しを決定した場合、onPartialToolCall(PartialToolCall) コールバックは、
通常、最終的に onCompleteToolCall(CompleteToolCall) が呼び出される前に複数回呼び出されます。
後者は、そのツール呼び出しのストリーミング出力が完了したことを示します。
すべての LLM プロバイダーが部分的なツール呼び出しをストリーミングするわけではないことに注意してください。
一部のプロバイダー(例:Bedrock、Google、Mistral、Ollama)は完全なツール呼び出しのみを返します。
これらの場合、onPartialToolCall コールバックは呼び出されず、onCompleteToolCall のみが呼び出されます。
単一のツール呼び出しのストリーミング出力は次のようになります:
onPartialToolCall(index = 0, id = "call_abc", name = "get_weather", partialArguments = "{\"")
onPartialToolCall(index = 0, id = "call_abc", name = "get_weather", partialArguments = "city")
onPartialToolCall(index = 0, id = "call_abc", name = "get_weather", partialArguments = ""\":\"")
onPartialToolCall(index = 0, id = "call_abc", name = "get_weather", partialArguments = "London")
onPartialToolCall(index = 0, id = "call_abc", name = "get_weather", partialArguments = "\"}")
onCompleteToolCall(index = 0, id = "call_abc", name = "get_weather", arguments = "{\"city\":\"London\"}")
LLMが複数のツール呼び出しを開始した場合、indexは増加し、異なるPartialToolCall同士や、最終的なCompleteToolCallとの対応付けが可能になります。
完全なレスポンスのストリーミングが終了し、onCompleteResponse(ChatResponse)が呼び出されると、
ChatResponse内のAiMessageには、ストリーミング中に発生したすべてのツール呼び出しが含まれます。
高レベルツールAPI
高レベルの抽象化では、任意のJavaメソッドに@Toolアノテーションを付与し、
AIサービスを作成する際に指定できます。
AIサービスは、そのようなメソッドを自動的にToolSpecificationに変換し、
LLMとの各やり取りのリクエストに含めます。
LLMがツールを呼び出すことを決定した場合、AIサービスは自動的に対応するメソッドを実行し、
メソッドの戻り値(存在する場合)はLLMに送り返されます。
実装の詳細はDefaultToolExecutorにあります。
ツールの例をいくつか示します。
@Tool("Searches Google for relevant URLs, given the query")
public List<String> searchGoogle(@P("search query") String query) {
return googleSearchService.search(query);
}
@Tool("Returns the content of a web page, given the URL")
public String getWebPageContent(@P("URL of the page") String url) {
Document jsoupDocument = Jsoup.connect(url).get();
return jsoupDocument.body().text();
}
ツールメソッドの制限
@Tool で注釈されたメソッドは:
- 静的メソッドまたは非静的メソッドのいずれかを使用できます
- 任意の可視性(public、private など)を持つことができます
ツールメソッドのパラメータ
@Tool で注釈されたメソッドは、さまざまな型の任意の数のパラメータを受け入れることができます:
- プリミティブ型:
int、doubleなど - オブジェクト型:
String、Integer、Doubleなど - カスタム POJO(ネストされた POJO を含むことができます)
enum- ポリモーフィック型(sealed インターフェース/クラス、または Jackson の
@JsonSubTypes/@JsonTypeInfoで注釈された型)— ポリモーフィックツールパラメータ を参照してください - 上記の型のいずれかである
List<T>/Set<T> Map<K,V>(@Pを使用してパラメータの説明にKとVの型を手動で指定する必要があります)
パラメータのないメソッドもサポートされています。
パラメータ名
デフォルトでは、@P の name 属性が指定されていない場合、パラメータ名はリフレクションによって取得されます。
ただし、-parameters javac オプションがない場合、リフレクションは arg0、arg1 などの汎用的な名前を返します。
パラメータの意味が失われ、LLM を混乱させる可能性があります。
@P で name を設定することは、次の 2 つの場合に役立ちます:
-parametersjavac オプションがない場合 — LLM が参照するであろう汎用的なarg0/arg1という名前を避けるためです。 Quarkus や Spring などのフレームワークはデフォルトで-parametersを有効にするため、 実際のメソッドパラメータ名が保持され、これらのフレームワークを使用する場合は通常nameを設定する必要がないことに注意してください。- LLM 用のカスタム名 — ソースコード内のパラメータ名とは異なるパラメータ名を LLM に表示したい場合 (たとえば、特定の API 契約に一致させるため、またはより説明的な名前を提供するため)。
例:
@Tool
void getTemperature(
@P("Temperature value") double value,
@P("Unit of temperature") Optional<String> unit) {
...
}
必須とオプション
デフォルトでは、すべてのツールメソッドのパラメータは必須と見なされます。
これは、パラメータが LLM に送信される JSON スキーマの required 配列にリストされ、
値の生成が指示されることを意味します。
パラメータに @P(required = false) アノテーションを付けることで、オプションにすることができます:
@Tool
String getTemperature(String location, @P(required = false) Unit unit) {
...
}
または、パラメータを Optional<T> として宣言することもできます:
@Tool
String getTemperature(String location, Optional<Unit> unit) {
...
}
複雑なパラメータのフィールドとサブフィールドも、デフォルトでは必須と見なされます。
フィールドに @JsonProperty(required = false) アノテーションを付けることで、任意指定にできます:
record User(String name, @JsonProperty(required = false) String email) {}
@Tool
void add(User user) {
...
}
结构化输出と併用する場合、 すべてのフィールドとサブフィールドはデフォルトでオプションとして扱われることに注意して ください。
required フラグは LLM に送信される JSON スキーマを制御します(必須パラメータは
スキーマの required 配列にリストされます)。LLM がこれに従うことが期待されますが、実際には
スキーマを無視してパラメータを省略する可能性があります。
LangChain4j 1.x では、これはプリミティブ型パラメータ(int、long、boolean など)に対してのみ検出されます——
欠落したプリミティブ型は ToolArgumentsErrorHandler をトリガーします(下記のエラーハンドリングを参照)。
欠落したオブジェクトパラメータは検証されません:スキーマがパラメータを必須とマークしていても、
@Tool アノテーション付きメソッドには null が渡されます。
LangChain4j 2.0 ではこの非対称性を解消し、すべての必須パラメータを 一貫して検証することを計画しています。この計画の変更がユースケースに影響する場合は、 issue を提出してください。実装前にフィードバックを反映します。
null の代わりに実際のフォールバック値を使用したい場合(またはプリミティブ型パラメータのエラーの代わりに)、
@P(defaultValue = ...) を使用してください。
デフォルトパラメータ値
@P(defaultValue = "...") は、LLM がパラメータを省略した場合に LangChain4j が置き換える値を宣言します。
これはパラメータをオプションにし、ツールメソッドに合理的なフォールバック値を提供する最も簡単な方法です。
enum SortBy { RELEVANCE, DATE, RATING }
@Tool
List<Article> searchArticles(
String query,
@P(defaultValue = "10") int limit,
@P(defaultValue = "[\"en\"]") List<String> languages,
@P(defaultValue = "RELEVANCE") SortBy sortBy
) {
// When the LLM omits them:
// 'limit' -> 10
// 'languages' -> ["en"]
// 'sortBy' -> SortBy.RELEVANCE
}
defaultValue を設定すると、JSON スキーマ上ではオプション扱いになります — @P(required) の指定に関係なく、そのパラメータはスキーマの required 配列には含まれません。LLM にはこのパラメータを省略してもよいと伝えられ、省略された場合、LangChain4j はメソッド呼び出し前にデフォルト値を代入します。
サポートされる型:
| 型 | 形式 | 例 |
|---|---|---|
String | そのまま使用 | defaultValue = "USD" |
| プリミティブ型 / ラッパー型 | 型固有の変換 | "10"、"3.14"、"true" |
enum | 列挙定数名 | defaultValue = "EUR" |
UUID | UUID.fromString | "550e8400-e29b-41d4-a716-446655440000" |
BigDecimal、BigInteger | 数値リテラル | "1.5"、"100" |
List<T> / Set<T> / 配列 | JSON 配列 | "[\"a\",\"b\"]", "[1,2,3]" |
Map<K,V> | JSON オブジェクト | "{\"a\":1,\"b\":2}" |
| POJO(ネストを含む) | JSON オブジェクト | "{\"name\":\"Klaus\",\"age\":42}" |
デフォルト値の文字列は AI Service の登録時に解析されます。パラメータ型に変換できない場合、AI Service の構築は問題のあるパラメータを指摘して即座に IllegalConfigurationException で失敗します。つまり、タイプミスは最初の LLM 呼び出し時ではなく、起動時に検出されます。
デフォルト値は「欠落」に対してのみ適用され、「不正な値」には適用されません。 LLM が提供したパラメータの型変換に失敗した場合(例:int に対して "banana" が渡された場合)、変換エラーは通常どおり伝播します。デフォルト値がフォールバ ックとして使用されることはありません。
デフォルト値は呼び出しのたびに再解析されるため、 可変なデフォルトの List / Map / POJO を変更するツールが後続の呼び出しに影響を与えることはありません。
@Tool
void process(@P(defaultValue = "[\"a\",\"b\"]") List<String> tags) {
tags.add("processed"); // safe — next invocation still receives ["a","b"]
}
制限(登録時に IllegalConfigurationException で拒否されます):
defaultValueはOptional<T>と組み合わせられません —Optionalはすでに 「欠落」をエンコードしています。どちらか一方のメカニズムを選択してください。defaultValueは LangChain4j が注入するパラメータ(@ToolMemoryId、InvocationContextなど)には設定できません — これらは LLM から提供されるものではないためです。
ポリモーフィックなツールパラメータ
ツールパラメータはポリモーフィック型にできます — つまり、具体的なサブタイプが
呼び出し時に LLM によって決定される基本型です。sealed インターフェースと sealed クラスは
アノテーションなしで機能します。通常の抽象クラスとインターフェースは、Jackson の
@JsonSubTypes を使用してサブタイプを宣言する必要があります。
LLM に送信されるスキーマには、許可されたサブタイプの anyOf が含まれ、それぞれに
判別子プロパティ(デフォルトは "type")があり、LLM が生成する具体的な
型を伝えられるようになっています。LangChain4j はツールメソッドを呼び出す前に、LLM のパラメータを正しいサブタイプに逆シリアル化します。
これは、パラメータとしてのポリモーフィック型、ポリモーフィック型の List<T> / Set<T>、
および別の POJO パラメータ内にネストされたポリモーフィック型に対して機能します。
sealed インターフェースとクラス — アノテーション不要:
sealed interface Animal permits Dog, Cat {}
record Dog(String name, String breed) implements Animal {}
record Cat(String name, boolean indoor) implements Animal {}
class AnimalRegistry {
@Tool("Registers a single animal")
void registerAnimal(Animal animal) { /* dispatched to Dog or Cat */ }
@Tool("Registers a batch of animals")
void registerAnimals(List<Animal> animals) { /* mixed Dog / Cat */ }
@Tool("Registers an owner with their pet")
void registerOwner(Owner owner) { /* Owner.pet is dispatched */ }
}
record Owner(String name, Animal pet) {}
Jackson @JsonSubTypes / @JsonTypeInfo もサポートされており、オンライン上の
名前を Java クラス名から切り離すことができます:
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "kind")
@JsonSubTypes({
@JsonSubTypes.Type(value = Square.class, name = "square"),
@JsonSubTypes.Type(value = Circle.class, name = "circle")
})
interface Shape {}
class ShapeRegistry {
@Tool("Registers a shape")
void registerShape(Shape shape) { /* dispatched to Square or Circle */ }
}
サポートされている@JsonTypeInfoオプションのセット、判別子名の解決順序、
defaultImplの動作、visibleフラグ、およびフィールド衝突の検出については、
構造化出力のポリモーフィック型で
詳しく説明されています。これらはツールパラメータにも同様に適用されます。
再帰的パラメータ
再帰的パラメータ(例:Set<Person> childrenフィールドを持つPersonクラス)は、
現在OpenAIでのみサポートされています。
ツールメソッドの戻り値の型
@Toolでアノテーションされたメソッドは、voidを含む任意の型を返すことができます。
メソッドの戻り値の型がvoidの場合、メソッドが正常に戻れば「Success」という文字列がLLMに送信されます。
メソッドの戻り値の型がStringの場合、戻り値は変換なしでそのままLLMに送信されます。
その他の戻り値の型の場合、戻り値はLLMに送信される前にJSON文字列に変換 されます。
画像およびマルチモーダルコンテンツの返却
ツールは画像やその他のテキスト以外のコンテンツも返すことができます。ツールが以下の型のいずれかを返す場合、 結果はJSONテキストにシリアライズされる代わりに、マルチモーダルコンテンツ(例:画像)としてLLMに送信されます:
Image— 単一の画像として送信ImageContent— 単一の画像コンテンツとして送信Content— 単一のコンテンツ要素として送信(例:TextContent、ImageContent)List<Content>— 複数のコンテンツ要素として送信Content[]— 複数のコンテンツ要素として送信
例えば、写真を撮って画像を返すツールは次のようになります:
@Tool("Takes a photo and returns it")
Image takePhoto() {
byte[] imageBytes = camera.capture();
return Image.builder()
.base64Data(Base64.getEncoder().encodeToString(imageBytes))
.mimeType("image/png")
.build();
}
またはテキストと画像を返すツール:
@Tool("Takes a photo and returns it with a description")
List<Content> takePhoto() {
Image image = camera.capture();
return List.of(
TextContent.from("Photo taken at " + LocalDateTime.now()),
ImageContent.from(image)
);
}
すべての LLM プロバイダーがマルチモーダルなツール結果をサポートしているわけではありません。
現在、ツール結果内の画像をサポートしているプロバイダーには、Anthropic、Amazon Bedrock、Google AI Gemini が含まれます。
ツールが非テキストコンテンツを返す場合、他のプロバイダーは UnsupportedFeatureException をスローします。
AI サービスを他の AI サービスのツールとして使用する
AI サービスは、他の AI サービスのツールとしても使用できます。これは、多くのエージェントのユースケースで役立ちます。ある AI サービスが、特定のタスクを実行するために、より専門的な別の AI サービスの支援を要求できるからです。例えば、以下の AI サービスを定義した場合を考えてみましょう。
interface RouterAgent {
@dev.langchain4j.service.UserMessage("""
Analyze the following user request and categorize it as 'legal', 'medical' or 'technical',
then forward the request as it is to the corresponding expert provided as a tool.
Finally return the answer that you received from the expert without any modification.
The user request is: '{{it}}'.
""")
String askToExpert(String request);
}
interface MedicalExpert {
@dev.langchain4j.service.UserMessage("""
You are a medical expert.
Analyze the following user request under a medical point of view and provide the best possible answer.
The user request is {{it}}.
""")
@Tool("A medical expert")
String medicalRequest(String request);
}
interface LegalExpert {
@dev.langchain4j.service.UserMessage("""
You are a legal expert.
Analyze the following user request under a legal point of view and provide the best possible answer.
The user request is {{it}}.
""")
@Tool("A legal expert")
String legalRequest(String request);
}
interface TechnicalExpert {
@dev.langchain4j.service.UserMessage("""
You are a technical expert.
Analyze the following user request under a technical point of view and provide the best possible answer.
The user request is {{it}}.
""")
@Tool("A technical expert")
String technicalRequest(String request);
}
RouterAgent は、ユーザーのリクエストをそのうちの1つにルーティングするために、他の3つの特定分野の専門家AIサービスをツールとして使用するように設定できます。
MedicalExpert medicalExpert = AiServices.builder(MedicalExpert.class)
.chatModel(model)
.build();
LegalExpert legalExpert = AiServices.builder(LegalExpert.class)
.chatModel(model)
.build();
TechnicalExpert technicalExpert = AiServices.builder(TechnicalExpert.class)
.chatModel(model)
.build();
RouterAgent routerAgent = AiServices.builder(RouterAgent.class)
.chatModel(model)
.tools(medicalExpert, legalExpert, technicalExpert)
.build();
routerAgent.askToExpert("I broke my leg what should I do");
AI サービスを他の AI サービスのツールとして使用することは、複雑なエージェントシステムを構築するための強力な機能です。ただし、この方法には注意すべき関連する欠点もいくつかあり ます:
- この実装では、LLM がユーザーのリクエストをツール呼び出しとしてそのままコピー&ペーストする必要があり、これはエラーが発生しやすい操作となる可能性があります。
- 別の LLM をツールとして呼び出す LLM は、(他のツール呼び出しと同様に)その応答を再処理する必要があり、時間と消費されるトークンの点で無駄な計算となる可能性があります。
- ツールとして機能するエージェントは完全に分離された AI サービスであり、それを呼び出すエージェントのチャットメモリにアクセスできないため、チャットメモリを使用してより情報に基づいた回答を提供することはできません。
@Tool
@Tool アノテーションが付けられ、AI サービスの構築時に明示的に指定された Java メソッドは、すべて LLM によって実行できます:
interface MathGenius {
String ask(String question);
}
class Calculator {
@Tool
double add(int a, int b) {
return a + b;
}
@Tool
double squareRoot(double x) {
return Math.sqrt(x);
}
}
MathGenius mathGenius = AiServices.builder(MathGenius.class)
.chatModel(model)
.tools(new Calculator())
.build();
String answer = mathGenius.ask("What is the square root of 475695037565?");
System.out.println(answer); // The square root of 475695037565 is 689706.486532.
ask メソッドを呼び出すと、前述の章で説明したように、LLM との間で 2 回のやり取りが発生します。
これらのやり取りの間に、squareRoot メソッドが自動的に呼び出されます。
@Tool アノテーションには、次のフィールドがあります:
name:ツール名。指定しない場合、メソッド名がツール名として使用されます。value:ツールの説明。returnBehavior:詳細はこちらを参照してください。metadata:LLM プロバイダー固有のツールメタデータエントリを含む有効な JSON 文字列。
デフォルトでは LLM プロバイダーに送信されず、ChatModel を作成する際に、どのメタデータキーを送信するかを明示的に指定する必要があります。
現在、ツールメタデータは langchain4j-anthropic モジュールのみでサポートされています。
ツールによっては、説明がなくても LLM が十分に理解できる場合もありますが
(例:add(a, b) は明らかです)、
通常は、明確で意味のある名前と説明を提供するのが最善です。
そうすることで、LLM は特定のツールを呼び出すかどうか、またどのように呼び出すかを決定するための情報をより多く得られます。
継承とツールの発見
AI Service にツールオブジェクトを渡すと、LangChain4j はオブジェクトのクラス、そのすべてのスーパークラス(Object は除く)、および実装されたインターフェースの default メソッドと static メソッドから @Tool メソッドを発見します。
class BaseMathTools {
@Tool("Calculates the sum of two numbers")
int sum(int a, int b) {
return a + b;
}
}
class AdvancedMathTools extends BaseMathTools {
@Tool("Calculates the product of two numbers")
int multiply(int a, int b) {
return a * b;
}
}
Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(model)
.tools(new AdvancedMathTools()) // both "sum" and "multiply" are available
.build();
子クラスは親クラスの @Tool メソッドをオーバーライドできます。この場合、子クラスのバージョン(その @Tool アノテーションを含む)のみが使用されます:
class ParentTools {
@Tool("Returns the greeting")
String greet(String name) {
return "Hello, " + name;
}
}
class ChildTools extends ParentTools {
@Override
@Tool(name = "greet_formal", value = "Returns a formal greeting")
String greet(String name) {
return "Good day, " + name;
}
}
ここで、LLM は greet_formal という名前で、「正式な挨拶を返す」と説明された単一のツールを参照します。
メソッドが、アノテーションを繰り返さずに @Tool アノテーション付きのメソッドをオーバーライドまたは実装している場合も、そのメソッドはツールになります。
ツールをインターフェースで宣言し、別の場所で実装する場合に便利です:
interface WeatherTools {
@Tool("Returns the weather in the given city")
String weather(String city);
}
class OpenMeteoWeatherTools implements WeatherTools {
@Override
public String weather(String city) {
return ...;
}
}
Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(model)
.tools(new OpenMeteoWeatherTools()) // "weather" is available, described as declared in the interface
.build();
LLM には、オーバーライドされたメソッドの @Tool アノテーションが見えます。ただし、オーバーライドするメソッドが独自のアノテーションを宣言している場合は、そちらが使われます。
これは、ツールオブジェクトがプロキシでラップされている場合にもツールが機能する仕組みでもあります。
たとえば、@Aspect、@Transactional、@Async が適用された Spring bean などです。
このようなプロキシはツールメソッドをオーバーライドする生成されたサブクラスであり、Java はメソッドのアノテーションを
オーバーライドするメソッドにコピーしないため、アノテーションはプロキシされるクラスから検索されます。
ツールはプロキシ経由で呼び出されるため、インターセプターやアスペクトも引き続き実行されます。
サブクラスが親メソッドと同じ名前だが異なるパラメータを持つメソッドを宣言する場合(オーバーライドではなくオーバーロード)、両方のメソッドが検出されます。ツール名は一意である必要があり、デフォルトではメソッド名になるため、少なくとも一方に明示的な名前を付ける必要があり ます。
class ParentTools {
@Tool(name = "process_text", value = "Processes a text input")
String process(String input) {
return input.toUpperCase();
}
}
class ChildTools extends ParentTools {
@Tool(name = "process_number", value = "Processes a numeric input")
int process(int input) {
return input * 2;
}
}
両方のメソッドが同じツール名に解決される場合、AIサービスの作成時にIllegalArgumentExceptionがスローされます。
@P
メソッドのパラメータには、任意で@Pを付与できます。
@Pアノテーションには、以下の任意フィールドがあります:
name:LLMから見えるパラメータ名。指定しない場合、実際のメソッドパラメータ名が使用されます。description:パラメータの説明(valueのエイリアス)。デフォルトは空です。value:パラメータの説明(descriptionのエイリアス)。デフォルトは空です。required:パラメータが必須かどうか。デフォルトはtrueです。
パラメータ名
name属性は、LLMが参照するパラメータ名を上書きします。
nameを設定すると便利なケースは2つあります:
-
-parametersjavacオプションがない場合。-parametersjavacオプションがないと、Javaリフレクションはarg0、arg1などの汎用的な名前を返します。 パラメータの意味が失われ、LLMを混乱させる可能性があります。nameを設定することで、意味のある名前を復元できます。 QuarkusやSpringなどのフレームワークはデフォルトで-parametersを有効にするため、 実際のメソッドパラメータ名が保持され、これらのフレームワークを使用する場合は通常nameを設定する必要はありません。 -
LLM用のカスタム名。 開発者がソースコードで使用しているパラメータ名とは異なる名前をLLMに表示したい場合 (たとえば、特定のAPI契約に合わせる場合や、より説明的な名前を提供する場合)。
パラメータの説明
descriptionとvalueは相互に置き換え可能です。どちらもLLMが参照するパラメータの説明を設定します。
説明のみが必要な場合は、短縮形のvalue形式を使用します:
@Tool
void getWeather(@P("The city name") String city) { ... }
名前と説明の両方が必要な場合は、名前付き属性を使用します。
@Tool
void getWeather(@P(name = "city", description = "The city name") String city) { ... }
@Description
クラスとフィールドの説明は、@Description アノテーションを使用して指定できます:
@Description("Query to execute")
class Query {
@Description("Fields to select")
private List<String> select;
@Description("Conditions to filter on")
private List<Condition> where;
}
@Tool
Result executeQuery(Query query) {
...
}
enum 値に付与された @Description は 効果がなく、生成される JSON スキーマには 含まれない ことに注意してください:
enum Priority {
@Description("Critical issues such as payment gateway failures or security breaches.") // this is ignored
CRITICAL,
@Description("High-priority issues like major feature malfunctions or widespread outages.") // this is ignored
HIGH,
@Description("Low-priority issues such as minor bugs or cosmetic problems.") // this is ignored
LOW
}
InvocationParameters
AI Service を呼び出す際にツールへ追加データを渡したい場合は、
InvocationParameters を使用できます:
interface Assistant {
String chat(@UserMessage String userMessage, InvocationParameters parameters);
}
class Tools {
@Tool
String getWeather(String city, InvocationParameters parameters) {
String userId = parameters.get("userId");
UserPreferences preferences = getUserPreferences(userId);
return weatherService.getWeather(city, preferences.temperatureUnits());
}
}
InvocationParameters parameters = InvocationParameters.from(Map.of("userId", "12345"));
String response = assistant.chat("What is the weather in London?", parameters);
この場合、LLM はこれらのパラメータを認識しません。 それらは LangChain4j とユーザーコードにのみ表示されます。
InvocationParameters は、他の AI Service コンポーネントでもアクセスできます。例:
ToolProvider:ToolProviderRequest内ToolArgumentsErrorHandlerおよびToolExecutionErrorHandler:ToolErrorContext内- RAG コンポーネント:
Query->Metadata内
パラメータは、可変でスレッドセーフな Map に格納されます。
データは、AI Service の単一呼び出し中に、InvocationParameters を介して
AI Service コンポーネント間で受け渡しできます(例:あるツールから別のツールへ、または RAG コンポーネントからツールへ)。
InvocationContext
InvocationParameters と同様に、@Tool アノテーションが付いたメソッドは
InvocationContext パラメータを受け入れて、AI Service 呼び 出しに関する情報に
アクセスできます。
class Tools {
@Tool
String getWeather(String city, InvocationContext context) {
UUID invocationId = context.invocationId();
String aiServiceInterfaceName = context.interfaceName();
...
}
}
この場合、LLM はこれらのパラメータを認識しません。 それらは LangChain4j とユーザーコードにのみ表示されます。
ツールが別の AI Service を呼び出す場合、その内側の呼び出しの InvocationContext は、
parentInvocationId() から呼び出し元の呼び出しの invocationId を返します。
ネストされた呼び出しのリンクを参照してください。
@ToolMemoryId
AI Service メソッドに @MemoryId アノテーションが付いたパラメータがある場合、
@Tool メソッドのパラメータにも @ToolMemoryId アノテーションを付けることができます:
interface Assistant{
String chat(@UserMessage String userMessage, @MemoryId memoryId);
}
class Tools {
@Tool
String addCalendarEvent(CalendarEvent event, @ToolMemoryId memoryId) {
...
}
}
String answer = assistant.chat("Tomorrow I will have a meeting with Klaus at 14:00", "12345");
AI Service メソッドに提供された値は、自動的に @Tool メソッドへ渡されます。
複数のユーザーがいる場合や、ユーザーごとに複数のチャット/メモリがある場合に、
@Tool メソッド内でそれらを区別したい場合に、この機能は役立ちます。
ツールの並行実行
デフォルトでは、LLM が一度に複数のツールを呼び出す場合(並列ツール呼び出しとも呼ばれます)、
AI Service はそれらを順次実行します。ツールを並行して実行したい場合は、
AI Service の構築時に executeToolsConcurrently() または executeToolsConcurrently(Executor) を呼び出します。
これらのオプションのいずれかを有効にすると、ツールは並行して実行され(1つの例外があります——下記参照)、
デフォルトまたは指定された Executor が使用されます。