跳到主要内容

エージェントと Agentic AI

备注

このセクションでは、langchain4j-agentic モジュールを使用してエージェント型 AI アプリケーションを構築する方法を説明します。モジュール全体は実験的機能と見なされており、将来のリリースで変更される可能性があることに注意してください。

エージェント型システム​

AI エージェントについて普遍的に合意された定義はありませんが、複数の AI サービスの能力を連携・組み合わせることで、より複雑なタスクを達成できる AI を活用したアプリケーションを作成する方法として、いくつかのパターンが現れています。これらのパターンは、しばしば「エージェント型システム」または「エージェント型 AI」と呼ばれます。通常は、大規模言語モデル(LLM)を用いて、タスクの実行をオーケストレーションし、ツールの利用を管理し、対話をまたいでコンテキストを維持します。

Anthropic の研究者による最近の記事によれば、これらのエージェント型システムのアーキテクチャは、ワークフローと純粋なエージェントという 2 つの主なカテゴリに分類できます。

このチュートリアルで扱う langchain4j-agentic モジュールは、ワークフローおよび純粋なエージェント型 AI アプリケーションの構築を支援する抽象化とユーティリティ一式を提供します。ワークフローの定義、ツール利用の管理、異なる LLM との対話をまたいだコンテキストの維持を可能にします。

LangChain4j のエージェント​

LangChain4j のエージェントは、LLM を使用して特定のタスクまたは一連のタスクを実行します。通常の AI サービスと同様に、単一メソッドを持つインターフェースとして定義でき、そこに @Agent アノテーションを追加するだけです。

public interface CreativeWriter {

@UserMessage("""
You are a creative writer.
Generate a draft of a story no more than
3 sentences long around the given topic.
Return only the story and nothing else.
The topic is {{topic}}.
""")
@Agent("Generates a story based on the given topic")
String generateStory(@V("topic") String topic);
}

このアノテーションには、エージェントの目的を示す短い説明も付与することを推奨します。特に、他のエージェントがこのエージェントをいつどのように利用するかを適切に判断する必要がある純粋なエージェント型パターンでは重要です。この説明は、エージェントビルダーの description メソッドを使用して、プログラムから指定することもできます。

エージェントには、エージェント型システム内で一意に識別する名前も必要です。この名前は @Agent アノテーションで指定することも、エージェントビルダーの name メソッドを使用してプログラムから指定することもできます。指定しない場合は、@Agent が付与されたメソッド名が使用されます。

これで、インターフェースと使用するチャットモデルを指定して、AgenticServices.agentBuilder() メソッドによりこのエージェントのインスタンスを構築できます。

CreativeWriter creativeWriter = AgenticServices
.agentBuilder(CreativeWriter.class)
.chatModel(myChatModel)
.outputKey("story")
.build();

本質的に、エージェントは通常の AI サービスであり、同じ機能を提供します。ただし、他のエージェントと組み合わせて、より複雑なワークフローやエージェント型システムを作成できます。

AI サービスとのもう 1 つの主な違いは、エージェント呼び出しの結果を保存する共有変数の名前を指定する outputKey パラメータがあることです。これにより、同じエージェント型システム内の他のエージェントが結果を利用できます。代わりに、この例のようにプログラムから指定するのではなく、出力名を @Agent アノテーションで直接宣言することもできます。

@Agent(outputKey = "story", description = "Generates a story based on the given topic")

AgenticServices クラスは、langchain4j-agentic フレームワークで利用可能なあらゆる種類のエージェントを作成・定義するための静的ファクトリメソッド群を提供します。

ツール検索​

多数のツールを持つエージェントは、ツール検索を使用することで、すべてのツール仕様を最初から受け取る代わりに、LLM が必要なツールを自ら見つけられるようになります。AI サービスと同じ ToolSearchStrategy をエージェントビルダーに設定します。

Assistant assistant = AgenticServices.agentBuilder(Assistant.class)
.chatModel(chatModel)
.tools(new BookingTools(), new WeatherTools())
.toolSearchStrategy(new SimpleToolSearchStrategy())
.build();

LLM には当初、ツール検索ツールと SearchBehavior.ALWAYS_VISIBLE でマークされたツールのみが見えます。見つかったツールは、その呼び出しの残りの間利用可能なままとなり、エージェントにチャットメモリがある場合は、その検索結果がメモリから削除されるまで利用可能です。これは .tools(...) と .toolProvider(...) の両方で、ブロッキングおよびストリーミングのエージェントで動作し、SimpleToolSearchStrategy、VectorToolSearchStrategy、DecisionModelToolSearchStrategy など任意の ToolSearchStrategy と組み合わせて使えます。

宣言型エージェントは、@ToolsSupplier や @ToolProviderSupplier と並べて、@ToolSearchStrategySupplier で戦略を提供できます。

public interface Assistant {
@UserMessage("{{request}}")
@Agent(outputKey = "answer")
String answer(@V("request") String request);

@ToolsSupplier
static Object[] tools() {
return new Object[] { new BookingTools(), new WeatherTools() };
}

@ToolSearchStrategySupplier
static ToolSearchStrategy toolSearchStrategy() {
return new SimpleToolSearchStrategy();
}
}

ビルダーで .toolSearchStrategy(...) により設定した戦略は、アノテーションで指定したものより優先されます。この戦略は、設定されたエージェントにのみ適用されます。ツールと同様に、ワークフローからそのサブエージェントへは引き継がれません。

AgenticScope の紹介​

langchain4j-agentic モジュールは、エージェント型システムに参加するエージェント間で共有されるデータの集合である AgenticScope の概念を導入します。AgenticScope は共有変数を保存するために使われます。エージェントは生成した結果を伝えるために変数へ書き込み、別のエージェントは自身のタスクに必要な情報を組み立てるために変数を読み取れます。これにより、必要に応じて情報と結果を共有し、エージェントが効率的に協調できます。

AgenticScope は、すべてのエージェントの呼び出し順序と応答など、他の関連情報も自動的に登録します。エージェント型システムのメインエージェントが呼び出されると自動的に作成され、必要に応じてコールバックを通じてプログラムから提供されます。AgenticScope のさまざまな利用方法は、langchain4j-agentic が実装するエージェント型パターンを説明する際に、実践的な例で明らかにします。

ワークフローパターン​

langchain4j-agentic モジュールは、複数のエージェントをプログラムからオーケストレーションし、エージェント型ワークフローパターンを作成するための抽象化一式を提供します。これらのパターンは組み合わせて、より複雑なワークフローを作成できます。

順次ワークフロー​

順次ワークフローは最も単純なパターンで、複数のエージェントを順番に呼び出し、各エージェントの出力を次のエージェントへの入力として渡します。特定の順序で実行する必要がある一連のタスクに適しています。

たとえば、先に定義した CreativeWriter エージェントに、生成された物語を特定の読者層により適合するよう編集できる AudienceEditor エージェントを追加するとよいでしょう。

public interface AudienceEditor {

@UserMessage("""
You are a professional editor.
Analyze and rewrite the following story to better align
with the target audience of {{audience}}.
Return only the story and nothing else.
The story is "{{story}}".
""")
@Agent("Edits a story to better fit a given audience")
String editStory(@V("story") String story, @V("audience") String audience);
}

さらに、特定のスタイルに対して同じ仕事を行う、非常によく似た StyleEditor も追加します。

public interface StyleEditor {

@UserMessage("""
You are a professional editor.
Analyze and rewrite the following story to better fit and be more coherent with the {{style}} style.
Return only the story and nothing else.
The story is "{{story}}".
""")
@Agent("Edits a story to better fit a given style")
String editStory(@V("story") String story, @V("style") String style);
}

このエージェントの入力引数には変数名のアノテーションが付与されていることに注意してください。実際には、エージェントに渡す引数の値を直接提供するのではなく、同じ名前を持つ AgenticScope の共有変数から取得します。これにより、エージェントはワークフロー内の前のエージェントの出力にアクセスできます。エージェントクラスを -parameters オプションを有効にしてコンパイルし、メソッドパラメータ名を実行時に保持している場合は、@V アノテーションを省略でき、変数名はパラメータ名から自動的に推論されます。

この時点で、これら 3 つのエージェントを組み合わせた順次ワークフローを作成できます。CreativeWriter の出力は AudienceEditor と StyleEditor の両方への入力として渡され、最終出力は編集済みの物語です。

CreativeWriter creativeWriter = AgenticServices
.agentBuilder(CreativeWriter.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

AudienceEditor audienceEditor = AgenticServices
.agentBuilder(AudienceEditor.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

StyleEditor styleEditor = AgenticServices
.agentBuilder(StyleEditor.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

UntypedAgent novelCreator = AgenticServices
.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.build();

Map<String, Object> input = Map.of(
"topic", "dragons and wizards",
"style", "fantasy",
"audience", "young adults"
);

String story = (String) novelCreator.invoke(input);

ここでの novelCreator エージェントは、3 つのサブエージェントを順番に呼び出して組み合わせる、順次ワークフローを実装したエージェント型システムです。このエージェントの定義には型付きインターフェースが提供されていないため、シーケンスエージェントビルダーは、入力マップで呼び出せる汎用エージェントである UntypedAgent インスタンスを返します。

public interface UntypedAgent {
@Agent
Object invoke(Map<String, Object> input);
}

その入力マップ内の値は AgenticScope の共有変数へコピーされるため、サブエージェントからアクセスできます。novelCreator エージェントの出力も、物語の作成・編集ワークフローの実行中に他のすべてのエージェントによって書き換えられた、"story" という名前の AgenticScope 共有変数から取得されます。

なお、型付きインターフェースを提供せず、単一のエージェントも UntypedAgent インスタンスとして定義できます。たとえば、CreativeWriter エージェントは次のように定義することも可能でした。

UntypedAgent creativeWriter = AgenticServices.agentBuilder()
.chatModel(BASE_MODEL)
.description("Generate a story based on the given topic")
.userMessage("""
You are a creative writer.
Generate a draft of a story no more than
3 sentences long around the given topic.
Return only the story and nothing else.
The topic is {{topic}}.
""")
.inputKey(String.class, "topic")
.returnType(String.class) // String is the default return type for untyped agents
.outputKey("story")
.build();

一方、ワークフローエージェントにも、型の強い入力と出力で呼び出せるよう、任意で型付きインターフェースを提供できます。この場合、UntypedAgent インターフェースを次のようなより具体的なものに置き換えられます。

public interface NovelCreator {

@Agent
String createNovel(@V("topic") String topic, @V("audience") String audience, @V("style") String style);
}

これにより、novelCreator エージェントは次のように作成・使用できます。

NovelCreator novelCreator = AgenticServices
.sequenceBuilder(NovelCreator.class)
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.build();

String story = novelCreator.createNovel("dragons and wizards", "young adults", "fantasy");

ループワークフロー​

LLM の能力をより活用する一般的な方法は、物語などのテキストを編集・改善できるエージェントを繰り返し呼び出して、反復的に洗練することです。これは、特定の条件を満たすまでエージェントを複数回呼び出すループワークフローパターンで実現できます。

必要なスタイルとの整合性をスコアに基づいて評価する StyleScorer エージェントを使用できます。

public interface StyleScorer {

@UserMessage("""
You are a critical reviewer.
Give a review score between 0.0 and 1.0 for the following
story based on how well it aligns with the style '{{style}}'.
Return only the score and nothing else.

The story is: "{{story}}"
""")
@Agent("Scores a story based on how well it aligns with a given style")
double scoreStyle(@V("story") String story, @V("style") String style);
}

次に、このエージェントを StyleEditor とループで使用し、スコアが 0.8 などのしきい値に達するか、最大反復回数に達するまで物語を反復的に改善できます。

StyleEditor styleEditor = AgenticServices
.agentBuilder(StyleEditor.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

StyleScorer styleScorer = AgenticServices
.agentBuilder(StyleScorer.class)
.chatModel(BASE_MODEL)
.outputKey("score")
.build();

UntypedAgent styleReviewLoop = AgenticServices
.loopBuilder()
.subAgents(styleScorer, styleEditor)
.maxIterations(5)
.exitCondition( agenticScope -> agenticScope.readState("score", 0.0) >= 0.8)
.build();

ここで styleScorer エージェントは出力を "score" という名前の AgenticScope 共有変数に書き込み、ループの終了条件で同じ変数にアクセスして評価します。

exitCondition メソッドは引数として Predicate<AgenticScope> を受け取り、デフォルトでは各エージェント呼び出しの後に評価されます。これにより、呼び出し回数を可能な限り減らすため、条件が満たされるとすぐにループが終了します。ただし、ループの最後でのみ終了条件を確認し、条件をテストする前にすべてのエージェントを必ず呼び出すこともできます。その場合は、ループビルダーを testExitAtLoopEnd(true) メソッドで設定します。あるいは、exitCondition メソッドは第 2 引数として現在のループ反復回数を受け取る BiPredicate<AgenticScope, Integer> も受け取れます。たとえば、次のループ定義では、

UntypedAgent styleReviewLoop = AgenticServices
.loopBuilder()
.subAgents(styleScorer, styleEditor)
.maxIterations(5)
.testExitAtLoopEnd(true)
.exitCondition( (agenticScope, loopCounter) -> {
double score = agenticScope.readState("score", 0.0);
return loopCounter <= 3 ? score >= 0.8 : score >= 0.6;
})
.build();

最初の 3 回の反復でスコアが少なくとも 0.8 ならループを終了し、それ以外では品質への期待を下げ、スコアが少なくとも 0.6 になった時点で終了します。また、終了条件が満たされた後でも、最後にもう一度 styleEditor エージェントを強制的に呼び出します。

この styleReviewLoop を設定した後は、単一のエージェントと見なして CreativeWriter エージェントとシーケンスに組み込み、StyledWriter エージェントを作成できます。

public interface StyledWriter {

@Agent
String writeStoryWithStyle(@V("topic") String topic, @V("style") String style);
}

これにより、物語生成とスタイルレビューのプロセスを組み合わせた、より複雑なワークフローを実装します。

CreativeWriter creativeWriter = AgenticServices
.agentBuilder(CreativeWriter.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

StyledWriter styledWriter = AgenticServices
.sequenceBuilder(StyledWriter.class)
.subAgents(creativeWriter, styleReviewLoop)
.outputKey("story")
.build();

String story = styledWriter.writeStoryWithStyle("dragons and wizards", "comedy");

並列ワークフロー​

特に同じ入力に対して独立して作業できる場合、複数のエージェントを並列に呼び出すことが有用なことがあります。これは、複数のエージェントを同時に呼び出して出力を単一の結果に結合する、並列ワークフローパターンで実現できます。

たとえば、映画と食事を組み合わせて、指定されたムードに合う素敵な夜のプランをいくつか生成するために、映画と料理の専門家を使ってみましょう。

public interface FoodExpert {

@UserMessage("""
You are a great evening planner.
Propose a list of 3 meals matching the given mood.
The mood is {{mood}}.
For each meal, just give the name of the meal.
Provide a list with the 3 items and nothing else.
""")
@Agent
List<String> findMeal(@V("mood") String mood);
}

public interface MovieExpert {

@UserMessage("""
You are a great evening planner.
Propose a list of 3 movies matching the given mood.
The mood is {mood}.
Provide a list with the 3 items and nothing else.
""")
@Agent
List<String> findMovie(@V("mood") String mood);
}

2 人の専門家の作業は独立しているため、次のように AgenticServices.parallelBuilder() メソッドを使用して並列に呼び出すことができます。

FoodExpert foodExpert = AgenticServices
.agentBuilder(FoodExpert.class)
.chatModel(BASE_MODEL)
.outputKey("meals")
.build();

MovieExpert movieExpert = AgenticServices
.agentBuilder(MovieExpert.class)
.chatModel(BASE_MODEL)
.outputKey("movies")
.build();

EveningPlannerAgent eveningPlannerAgent = AgenticServices
.parallelBuilder(EveningPlannerAgent.class)
.subAgents(foodExpert, movieExpert)
.executor(Executors.newFixedThreadPool(2))
.outputKey("plans")
.output(agenticScope -> {
List<String> movies = agenticScope.readState("movies", List.of());
List<String> meals = agenticScope.readState("meals", List.of());

List<EveningPlan> moviesAndMeals = new ArrayList<>();
for (int i = 0; i < movies.size(); i++) {
if (i >= meals.size()) {
break;
}
moviesAndMeals.add(new EveningPlan(movies.get(i), meals.get(i)));
}
return moviesAndMeals;
})
.build();

List<EveningPlan> plans = eveningPlannerAgent.plan("romantic");

ここで EveningPlannerAgent に定義した AgenticScope の output 関数により、2 つのサブエージェントの出力を組み立て、指定されたムードに合う映画と食事を組み合わせた EveningPlan オブジェクトのリストを作成できます。output メソッドは並列ワークフローで特に重要ですが、単に AgenticScope の値を返す代わりに、サブエージェントの出力を単一の結果へ結合する方法を定義するため、実際には任意のワークフローパターンで使用できます。executor メソッドでは、サブエージェントの並列実行に使用する Executor を任意で提供できます。指定しない場合、デフォルトで内部キャッシュスレッドプールが使用されます。

並列マッパーワークフロー​

並列マッパーワークフローは、コレクション内の各項目に対して同じサブエージェントを 1 回ずつ並列に複数回実行する、並列ワークフローの変種です。言い換えると、リストのすべての項目をマッピングし、同じサブエージェントを複数回呼び出して各項目を独立して処理します。同じ操作を入力のバッチに同時適用する必要がある場合に便利です。

たとえば、人物のリストに対してパーソナライズされた星占いを生成するエージェントを作成しましょう。

public interface PersonAstrologyAgent {

@SystemMessage("""
You are an astrologist that generates horoscopes based on the user's name and zodiac sign.
""")
@UserMessage("""
Generate the horoscope for {{person}}.
The person has a name and a zodiac sign. Use both to create a personalized horoscope.
""")
@Agent(description = "An astrologist that generates horoscopes for a person", outputKey = "horoscope")
String horoscope(@V("person") Person person);
}

AgenticServices.parallelMapperBuilder() を使用すると、コレクションに対してこのエージェントをファンアウトし、項目ごとに 1 インスタンスを自動作成するワークフローを作成できます。

PersonAstrologyAgent personAstrologyAgent = AgenticServices
.agentBuilder(PersonAstrologyAgent.class)
.chatModel(BASE_MODEL)
.outputKey("horoscope")
.build();

BatchHoroscopeAgent agent = AgenticServices
.parallelMapperBuilder(BatchHoroscopeAgent.class)
.subAgents(personAstrologyAgent)
.itemsProvider("persons")
.executor(Executors.newFixedThreadPool(3))
.build();

List<Person> persons = List.of(
new Person("Mario", "aries"),
new Person("Luigi", "pisces"),
new Person("Peach", "leo"));

List<String> horoscopes = agent.generateHoroscopes(persons);

BatchHoroscopeAgent は次のように定義します。

public interface BatchHoroscopeAgent extends AgentInstance {

@Agent
List<String> generateHoroscopes(@V("persons") List<Person> persons);
}

itemsProvider は、反復処理するコレクションを含む引数を指定します。ただし、この例のように曖昧さがなく、反復可能な引数(Collection または配列)が 1 つだけなら、安全に省略できます。サブエージェントの各インスタンスはコレクションから 1 項目を受け取り、すべてのインスタンスが完了すると、個々の結果が自動的にリストへ集約され、ワークフローの結果として返されます。並列ワークフローと同様に、Executor は任意で指定できます。

同じエージェントが異なる引数で同じタスクを繰り返し独立して実行するため、その ChatMemory を保持しても意味がないことに注意してください。このため、並列マッパーワークフローが ChatMemory を使用する設定のサブエージェントを使おうとすると、LangChain4j は例外をスローします。

条件付きワークフロー​

特定の条件が満たされた場合にのみ、特定のエージェントを呼び出す必要もよくあります。たとえば、ユーザーリクエストを処理する前に分類すると、リクエストのカテゴリに応じて異なるエージェントで処理できます。これは、次の CategoryRouter を使用して実現できます。

public interface CategoryRouter {

@UserMessage("""
Analyze the following user request and categorize it as 'legal', 'medical' or 'technical'.
In case the request doesn't belong to any of those categories categorize it as 'unknown'.
Reply with only one of those words and nothing else.
The user request is: '{{request}}'.
""")
@Agent("Categorizes a user request")
RequestCategory classify(@V("request") String request);
}

これは RequestCategory 列挙値を返します。

public enum RequestCategory {
LEGAL, MEDICAL, TECHNICAL, UNKNOWN
}

このように、次のような MedicalExpert エージェントと、

public interface MedicalExpert {

@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 {{request}}.
""")
@Agent("A medical expert")
String medical(@V("request") String request);
}

同様の LegalExpert および TechnicalExpert エージェントを定義すると、ExpertRouterAgent を作成できます。

public interface ExpertRouterAgent {

@Agent
String ask(@V("request") String request);
}

これは、ユーザーリクエストのカテゴリに基づいて適切なエージェントを呼び出す条件付きワークフローを実装します。

CategoryRouter routerAgent = AgenticServices
.agentBuilder(CategoryRouter.class)
.chatModel(BASE_MODEL)
.outputKey("category")
.build();

MedicalExpert medicalExpert = AgenticServices
.agentBuilder(MedicalExpert.class)
.chatModel(BASE_MODEL)
.outputKey("response")
.build();
LegalExpert legalExpert = AgenticServices
.agentBuilder(LegalExpert.class)
.chatModel(BASE_MODEL)
.outputKey("response")
.build();
TechnicalExpert technicalExpert = AgenticServices
.agentBuilder(TechnicalExpert.class)
.chatModel(BASE_MODEL)
.outputKey("response")
.build();

UntypedAgent expertsAgent = AgenticServices.conditionalBuilder()
.subAgents( agenticScope -> agenticScope.readState("category", RequestCategory.UNKNOWN) == RequestCategory.MEDICAL, medicalExpert)
.subAgents( agenticScope -> agenticScope.readState("category", RequestCategory.UNKNOWN) == RequestCategory.LEGAL, legalExpert)
.subAgents( agenticScope -> agenticScope.readState("category", RequestCategory.UNKNOWN) == RequestCategory.TECHNICAL, technicalExpert)
.build();

ExpertRouterAgent expertRouterAgent = AgenticServices
.sequenceBuilder(ExpertRouterAgent.class)
.subAgents(routerAgent, expertsAgent)
.outputKey("response")
.build();

String response = expertRouterAgent.ask("I broke my leg what should I do");

条件付きワークフローは、この例のように複数の選択肢から選ぶ場合に適したツールです。単一のエージェントを呼び出すかどうかを決めることだけが目的なら、そのエージェントにアクティベーション条件を設定する方が簡単です。

任意のエージェント​

ワークフロー内のサブエージェントは、AgenticScope に入力引数が存在しない場合、実行する必要がないことがあります。デフォルトでは、エージェントが必要な引数のいずれかを見つけられないと、エージェント型システム全体が MissingArgumentException で失敗します。ただし、エージェントを任意としてマークすると、引数が欠けている場合にワークフロー全体を失敗させるのではなく、実行をスキップできます。

これはエージェントビルダーの optional メソッドで行えます。たとえば、上で定義した順次ワークフローでは、AudienceEditor エージェントを任意にできます。これにより、入力に読者層が指定されていなくても、物語は生成されスタイル編集されます。

CreativeWriter creativeWriter = AgenticServices
.agentBuilder(CreativeWriter.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

AudienceEditor audienceEditor = AgenticServices
.agentBuilder(AudienceEditor.class)
.chatModel(BASE_MODEL)
.optional(true)
.outputKey("story")
.build();

StyleEditor styleEditor = AgenticServices
.agentBuilder(StyleEditor.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

UntypedAgent novelCreator = AgenticServices
.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.build();

// No "audience" key is provided, so the audienceEditor will be skipped
Map<String, Object> input = Map.of(
"topic", "dragons and wizards",
"style", "fantasy"
);

String story = (String) novelCreator.invoke(input);

ここで audienceEditor エージェントは任意として設定されています。入力マップには AudienceEditor が必要とする "audience" キーがないため、その呼び出しはスキップされ、ワークフローは直接 StyleEditor に進みます。同じエージェントは、@Agent アノテーション属性の @Agent(optional = true) を使用して宣言的に任意としてマークすることもできます。

アクティベーション条件​

任意のエージェントは、引数のいずれかが欠けている場合にのみスキップされます。より一般的には、どのエージェントもアクティベーション条件、つまりそのエージェントを実行するかどうかを決める AgenticScope 上の述語を宣言できます。エージェントがエージェント型システムのサブエージェントとして呼び出され、その条件が false の場合、そのエージェントはスキップされます。これにより、呼び出すかどうかを決めるためだけにエージェントを条件付きワークフローで包む必要がなくなります。

たとえば、先ほど定義した順次ワークフローをもう一度考えると、AudienceEditor を、特定の読者層向けの場合にのみ物語を編集するように設定できます。

AudienceEditor audienceEditor = AgenticServices
.agentBuilder(AudienceEditor.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.activationCondition("the story targets a specific audience",
agenticScope -> !agenticScope.readState("audience", "everyone").equals("everyone"))
.build();

条件の説明は任意で、デフォルトは <unknown> です。ログ、AgentMonitor、およびモニタリングのセクションで説明する HTML レポートに表示されます。スーパーバイザーのサブエージェントがスキップされた場合、その説明はスキップの理由としてスーパーバイザーのモデルにも送信されるため、モデルに渡してはならない内容を含めないでください。activationCondition メソッドは、あらゆる種類のエージェントのビルダーで利用できます。AI エージェント、スーパーバイザーを含むすべてのワークフローとプランナー、nonAiAgentBuilder で作成された非 AI エージェント、ヒューマン・イン・ザ・ループのエージェント、A2A および MCP クライアントエージェントが対象です。

同じ条件は、boolean を返し、値なしの @ActivationCondition をアノテートした静的メソッドにより、エージェントのインターフェース上で宣言することもできます。

public interface AudienceEditor {

@UserMessage("""
You are a professional editor.
Analyze and rewrite the following story to better align
with the target audience of {{audience}}.
Return only the story and nothing else.
The story is "{{story}}".
""")
@Agent("Edits a story to better fit a given audience")
String editStory(@V("story") String story, @V("audience") String audience);

@ActivationCondition(description = "the story targets a specific audience")
static boolean hasSpecificAudience(AgenticScope agenticScope) {
return !agenticScope.readState("audience", "everyone").equals("everyone");
}
}

ここでは、メソッドが AgenticScope 自体を受け取ります。キーが存在しない可能性がある場合は、この方法が望ましいです。他のアノテート済み静的メソッドと同様に、@V("audience") String audience のように AgenticScope から読み取る引数を宣言することもできますが、その場合は引数が欠けていると条件が失敗し、それに伴ってエージェントの呼び出しも失敗します。この方法による条件の宣言は、あらゆる種類のエージェントで可能です。AI エージェント、静的な @Agent メソッドを持つクラス、宣言型 API で定義されたワークフローとプランナー、@HumanInTheLoop、@A2AClientAgent、@McpClientAgent でアノテートされたエージェントが対象です。@RegistryAgent ではサポートされません。そのエージェントはエージェントレジストリから構築済みの状態で取得されるためです。値を持つ @ActivationCondition は、代わりに @ConditionalAgent でのみ許可され、そこでアクティブ化するサブエージェントを選択します。それ以外のクラスで使用すると設定エラーになります。

エージェントがスキップされると、次のようになります。

  • エージェントは呼び出されず、AgenticScope には何も書き込まれません。親のプランナーから見たその結果は、出力キーの現在の値であり、そのキーが存在しない場合やエージェントに出力キーがない場合は null です。
  • 条件は引数が読み取られる前に評価されるため、スキップされたエージェントが引数の欠落で失敗することはありません。
  • 非同期エージェントは、開始されることなく同期的にスキップされます。
  • AgentListener には onAgentSkipped メソッドで通知され、親のプランナーは skipped() メソッドが true を返す AgentInvocation を受け取ります。一方、その呼び出しは AgenticScope には登録されません。

条件は、エージェントがサブエージェントとして呼び出される直前に毎回評価されます。そのため、ループ内では各反復で評価され、並列マッパーでは、マップされたエージェントの条件が項目ごとに 1 回評価され、スキップされた項目は結果内のその位置に null を生成します。逆に、エージェントがエージェント型システムのルートとして直接呼び出される場合は条件は無視されるため、同じエージェントを両方の方法で使用できます。

条件は、1 回の呼び出しに対して複数回評価されることもあります。スーパーバイザー、ピアツーピア、ブラックボード、ゴール指向、決定ルーター、信頼度カスケードなどの一部のプランナーは、次のエージェントを選択する際に条件を評価し、そのエージェントが呼び出されるときに再度評価されます。このため、条件は低コストで副作用がないものでなければなりません。特に、@ActivationCondition で宣言された条件の引数は AgenticScope から読み取られるだけです。エージェントの引数とは異なり、宣言された型に変換された値はスコープに書き戻されません。

例外をスローする条件は、そのエージェントの失敗として扱われます。例外は AgentInvocationException にラップされ、親のエラーハンドラーに渡されるため、たとえばエージェントを再試行すると条件が再度評価されます。

ワークフローまたはプランナーの条件は、そのすべてのサブエージェントをまとめて制御します。条件が false の場合、どのサブエージェントも呼び出されません。条件が成立すると、複合エージェントは完了するまでアクティブ化されたものとみなされます。そのため、たとえば人間を待つ一時停止の後に再開される場合や、クラッシュ後に復旧される場合に、その間に自身のサブエージェントによって条件が false になっていても、中断した場所から続行します。

アクティベーション条件と任意のエージェントは組み合わせられます。まず条件が評価され、アクティブ化された任意のエージェントでも、引数のいずれかが欠けていればスキップされます。どちらの場合も、リスナーとプランナーには同じ方法で通知されます。

最後に、アクティベーション条件は単一のエージェントを制御するものであり、リクエストを適切な専門家にルーティングするように、複数の選択肢から選ぶ方法としては条件付きワークフローが引き続き適しています。条件付きワークフローのサブエージェントが独自のアクティベーション条件を持つ場合、そのブランチの条件と自身の条件の両方が成立したときにのみ実行されます。

非同期エージェント​

デフォルトでは、すべてのエージェント呼び出しはエージェント型システムのルートエージェントを呼び出したのと同じスレッドで実行されるため、同期的です。つまり、エージェント型システムの実行は、次のエージェントに進む前に各エージェントの完了を待機します。しかし、多くの場合これは必要ではなく、エージェントを非同期に呼び出し、そのエージェントの完了を待たずにエージェント型システムの実行を続行すると便利です。

このため、エージェントビルダーの async メソッドを使用してエージェントを非同期として指定できます。指定すると、そのエージェントの呼び出しは別スレッドで実行され、エージェント型システムの実行は完了を待たずに続行します。非同期エージェントの結果は完了次第 AgenticScope で利用可能になり、別のエージェントの後続呼び出しへの入力として必要になった場合にのみ、AgenticScope はその結果を待ってブロックされます。

たとえば、並列ワークフローのセクションで扱った FoodExpert と MovieExpert は互いに独立しているため、各サブエージェントで .async(true) により非同期として指定すると、順次ワークフロー内で使用しても同時に実行されます。parallelBuilder() とは異なり、sequenceBuilder() には executor() メソッドがありません。任意の executor() は並列ワークフロー専用です。

FoodExpert foodExpert = AgenticServices
.agentBuilder(FoodExpert.class)
.chatModel(BASE_MODEL)
.async(true)
.outputKey("meals")
.build();

MovieExpert movieExpert = AgenticServices
.agentBuilder(MovieExpert.class)
.chatModel(BASE_MODEL)
.async(true)
.outputKey("movies")
.build();

EveningPlannerAgent eveningPlannerAgent = AgenticServices
.sequenceBuilder(EveningPlannerAgent.class)
.subAgents(foodExpert, movieExpert)
.outputKey("plans")
.output(agenticScope -> {
List<String> movies = agenticScope.readState("movies", List.of());
List<String> meals = agenticScope.readState("meals", List.of());

List<EveningPlan> moviesAndMeals = new ArrayList<>();
for (int i = 0; i < movies.size(); i++) {
if (i >= meals.size()) {
break;
}
moviesAndMeals.add(new EveningPlan(movies.get(i), meals.get(i)));
}
return moviesAndMeals;
})
.build();

List<EveningPlan> plans = eveningPlannerAgent.plan("romantic");

結果を誰も読まない非同期エージェントについては、エージェント型システムのルート呼び出しもそれを待ちません。他のエージェントが完了するとすぐに、そのエージェントが実行中のまま戻り、他のルート呼び出しと同様に、AgenticScope はその時点で終了し、そのエージェントを待ちません。これにより、数分かかるリモートのコーディングエージェントに委任する修正のような、長時間かかる副次的なタスクをワークフローの最後のエージェントに委任し、ワークフロー自体は数秒で結果を返すことができます。

RemediationAgent remediation = AgenticServices
.a2aBuilder(REMEDIATION_SERVER_URL, RemediationAgent.class)
.async(true)
.outputKey("fix")
.listener(new AgentListener() {
@Override
public void afterAgentInvocation(AgentResponse response) {
// called when the remediation completes, after analyze(...) returned
notifyTeam(response.output());
}
})
.build();

RolloutAnalysis analysis = AgenticServices
.sequenceBuilder(RolloutAnalysis.class)
.subAgents(dataCollector, scorer, remediation)
.outputKey("decision")
.build();

String decision = analysis.analyze(rollout); // returns while the remediation is still running

このようなエージェントの結果は、次の 2 つの方法で受け取れます。

  • そのエージェントの AgentListener の afterAgentInvocation が、エージェントの完了時に呼び出されます。これが結果を受け取る方法であり、上の例でリスナーがエージェント自体に登録されているのはこのためです。
  • 結果は、エージェントの出力キーで AgenticScope に書き込まれ、同じメモリ ID での後続のルート呼び出しがそれを読み取れます。

たとえばテストなどで、このようなエージェントをどうしても待つ場合は、ResultWithAgenticScope を返すメソッドを通じてエージェント型システムを呼び出し、エージェントの出力キーを読み取ります。readState はエージェントの完了を待ちます。

public interface RolloutAnalysisWithScope {

@Agent
ResultWithAgenticScope<String> analyze(@V("rollout") String rollout);
}

RolloutAnalysisWithScope analysis = AgenticServices
.sequenceBuilder(RolloutAnalysisWithScope.class)
.subAgents(dataCollector, scorer, remediation)
.outputKey("decision")
.build();

ResultWithAgenticScope<String> result = analysis.analyze(rollout); // returns while the remediation is still running
String fix = result.agenticScope().readState("fix", ""); // waits for the remediation to complete

このようなエージェントが失敗した場合:

  • エージェント型システムのエラーハンドラーが、そのエージェントのスレッド上で失敗を処理し、そのリスナーの onAgentInvocationError に通知されます。ルート呼び出しはすでに結果を返しているため、そのための補償は実行されません。
  • エラーハンドラーが失敗から回復した場合を除き、AgentMonitor は実行を失敗として記録します。
  • 失敗したエージェントの結果を読み取ると、同じメモリ ID での次のルート呼び出しが開始されて破棄されるまで、その失敗がスローされます。AgenticScope の保存済みコピーにはそれが含まれることはありません。

このようなエージェントがエージェント型システムを一時停止させる場合(たとえば、リモートタスクが追加の入力を必要とする A2A クライアントエージェント):

  • 同期エージェントと同様に、その保留中のレスポンスは AgenticScope に残り、その結果を読み取るエージェントは通常どおりエージェント型システムを一時停止させます。
  • ルート呼び出しが一時停止に気付かないまま戻る場合、呼び出し元に AgenticSystemSuspendedException をスローできないため、代わりにエージェント型システムのリスナーの onAgenticSystemSuspended に通知されます。同じメモリ ID での次のルート呼び出しは、保留中のレスポンスが完了していればそこから再開し、そうでなければ再び一時停止します。

AgenticScope と後続のルート呼び出しは次のように動作します。

  • 一時的な AgenticScope は通常どおりルート呼び出しの終了時に破棄されるため、beforeAgenticScopeDestroyed は、そのスコープでまだ実行中の非同期エージェントのイベントよりも前に通知されます。これらのエージェントは引き続きスコープに結果を書き込み、呼び出し元は ResultWithAgenticScope を通じてそれを読み取れます。
  • 永続化される AgenticScope は、ルート呼び出しの終了時に保留中の結果を除いて保存され、それぞれの結果が完了するたびに再度保存されます。
  • 同じメモリ ID での後続のルート呼び出しは、開始前に、前回の呼び出しでまだ実行中の非同期エージェントを待ちます。これにより、AgenticScope 上で同時に実行されるルート呼び出しは 1 つだけになります。したがって、前回の呼び出しが戻った直後に同じメモリ ID で再度呼び出す呼び出し元は、それらが完了するまでブロックされる可能性があります。

次の点にも注意してください。

  • 非同期エージェントは LangChain4j のデフォルトのエグゼキューター上で実行されるため、JVM が終了すると、保留中の処理は失われます。
  • 一部の非同期エージェントがまだ実行中のうちにルート呼び出しが終了した場合、AgenticScope はそれらの出力キーをデバッグレベルでログに記録します。これにより、ルート呼び出しが非同期エージェントによってブロックされたのか、待たずに戻ったのかを判断できます。
  • ルートエージェントの output 関数または出力キーは、他のエージェントと同様に AgenticScope を読み取ります。結果を読み取る非同期エージェントは、上記の夜の予定プランナーの例のように、ルート呼び出しが戻る前に待機されます。

ストリーミングエージェント​

ストリーミングをサポートするため、TokenStream を返すエージェントを作成することもできます。

public interface StreamingCreativeWriter {

@UserMessage("""
You are a creative writer.
Generate a draft of a story no more than
3 sentences long around the given topic.
Return only the story and nothing else.
The topic is {{topic}}.
""")
@Agent("Generates a story based on the given topic")
TokenStream generateStory(@V("topic") String topic);
}

次に StreamingChatModel を使用するよう設定すると、エージェント呼び出しの完了を待つ代わりに、生成中の結果を消費できます。

StreamingCreativeWriter creativeWriter = AgenticServices.agentBuilder(StreamingCreativeWriter.class)
.streamingChatModel(streamingBaseModel())
.outputKey("story")
.build();

TokenStream tokenStream = creativeWriter.generateStory("dragons and wizards");

エージェント型システム内で使用する場合、ストリーミングエージェントは、最後に呼び出されるエージェントである場合にのみストリーミング応答をシステム全体へ伝播できます。それ以外の場合は非同期エージェントのように動作するため、後続のエージェントは結果を取得・使用するためにストリーミング応答の完了を待つ必要があります。

たとえば、次の StreamingReviewedWriter エージェントは、

public interface StreamingReviewedWriter {
@Agent
TokenStream writeStory(@V("topic") String topic, @V("audience") String audience, @V("style") String style);
}

3 つのストリーミングエージェントのシーケンスで実装されます。

StreamingCreativeWriter creativeWriter = AgenticServices.agentBuilder(StreamingCreativeWriter.class)
.streamingChatModel(streamingBaseModel())
.outputKey("story")
.build();

StreamingAudienceEditor audienceEditor = AgenticServices.agentBuilder(StreamingAudienceEditor.class)
.streamingChatModel(streamingBaseModel())
.outputKey("story")
.build();

StreamingStyleEditor styleEditor = AgenticServices.agentBuilder(StreamingStyleEditor.class)
.streamingChatModel(streamingBaseModel())
.outputKey("story")
.build();

StreamingReviewedWriter novelCreator = AgenticServices.sequenceBuilder(StreamingReviewedWriter.class)
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.build();

この novelCreator エージェントを呼び出すと、

TokenStream tokenStream = novelCreator.writeStory("dragons and wizards", "young adults", "fantasy");

後続エージェントの呼び出しを開始できる前に、最初の 2 エージェントのストリーミング応答は内部的に完全に消費され、最後の StyleEditor エージェントのストリーミング応答だけが novelCreator エージェント全体のストリーミング応答として伝播されます。

動的なチャットモデル選択​

デフォルトでは、エージェントはビルド時に単一の ChatModel にバインドされます。しかし、エージェント型システムの現在の状態に基づき、呼び出しごとに使用するモデルを動的に選択したい場合があります。たとえば、定常的な作業には安価で高速なモデルを使用し、品質しきい値が求める場合にはより高性能なモデルに切り替えることができます。

AgentBuilder の chatModel メソッドには、Function<AgenticScope, ChatModel> を受け取るオーバーロードがあります。

StoryEditor storyEditor = AgenticServices.agentBuilder(StoryEditor.class)
.chatModel(scope -> {
CritiqueResult critique = (CritiqueResult) scope.readState("critique");
return critique != null && critique.score() > 7.8 ? enhancedModel() : baseModel();
})
.outputKey("story")
.build();

この関数は現在の AgenticScope を受け取り、現在の呼び出しに使用する ChatModel を返します。この例では、StoryEditor エージェントは編集対象の物語の批評スコアが 7.8 未満で、まだ多くの改善が必要な場合にはデフォルトで baseModel() を使用します。スコアがそのしきい値を超え、最終調整により良いモデルが必要な場合は enhancedModel() に切り替えます。この関数は呼び出しのたびに評価されるため、同じエージェントでも呼び出し間でモデルを変更できます。

同じ動的選択は streamingChatModel メソッドでも可能です。

エラー処理​

複雑なエージェント型システムでは、エージェントが結果を生成できない、外部ツールが利用できない、エージェントの実行中に予期しないエラーが発生するなど、多くの問題が起こり得ます。

このため、errorHandler メソッドにより、次のように定義される ErrorContext を変換する関数を、エージェント型システムのエラーハンドラーとして提供できます。

record ErrorContext(String agentName, AgenticScope agenticScope, AgentInvocationException exception) { }

変換先の ErrorRecoveryResult には、次の 3 つの可能性があります。

  1. ErrorRecoveryResult.throwException():デフォルトの動作です。問題を引き起こした Exception をルート呼び出し元まで単純に伝播します。
  2. ErrorRecoveryResult.retry():必要に応じて修正アクションを実行した後、エージェント呼び出しを再試行します。
  3. ErrorRecoveryResult.result(Object result):問題を無視し、指定された結果を失敗したエージェントの成果として返します。

たとえば、順次ワークフローの最初の例で必要な引数が省略されると、

UntypedAgent novelCreator = AgenticServices
.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.build();

Map<String, Object> input = Map.of(
// missing "topic" entry to trigger an error
// "topic", "dragons and wizards",
"style", "fantasy",
"audience", "young adults"
);

実行は次のような例外で失敗します。

dev.langchain4j.agentic.agent.MissingArgumentException: Missing argument: topic

この場合、この問題を解決するには、次のように不足した引数を agenticScope に提供する適切な errorHandler を設定して、このエラーを処理・回復できます。

UntypedAgent novelCreator = AgenticServices.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.errorHandler(errorContext -> {
if (errorContext.agentName().equals("generateStory") &&
errorContext.exception() instanceof MissingArgumentException mEx && mEx.argumentName().equals("topic")) {
errorContext.agenticScope().writeState("topic", "dragons and wizards");
errorRecoveryCalled.set(true);
return ErrorRecoveryResult.retry();
}
return ErrorRecoveryResult.throwException();
})
.outputKey("story")
.build();

エージェント間補償​

エージェント型システムがツールを通じて副作用(データベースへの書き込み、API 呼び出し、金融取引など)を実行する場合、ワークフローの途中で失敗するとシステムが不整合な状態になる可能性があります。エージェント間補償はこの問題を解決、または少なくとも軽減しようとします。階層内の任意のエージェントが失敗すると、@CompensateFor アクションを持つ以前に成功したツール呼び出しがすべて逆順に補償されます。

これはエージェント単位の @CompensateFor メカニズム(ツールを参照)を基盤とします。エージェント単位の補償は単一エージェント内のツールエラーを処理するのに対し、エージェント間補償は階層全体にまたがるエージェントレベルの失敗を処理します。

この機能を有効にするには、合成エージェントビルダーで compensateOnError(true) を設定します。

UntypedAgent transferWorkflow = AgenticServices.sequenceBuilder()
.subAgents(creditAgent, debitAgent, notificationAgent)
.compensateOnError(true)
.outputKey("result")
.build();

notificationAgent が例外をスローすると、@CompensateFor メソッドを持つ creditAgent と debitAgent が呼び出したツールは、時系列の逆順(最後に実行されたものから先)で補償されます。

@CompensateFor アノテーションのないツールは、補償中に単にスキップされます。

補償アクションは、エージェント単位のツール補償と同じ @CompensateFor を使用してツールクラスに定義します。

public class AccountService {

@Tool("Credits the given amount to the account")
String credit(@P(name = "amount") int amount) {
// perform the credit
return "credited " + amount;
}

@CompensateFor("credit")
void reverseCredit(int amount) {
// reverse the credit
}
}

補償アクションはベストエフォート方針で実行されることに注意してください。いずれかが失敗してもエラーはログに記録され、残りの補償は続行されます。

可観測性​

エージェントの呼び出しを追跡・ログ記録することは、デバッグや、エージェントが参加するエージェント型システム全体の集約動作を理解するうえで非常に重要です。このため、langchain4j-agentic モジュールでは、エージェントビルダーの listener メソッドを通じて AgentListener を登録できます。このリスナーはすべてのエージェント呼び出しとその結果について通知を受け、次のように定義されます。

public interface AgentListener {

default void beforeAgentInvocation(AgentRequest agentRequest) { }
default void afterAgentInvocation(AgentResponse agentResponse) { }
default void onAgentInvocationError(AgentInvocationError agentInvocationError) { }
default void onAgentSkipped(AgentSkipped agentSkipped) { }

default void afterAgenticScopeCreated(AgenticScope agenticScope) { }
default void beforeAgenticScopeDestroyed(AgenticScope agenticScope) { }

default void onAgenticSystemSuspended(AgenticScope agenticScope) { }

default void beforeAgentToolExecution(BeforeAgentToolExecution beforeAgentToolExecution) { }
default void afterAgentToolExecution(AfterAgentToolExecution afterAgentToolExecution) { }

default void onAgentAiServiceEvent(AgentAiServiceEvent agentAiServiceEvent) { }

default boolean inheritedBySubagents() {
return false;
}
}

このインターフェースのすべてのメソッドにはデフォルトの空実装があるため、関心のあるメソッドだけを実装できます。これにより、将来のリリースで新しいメソッドが追加されても既存の実装を壊さずに済みます。

たとえば、次の CreativeWriter エージェントの設定では、呼び出されたときと、生成した物語をコンソールにログ出力します。

CreativeWriter creativeWriter = AgenticServices.agentBuilder(CreativeWriter.class)
.chatModel(baseModel())
.outputKey("story")
.listener(new AgentListener() {
@Override
public void beforeAgentInvocation(AgentRequest request) {
System.out.println("Invoking CreativeWriter with topic: " + request.inputs().get("topic"));
}

@Override
public void afterAgentInvocation(AgentResponse response) {
System.out.println("CreativeWriter generated this story: " + response.output());
}
})
.build();

これらのリスナーメソッドは、それぞれ AgentRequest と AgentResponse を引数として受け取ります。これらはエージェントの名前、受け取った入力、生成した出力、さらにその呼び出しに使用された AgenticScope のインスタンスなど、エージェント呼び出しに関する有用な情報を提供します。これらのメソッドはエージェント呼び出しを実行するスレッドと同じスレッドで呼び出されるため、呼び出しと同期的であり、長時間ブロックする処理を実行すべきではありません。

AI エージェントでは、AgentResponse の chatRequest() および chatResponse() メソッドも、その呼び出し中にエージェントがチャットモデルへ送信した最後のリクエストと、受け取ったレスポンスを返します。トークン使用量には、たとえばエージェントがツールを呼び出した場合など、その呼び出しで行われたすべてのモデル呼び出しが含まれます。決定エージェントでは、decisionResponse() メソッドが決定モデルのレスポンスを返します。これらのメソッドは他の種類のエージェントでは null を返し、TokenStream を返すエージェントでは、モデル呼び出しが呼び出しの報告後にしか完了しないため、chatRequest() と chatResponse() も null を返します。

エージェントが、アクティベーション条件が false であるため、または任意で引数のいずれかが欠けているためにスキップされた場合、これらのメソッドはいずれも呼び出されず、代わりに onAgentSkipped メソッドが、スキップされたエージェントとスキップの理由を持つ AgentSkipped を受け取ります。

onAgentAiServiceEvent メソッドは、LLM ベースのエージェントの AI サービスイベントを受け取ります。たとえば、モデルに送信された各リクエスト、モデルから受け取ったレスポンス、ツールの実行、最終的な完了やエラーなどで、これらは AgentAiServiceEvent にラップされます。AgentAiServiceEvent は、イベントを生成したエージェント(そこから親エージェントをたどれます)とその AgenticScope も提供します。たとえば、次のリスナーはエージェント型システムのルートに登録され、そのすべてのサブエージェントに継承されて、すべてのモデル呼び出しのトークン使用量を、それを行ったエージェントの名前とともにログに記録します。

UntypedAgent novelCreator = AgenticServices.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.listener(new AgentListener() {
@Override
public void onAgentAiServiceEvent(AgentAiServiceEvent event) {
if (event.aiServiceEvent() instanceof AiServiceResponseReceivedEvent response) {
System.out.println(event.agentName() + " used " + response.response().tokenUsage());
}
}

@Override
public boolean inheritedBySubagents() {
return true;
}
})
.build();

これらのイベントは、エージェントの beforeAgentInvocation と afterAgentInvocation または onAgentInvocationError の間に、それらを生成するスレッド上で通知されます。ストリーミングまたは非同期エージェントでは、これはエージェントを呼び出したスレッドとは異なる場合があります。AiServiceInvocationSummaryEvent は他のイベントを集約するだけなので、AgentListener には通知されません。

AI サービス用に書かれた既存のリスナーは、AgentListener.forAiServiceListeners を通じてエージェントでも再利用できます。これは、AI サービスと同様に、それぞれのイベントクラスのイベントを各リスナーに通知する AgentListener を作成します。最初の引数は、そのリスナーをサブエージェントにも継承させるかどうかを指定します。

UntypedAgent novelCreator = AgenticServices.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.listener(AgentListener.forAiServiceListeners(true, tokenUsageListener, toolExecutionListener))
.build();

これらのリスナーは AI サービスイベントそのものを受け取ります。イベントを生成したエージェントも必要な場合は、onAgentAiServiceEvent を実装してください。

AgentListener には次の 2 つの重要な性質があります。

  • 合成可能:listener メソッドを複数回呼び出すことで同じエージェントに複数のリスナーを登録でき、登録順に通知されます。
  • 任意で階層的:デフォルトでは直接登録されたエージェントに対してのみローカルですが、inheritedBySubagents メソッドが true を返すようにするだけで、すべてのサブエージェントに継承させることもできます。この場合、トップレベルエージェントに登録したリスナーは、任意のレベルにあるすべてのサブエージェントの呼び出しについても通知を受け、それらのサブエージェントが独自に登録している可能性のあるすべてのリスナーと合成されます。

モニタリング​

AgentListener インターフェースが提供する可観測性機能を活用し、langchain4j-agentic モジュールはこのインターフェースの組み込み実装である AgentMonitor も提供します。これはすべてのサブエージェントに継承されるよう設定されており、すべてのエージェント呼び出しをインメモリのツリー構造に記録することを目的とします。これにより、エージェント型システムの実行中または実行後に、呼び出しの順序とその結果を調べられます。このモニターは、エージェントビルダーの listener メソッドを使用して、エージェント型システムのルートエージェントにリスナーとして登録できます。

より包括的な例として、必要なスタイル品質に達するまで物語を生成して反復的に洗練するループワークフローを再考し、AgentMonitor を含むいくつかのリスナーを登録してみましょう。

AgentMonitor monitor = new AgentMonitor();

CreativeWriter creativeWriter = AgenticServices.agentBuilder(CreativeWriter.class)
.listener(new AgentListener() {
@Override
public void beforeAgentInvocation(AgentRequest request) {
System.out.println("Invoking CreativeWriter with topic: " + request.inputs().get("topic"));
}
})
.chatModel(baseModel())
.outputKey("story")
.build();

StyleEditor styleEditor = AgenticServices.agentBuilder(StyleEditor.class)
.chatModel(baseModel())
.outputKey("story")
.build();

StyleScorer styleScorer = AgenticServices.agentBuilder(StyleScorer.class)
.name("styleScorer")
.chatModel(baseModel())
.outputKey("score")
.build();

UntypedAgent styleReviewLoop = AgenticServices.loopBuilder()
.subAgents(styleScorer, styleEditor)
.maxIterations(5)
.exitCondition(agenticScope -> agenticScope.readState("score", 0.0) >= 0.8)
.build();

UntypedAgent styledWriter = AgenticServices.sequenceBuilder()
.subAgents(creativeWriter, styleReviewLoop)
.listener(monitor)
.listener(new AgentListener() {
@Override
public void afterAgentInvocation(AgentResponse response) {
if (response.agentName().equals("styleScorer")) {
System.out.println("Current score: " + response.output());
}
}
})
.outputKey("story")
.build();

ここでは、最初のリスナーを creativeWriter エージェントに直接登録しているため、そのエージェントが呼び出された場合にのみ、生成する物語のリクエストトピックをログに記録します。2 番目のリスナーはトップレベルの styledWriter エージェントに登録されているため、そのエージェントの階層内の任意レベルにあるすべてのサブエージェントについても呼び出されます。そのため、このリスナーの afterAgentInvocation メソッドは、呼び出されるエージェントが styleScorer であるか確認し、その場合にのみ生成された物語のスタイルに割り当てられた現在のスコアをログに記録します。

最後に、AgentMonitor インスタンスも styledWriter トップレベルエージェントの追加リスナーとして登録され、他の 2 つのリスナーと自動的に合成されます。これにより、エージェント型システム全体のすべてのエージェント呼び出しを追跡できます。

次のように styledWriter エージェントを呼び出すと、

Map<String, Object> input = Map.of(
"topic", "dragons and wizards",
"style", "comedy");
String story = styledWriter.invoke(input);

AgentMonitor は、すべてのエージェント呼び出しをツリー構造で記録し、各エージェント呼び出しの開始時刻、終了時刻、所要時間、トークン、入力、出力も追跡します。AI エージェントでは、その AgentInvocation の modelName() メソッドも、最後の LLM 呼び出しに応答したモデルの名前を、プロバイダーがレスポンスのメタデータで報告したとおりに返します。そのため、ワークフローや非 AI エージェント、およびこれを報告しないプロバイダーでは空になります。この時点で、モニターから記録された実行内容を取得し、たとえばコンソールに出力して確認できます。

MonitoredExecution execution = monitor.successfulExecutions().get(0);
System.out.println(execution);

これにより、物語の生成と洗練に必要な、ネストされたエージェント呼び出しのシーケンスが次のように表示されます。

AgentInvocation{agent=Sequential, startTime=2026-03-18T17:27:28.099439515, finishTime=2026-03-18T17:27:38.683498783, duration=10584 ms, tokens=0, inputs={topic=dragons and wiz..., style=comedy}, output=In a realm wher...}
|=> AgentInvocation{agent=generateStory, startTime=2026-03-18T17:27:28.1.23.0287, finishTime=2026-03-18T17:27:31.033561726, duration=2932 ms, tokens=127, inputs={topic=dragons and wiz...}, output=In a realm wher...}
|=> AgentInvocation{agent=reviewLoop, startTime=2026-03-18T17:27:31.035952285, finishTime=2026-03-18T17:27:38.683438433, duration=7647 ms, tokens=0, inputs={score=0.8, topic=dragons and wiz..., style=comedy, story=In a realm wher...}, output=null}
|=> AgentInvocation{agent=scoreStyle, iteration=0, startTime=2026-03-18T17:27:31.036155107, finishTime=2026-03-18T17:27:31.671478699, duration=635 ms, tokens=152, inputs={style=comedy, story=In a realm wher...}, output=0.2}
|=> AgentInvocation{agent=editStory, iteration=0, startTime=2026-03-18T17:27:31.671711250, finishTime=2026-03-18T17:27:38.182881941, duration=6511 ms, tokens=491, inputs={style=comedy, story=In a realm wher...}, output=In a realm wher...}
|=> AgentInvocation{agent=scoreStyle, iteration=1, startTime=2026-03-18T17:27:38.183021641, finishTime=2026-03-18T17:27:38.683085876, duration=500 ms, tokens=439, inputs={style=comedy, story=In a realm wher...}, output=0.8}

最後に、HtmlReportGenerator クラスが公開する静的 generateReport メソッドを使用すると、エージェント型システムのトポロジーと記録された実行の両方について、AgentMonitor が収集したデータの視覚的な HTML レポートを生成することもできます。たとえば、先ほどの実行に対してこのレポートを生成すると、

HtmlReportGenerator.generateReport(monitor, Path.of("review-loop.html"));

現在の作業ディレクトリに、次のような review-loop.html レポートファイルが生成されます。

トポロジーと実行のセクションを個別に生成することもできます。実行データなしで、エージェント型システムのトポロジーのみを生成するには、次のようにします。

HtmlReportGenerator.generateTopology(styledWriter, Path.of("topology.html"));

逆に、トポロジーセクションなしでモニターが記録した実行履歴のみを生成するには、次のようにします。

HtmlReportGenerator.generateExecution(monitor, Path.of("execution.html"));

この最後のメソッドは、たとえば HtmlReportGenerator.generateExecution(monitor, memoryId, path) のようにメモリー ID によるフィルタリングもサポートします。また、すべてのメソッドには、ファイルへ書き込む代わりに HTML を String として返すオーバーロードがあります。

アクティベーション条件により、または任意でありながら引数が欠けているためにスキップされたエージェントは、AgentMonitor によって、所要時間のない完了済みの呼び出しとして記録されます。これは、本来実行されるはずだった親の下の位置に置かれ、ループ内では正しい反復インデックスを持ちます。その skipped() メソッドは true を返し、skipReason() はスキップされた理由を示します。HTML レポートでは、実行履歴に「skipped」バッジと理由が表示され、タイムラインのバーは表示されません。トポロジーでは、条件付きワークフローのブランチの「when:」ラベルに加えて、アクティベーション条件を持つ各エージェントに「if:」と条件の説明が付けられます。

エージェント型システムが中断されると、たとえばヒューマン・イン・ザ・ループのステップが SuspendedResponse を返すと、その実行は AgentMonitor で進行中として保持されます。ルートエージェントと中断したステップを含むワークフローの呼び出しは中断状態になり、それぞれの suspended() と MonitoredExecution.suspended() は true を返します。人の応答を待つステップは完了として記録され、並列ワークフローの別の分岐で動作中のエージェントも完了まで中断状態と表示されます。再開時はルートエージェントを再度呼ぶため、新規記録を作らず元の呼び出し記録を継続します。完了後の duration() には待機時間も含まれ、suspendedDuration() で待機時間を分離できます。人を待つループは反復ごとに中断されます。進行中の呼び出しで duration() と output() を呼ぶと IllegalStateException が発生しますが、suspendedDuration() はいつでも呼べます。HTML レポートは中断中の実行を “running” ではなく “suspended” と表示します。

待機しているセッションとその対象を確認できます。

MonitoredExecution execution = monitor.ongoingExecutionFor("order-12345");
if (execution != null && execution.suspended()) {
Set<String> waitingFor = execution.agenticScope().pendingResponseIds();
Duration waited = execution.topLevelInvocations().suspendedDuration();
}

再開後に続行されない呼び出し(条件が変わったルーター分岐など)は未完了のままになり、実行はルートエージェントとともに終了します。ルート呼び出しが返った後に非同期エージェントがシステムを中断した場合、元の実行は完了として記録され、再開時のルート呼び出しは新しい実行になります。中断後に作られたモニター(クラッシュ後の再起動など)も以前の記録がないため、再開を新しい実行として記録します。

デフォルトでは AgentMonitor は結果ごと(成功と失敗は別々)に、完了した最大 100 セッション(異なるメモリー ID)を保持します。超過すると古いセッションを削除するため、長寿命のシングルトンエージェントでも完了済みセッションによる無制限なメモリー増加を防げます。この上限は進行中の実行には適用されません。再開されない中断中の実行は、evictAgenticScope でスコープを削除するまで保持されます。その後、同じメモリー ID への呼び出しは新しい実行として始まります。

保持上限は setMaxRetainedSessions を介していつでも変更できます。新しい上限が現在保持しているセッション数より少ない場合、超過したエントリは即座に削除されます。

monitor.setMaxRetainedSessions(20);

0 に設定すると保持は完全に無効になります。リスナーのコールバックは引き続き発生しますが、メモリーには何も保持されません。保持済みの全セッションを明示的に削除するには、clear() メソッドを使用します。

monitor.clear();

どちらの操作も、進行中(in-flight)の実行には影響しません。

AgentMonitor を手動で作成してリスナーとして登録する代わりに、エージェントサービスインターフェースを MonitoredAgent から継承させることもできます。そうすると、ビルダーは AgentMonitor を自動作成してリスナーとして登録し、このモニターは agentMonitor() メソッドを介してエージェントインスタンスから直接アクセスできるようになります。

たとえば、前の例で定義したシーケンスエージェントは、MonitoredAgent インターフェースも継承する StyledWriter インターフェースを定義することで、型付きかつ監視対象のエージェントに変換できます。

public interface StyledWriter extends MonitoredAgent {
@Agent("Write a creative story about the given topic")
String generateStoryWithStyle(@V("topic") String topic, @V("style") String style);
}

このエージェントをビルドする際に、AgentMonitor を明示的に作成または登録する必要はありません。

StyledWriter styledWriter = AgenticServices.sequenceBuilder(StyledWriter.class)
.subAgents(creativeWriter, styleReviewLoop)
.outputKey("story")
.build();

モニターは自動的に登録され、いつでもエージェント自身から取得できます。

AgentMonitor monitor = styledWriter.agentMonitor();

宣言的 API​

ここまでで説明したすべてのワークフローパターンは、より簡潔で読みやすい方法でワークフローを定義できる宣言的 API を使用して定義できます。langchain4j-agentic モジュールは、より宣言的なスタイルでエージェントとそのワークフローを定義するために使用できるアノテーション一式を提供します。

たとえば、前のセクションでプログラムから定義した並列ワークフローを実装する EveningPlannerAgent は、宣言的 API を使用して次のように書き換えられます。

public interface EveningPlannerAgent {

@ParallelAgent( outputKey = "plans",
subAgents = { FoodExpert.class, MovieExpert.class })
List<EveningPlan> plan(@V("mood") String mood);

@ParallelExecutor
static Executor executor() {
return Executors.newFixedThreadPool(2);
}

@Output
static List<EveningPlan> createPlans(@V("movies") List<String> movies, @V("meals") List<String> meals) {
List<EveningPlan> moviesAndMeals = new ArrayList<>();
for (int i = 0; i < movies.size(); i++) {
if (i >= meals.size()) {
break;
}
moviesAndMeals.add(new EveningPlan(movies.get(i), meals.get(i)));
}
return moviesAndMeals;
}
}

この場合、@Output が付与された静的メソッドは、AgenticScope の関数を output メソッドへ渡して行ったのとまったく同じように、サブエージェントの出力を単一の結果へ結合する方法を定義するために使用されます。

このインターフェースを定義すると、AgenticServices.createAgenticSystem() メソッドを使用して EveningPlannerAgent のインスタンスを作成でき、その後は以前とまったく同じように使用できます。

EveningPlannerAgent eveningPlannerAgent = AgenticServices
.createAgenticSystem(EveningPlannerAgent.class, BASE_MODEL);
List<EveningPlan> plans = eveningPlannerAgent.plan("romantic");

@Output アノテーションについて示したのと同様に、エージェントパターンを定義するインターフェース内の他の static メソッドに以下のアノテーションのいずれかを付与することで、たとえば並列エージェントに使用する executor、ループエージェントの終了条件など、エージェント型システムを宣言的に設定できます。この目的で利用できるアノテーションの一覧を次に示します。

アノテーション名説明
@Outputこのエージェント型パターンが返す出力を、AgenticScope の異なる状態を組み合わせて組み立てます。
@ActivationCondition値なしの場合は、このエージェント型パターン自体のアクティベーション条件であり、ConditionalAgent では使用できません。値ありの場合は ConditionalAgent でのみ利用でき、1 つ以上のサブエージェントのアクティベーション述語を定義します。boolean を返す必要があります
@BeforeCallこのエージェント型パターンの呼び出し前に実行するアクションです。AgenticScope の状態を初期化するのに役立ちます。
@ErrorHandlerエージェントの動作中にエラーが発生した場合に呼び出すアクションで、カスタムのエラー処理ロジックを可能にします。
@ExitConditionLoopAgent でのみ利用でき、ループの終了述語を定義します。boolean を返す必要があります。
@ParallelExecutorParallelAgent および ParallelMapperAgent でのみ利用でき、サブエージェントの並列実行に使用する executor を指定します。
@AgentListenerSupplierこのエージェント型パターンに登録された AgentListener を返します。
@PlannerSupplierこのエージェント型パターンが使用する Planner 実装を返します。
@SupervisorRequestSupervisorAgent でのみ利用でき、スーパーバイザーに送信するリクエストを定義します。

前の例では、AgenticServices.createAgenticSystem() メソッドに、このエージェント型システム内のすべてのサブエージェントの作成にデフォルトで使用される ChatModel も指定しています。しかし、特定のサブエージェントに別の ChatModel を任意で指定することも可能です。その定義に、使用する ChatModel を返す @ChatModelSupplier が付与された静的メソッドを追加します。たとえば、FoodExpert エージェントは次のように独自の ChatModel を定義できます。

public interface FoodExpert {

@UserMessage("""
You are a great evening planner.
Propose a list of 3 meals matching the given mood.
The mood is {{mood}}.
For each meal, just give the name of the meal.
Provide a list with the 3 items and nothing else.
""")
@Agent(outputKey = "meals")
List<String> findMeal(@V("mood") String mood);

@ChatModelSupplier
static ChatModel chatModel() {
return FOOD_MODEL;
}
}

同様に、エージェントインターフェース内の他の static メソッドにアノテーションを付与することで、チャットメモリーや利用できるツールなど、エージェントの他の側面を宣言的に設定できます。前のアノテーション一覧はエージェント型パターンにのみ適用されますが、以下のアノテーションは、エージェント型パターンと最終エージェントの両方にリスナーを登録できる @AgentListenerSupplier を除き、LLM ベースの最終エージェントにのみ使用するのが適切です。また、スーパーバイザーパターンは内部的に LLM を使用する唯一のものなので、@ChatModelSupplier や @ChatMemoryProviderSupplier など、スーパーバイザー自身が使用する ChatModel を設定できるアノテーションを使用できます。以下の表で別途指定されていない限り、これらのメソッドは引数を持たない必要があります。この目的で利用できるアノテーションの一覧を次に示します。

アノテーション名説明
@ChatModelSupplierこのエージェントが使用する ChatModel を返します。メソッドが引数を持たない、または SupplierParameterResolver から提供される引数のみを持つ場合は固定モデル、あるいは AgenticScope の関数のいずれかにできます。
@StreamingChatModelSupplierこのエージェントが使用する StreamingChatModel を返します。メソッドが引数を持たない、または SupplierParameterResolver から提供される引数のみを持つ場合は固定モデル、あるいは AgenticScope の関数のいずれかにできます
@DecisionModelSupplier決定エージェントが使用する DecisionModel を返します。メソッドが引数を持たない、または SupplierParameterResolver から提供される引数のみを持つ場合は固定モデル、あるいは AgenticScope の関数のいずれかにできます。
@DecisionThresholdSupplier決定エージェントの boolean 回答のしきい値を double として返します。質問を記述する ThresholdContext を受け取り、呼び出しのたびに実行されます。
@ChatMemorySupplierこのエージェントが使用する ChatMemory を返します。
@ChatMemoryProviderSupplierこのエージェントが使用する ChatMemoryProvider を返します。
このメソッドには、作成するメモリーの memoryId として使用する Object が引数として必要です。
@ContentRetrieverSupplierこのエージェントが使用する ContentRetriever を返します。
@AgentListenerSupplierこのエージェントが使用する AgentListener を返します。
@RetrievalAugmentorSupplierこのエージェントが使用する RetrievalAugmentor を返します。
@ToolsSupplierこのエージェントが使用するツールまたはツールセットを返します。
単一の Object または Object[] を返せます。
@ToolProviderSupplierこのエージェントが使用する ToolProvider を返します。
@ToolSearchStrategySupplierこのエージェントがツールを見つけるために使用する ToolSearchStrategy を返します。
@SystemMessageProviderSupplier動的なシステムメッセージを提供します。メソッドは memoryId を Object として受け取り、String を返します。
@UserMessageProviderSupplier動的なユーザーメッセージを提供します。メソッドは memoryId を Object として受け取り、String を返します。

この宣言的 API の別の例として、条件付きワークフローのセクションで示した ExpertsAgent をこれを通じて再定義してみましょう。

public interface ExpertsAgent {

@ConditionalAgent(outputKey = "response",
subAgents = { MedicalExpert.class, TechnicalExpert.class, LegalExpert.class })
String askExpert(@V("request") String request);

@ActivationCondition(MedicalExpert.class)
static boolean activateMedical(@V("category") RequestCategory category) {
return category == RequestCategory.MEDICAL;
}

@ActivationCondition(TechnicalExpert.class)
static boolean activateTechnical(@V("category") RequestCategory category) {
return category == RequestCategory.TECHNICAL;
}

@ActivationCondition(LegalExpert.class)
static boolean activateLegal(@V("category") RequestCategory category) {
return category == RequestCategory.LEGAL;
}
}

この場合、@ActivationCondition アノテーションの値は、そのアノテーションが付いたメソッドが true を返したときにアクティブ化されるエージェントクラスの集合を指します。条件付きエージェントでは、すべての @ActivationCondition に値が必要です。値のないもの(他のエージェントではそのエージェント自身のアクティベーション条件になります)は、エージェント型システムの作成時に AgenticSystemConfigurationException で拒否されます。

エージェントおよびエージェント システムを定義するプログラム スタイルと宣言スタイルを混合して、部分的にアノテーションを使用してエージェントを構成し、部分的にエージェント ビルダーを使用してエージェントを構成することもできることに注意してください。また、エージェントを宣言的に完全に定義し、そのエージェントのクラスをサブエージェントとして使用してエージェント システムをプログラム的に実装することもできます。たとえば、次のように CreativeWriter エージェントと AudienceEditor エージェントを宣言的に定義することができます。

public interface CreativeWriter {

@UserMessage("""
You are a creative writer.
Generate a draft of a story long no more than 3 sentence around the given topic.
Return only the story and nothing else.
The topic is {{topic}}.
""")
@Agent(description = "Generate a story based on the given topic", outputKey = "story")
String generateStory(@V("topic") String topic);

@ChatModelSupplier
static ChatModel chatModel() {
return baseModel();
}
}

public interface AudienceEditor {

@UserMessage("""
You are a professional editor.
Analyze and rewrite the following story to better align with the target audience of {{audience}}.
Return only the story and nothing else.
The story is "{{story}}".
""")
@Agent(description = "Edit a story to better fit a given audience", outputKey = "story")
String editStory(@V("story") String story, @V("audience") String audience);

@ChatModelSupplier
static ChatModel chatModel() {
return baseModel();
}
}

次に、それらのクラスをサブエージェントとして使用するだけで、それらをプログラムでシーケンス内に連結します。

UntypedAgent novelCreator = AgenticServices.sequenceBuilder()
.subAgents(CreativeWriter.class, AudienceEditor.class)
.outputKey("story")
.build();

Map<String, Object> input = Map.of(
"topic", "dragons and wizards",
"audience", "young adults"
);

String story = (String) novelCreator.invoke(input);

ヘルパーオブジェクト​

@Output、@ExitCondition、@ActivationCondition、@ChatModelSupplier、および上記 2 つの表にあるその他のアノテーションが付いたメソッドは、エージェントのヘルパーメソッドです。エージェントインターフェースでは、これらは静的メソッドです。また、エージェントのヘルパーオブジェクトのインスタンスメソッドにすることもできます。ヘルパーオブジェクトは、インテグレーションが AgentConfigurator.builder() で構築した AgentConfigurator の helperObjectsResolver を通じて、エージェントの種類ごとに提供する通常のオブジェクトです。依存性注入コンテナ(Quarkus 拡張など)は、この方法でエージェントのヘルパーを、注入されたフィールドやインターセプターとともに Bean 上に保持します。この場合、エージェントクラス自体がそのヘルパーオブジェクトになります。たとえば、上記の EveningPlannerAgent は、リスナーを作成する静的メソッドの代わりに、リスナーを保持するヘルパーオブジェクトからリスナーを取得できます。

public class PlannerHelpers {

private final AgentListener listener; // in a container, an injected bean

public PlannerHelpers(AgentListener listener) {
this.listener = listener;
}

@AgentListenerSupplier
AgentListener listener() {
return listener;
}
}

AgentConfigurator configurator = AgentConfigurator.builder()
.helperObjectsResolver(agentType -> agentType == EveningPlannerAgent.class
? List.of(new PlannerHelpers(new AgentMonitor()))
: List.of())
.build();
EveningPlannerAgent eveningPlannerAgent = AgenticServices
.createAgenticSystem(EveningPlannerAgent.class, BASE_MODEL, configurator);

リゾルバーは、システムの構築時に各エージェントに対して 1 回呼び出され、返されたオブジェクトはそのエージェントのすべての呼び出しで共有されます。インスタンスヘルパーは、静的形式と同じパラメーターを取ります。AgenticScope から読み取られる値、@LoopCounter や ErrorContext のようにフレームワークが提供するパラメーター、SupplierParameterResolver を通じて解決されるパラメーターです。規則は次のとおりです。

  • 1 つのアノテーションに対して、エージェントが持つヘルパーは 1 つです。エージェント型の静的メソッドとヘルパーオブジェクトのインスタンスメソッドの併存、または同じアノテーションを持つ 2 つのヘルパーオブジェクトは設定エラーとなります。ただし、条件付きエージェントで値を持つ @ActivationCondition のように、エージェントで複数回使用できるアノテーションは例外です。
  • エージェント型自体が宣言する非静的ヘルパー(インターフェースの default メソッドなど)には、その宣言型のインスタンスであるヘルパーオブジェクトが必要です。そうでない場合、メソッドを無視する代わりに、エージェント型システムの作成が失敗します。
  • インスタンスヘルパーは private や final にできません。コンテナが Bean の前に置くプロキシがそれをオーバーライドできず、メソッドが注入されたフィールドのないプロキシ上で実行されてしまうためです。Kotlin クラスでデフォルトのように、final クラスの final メソッドは問題ありません。そのようなクラスをプロキシがサブクラス化することはできないためです。
  • ワークフロービルダーにインスタンスとして渡されるエージェント、非 AI エージェント、またはヒューマン・イン・ザ・ループオブジェクトは、それ自体がヘルパーオブジェクトです。その @ActivationCondition と @AgentListenerSupplier はインスタンスメソッドにでき、そのエージェントメソッドのパラメーターは SupplierParameterResolver を通じて解決できます。
  • 素の LangChain4j では、ヘルパーオブジェクトは主にインテグレーション向けの仕組みです。Quarkus 拡張では、インスタンスヘルパーが Bean 上で呼び出される Bean クラスとしてエージェントを定義できます。詳細はそのドキュメントを参照してください。

厳密に型指定された入力と出力​

この時点まで、エージェントとの間でデータの受け渡しに使用されるすべての入力キーと出力キーは、単純な String によって識別されていました。ただし、このアプローチはキーの正しいスペルに依存するため、間違いが発生しやすい可能性があります。また、この方法では、これらの変数を特定の型に強くバインドすることはできないため、AgenticScope から値を読み取るときに型チェックとキャストが必要になります。これらの問題を回避するために、TypedKey インターフェイスを使用して、厳密に型指定された入力キーと出力キーを定義することがオプションで許可されます。

たとえば、このアプローチに従って、条件付きワークフローを提示するときに説明したエキスパート ルーティングの例で使用される入力キーと出力キーを次のように定義できます。

public static class UserRequest implements TypedKey<String> { }

public static class ExpertResponse implements TypedKey<String> { }

public static class Category implements TypedKey<RequestCategory> {
@Override
public RequestCategory defaultValue() {
return RequestCategory.UNKNOWN;
}
}

ここで、UserRequest キーと ExpertResponse キーは両方とも String として厳密に型指定されていますが、Category キーは RequestCategory 列挙型として型指定されており、そのキーが AgenticScope に存在しない場合に使用されるデフォルト値も提供します。これらの入力されたキーを使用すると、ユーザーのリクエストを分類するために使用される CategoryRouter エージェントを次のように再定義できます。

public interface CategoryRouter {

@UserMessage("""
Analyze the following user request and categorize it as 'legal', 'medical' or 'technical'.
In case the request doesn't belong to any of those categories categorize it as 'unknown'.
Reply with only one of those words and nothing else.
The user request is: '{{UserRequest}}'.
""")
@Agent(description = "Categorizes a user request", typedOutputKey = Category.class)
RequestCategory classify(@K(UserRequest.class) String request);
}

classify メソッドの引数には @K 注釈が付けられ、その値が UserRequest 型付きキーで識別される AgenticScope 変数から取得される必要があることを示します。同様に、このエージェントの出力は、Category 型付きキーによって識別される AgenticScope 変数に書き込まれます。プロンプト テンプレートも、入力されたキーの名前を使用するように更新されていることに注意してください。これは、デフォルトでは、TypedKey インターフェイスを実装するクラスの単純名 (この場合は {{UserRequest}}) に対応しますが、この規則は、TypedKey インターフェイスの name() メソッドを実装することによってもオーバーライドできます。同様の方法で、3 つのエキスパート エージェントのうちの 1 つである MedicalExpert を次のように再定義できます。

public interface MedicalExpert {

@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 {{UserRequest}}.
""")
@Agent("A medical expert")
String medical(@K(UserRequest.class) String request);
}

この時点で、これらの入力されたキーを使用して、AgenticScope の入力変数と出力変数を識別するエージェント システム全体を作成できます。

CategoryRouter routerAgent = AgenticServices.agentBuilder(CategoryRouter.class)
.chatModel(baseModel())
.build();

MedicalExpert medicalExpert = AgenticServices.agentBuilder(MedicalExpert.class)
.chatModel(baseModel())
.outputKey(ExpertResponse.class)
.build();
LegalExpert legalExpert = AgenticServices.agentBuilder(LegalExpert.class)
.chatModel(baseModel())
.outputKey(ExpertResponse.class)
.build();
TechnicalExpert technicalExpert = AgenticServices.agentBuilder(TechnicalExpert.class)
.chatModel(baseModel())
.outputKey(ExpertResponse.class)
.build();

UntypedAgent expertsAgent = AgenticServices.conditionalBuilder()
.subAgents(scope -> scope.readState(Category.class) == RequestCategory.MEDICAL, medicalExpert)
.subAgents(scope -> scope.readState(Category.class) == RequestCategory.LEGAL, legalExpert)
.subAgents(scope -> scope.readState(Category.class) == RequestCategory.TECHNICAL, technicalExpert)
.build();

ExpertChatbot expertChatbot = AgenticServices.sequenceBuilder(ExpertChatbot.class)
.subAgents(routerAgent, expertsAgent)
.outputKey(ExpertResponse.class)
.build();

String response = expertChatbot.ask("I broke my leg what should I do");

routerAgent は、出力キーが @Agent アノテーションの typedOutputKey 属性を通じてインターフェイスですでに定義されているため、プログラムで指定する必要がありません。一方、3 つのエキスパート エージェントは、インターフェイスで定義されていないため、出力キーをプログラムで指定する必要があるため、通常どおり、2 つのアプローチのいずれかを使用できます。また、条件付きワークフロー定義の場合と同様に、AgenticScope から値を読み取る場合、型指定されたキーが必要な型情報をすでに提供しているため、型チェックやキャストを実行する必要がないことにも注意してください。

純粋なエージェント AI​

この時点まで、すべてのエージェントが接続され、結合されて、決定論的なワークフローを使用してエージェント システムが作成されてきました。ただし、エージェント システムがより柔軟で適応性があり、エージェントがコンテキストと以前の対話の結果に基づいて続行方法を決定できるようにする必要がある場合があります。これは、「純粋なエージェント AI」と呼ばれることがよくあります。

この目的のために、langchain4j-agentic モジュールは、すぐに使用できるスーパーバイザー エージェントを提供します。このスーパーバイザー エージェントは、一連のサブエージェントとともに提供され、次にどのエージェントを呼び出すか、または割り当てられたタスクが完了したかどうかを決定する計画を自律的に生成できます。

これがどのように機能するかの例を示すために、銀行口座にお金を入金したり引き出したり、ある通貨から特定の金額を別の通貨に交換したりできるいくつかのエージェントを定義してみましょう。

public interface WithdrawAgent {

@SystemMessage("""
You are a banker that can only withdraw US dollars (USD) from a user account,
""")
@UserMessage("""
Withdraw {{amount}} USD from {{user}}'s account and return the new balance.
""")
@Agent("A banker that withdraw USD from an account")
String withdraw(@V("user") String user, @V("amount") Double amount);
}

public interface CreditAgent {
@SystemMessage("""
You are a banker that can only credit US dollars (USD) to a user account,
""")
@UserMessage("""
Credit {{amount}} USD to {{user}}'s account and return the new balance.
""")
@Agent("A banker that credit USD to an account")
String credit(@V("user") String user, @V("amount") Double amount);
}

public interface ExchangeAgent {
@UserMessage("""
You are an operator exchanging money in different currencies.
Use the tool to exchange {{amount}} {{originalCurrency}} into {{targetCurrency}}
returning only the final amount provided by the tool as it is and nothing else.
""")
@Agent("A money exchanger that converts a given amount of money from the original to the target currency")
Double exchange(@V("originalCurrency") String originalCurrency, @V("amount") Double amount, @V("targetCurrency") String targetCurrency);
}

これらすべてのエージェントは外部ツールを使用してタスクを実行します。具体的には、ユーザーのアカウントからお金を引き出したり入金したりするために使用できる BankTool です。

public class BankTool {

private final Map<String, Double> accounts = new HashMap<>();

void createAccount(String user, Double initialBalance) {
if (accounts.containsKey(user)) {
throw new RuntimeException("Account for user " + user + " already exists");
}
accounts.put(user, initialBalance);
}

double getBalance(String user) {
Double balance = accounts.get(user);
if (balance == null) {
throw new RuntimeException("No balance found for user " + user);
}
return balance;
}

@Tool("Credit the given user with the given amount and return the new balance")
Double credit(@P("user name") String user, @P("amount") Double amount) {
Double balance = accounts.get(user);
if (balance == null) {
throw new RuntimeException("No balance found for user " + user);
}
Double newBalance = balance + amount;
accounts.put(user, newBalance);
return newBalance;
}

@Tool("Withdraw the given amount with the given user and return the new balance")
Double withdraw(@P("user name") String user, @P("amount") Double amount) {
Double balance = accounts.get(user);
if (balance == null) {
throw new RuntimeException("No balance found for user " + user);
}
Double newBalance = balance - amount;
accounts.put(user, newBalance);
return newBalance;
}
}

ExchangeTool は、最新の為替レートを提供する REST サービスを使用して、ある通貨から別の通貨に両替するために使用できます。

public class ExchangeTool {

@Tool("Exchange the given amount of money from the original to the target currency")
Double exchange(@P("originalCurrency") String originalCurrency, @P("amount") Double amount, @P("targetCurrency") String targetCurrency) {
// Invoke a REST service to get the exchange rate
}
}

AgenticServices.agentBuilder() メソッドを使用して通常どおりこれらのエージェントのインスタンスを作成し、これらのツールを使用するように構成して、スーパーバイザー エージェントのサブエージェントとして使用できるようになりました。

BankTool bankTool = new BankTool();
bankTool.createAccount("Mario", 1000.0);
bankTool.createAccount("Georgios", 1000.0);

WithdrawAgent withdrawAgent = AgenticServices
.agentBuilder(WithdrawAgent.class)
.chatModel(BASE_MODEL)
.tools(bankTool)
.build();
CreditAgent creditAgent = AgenticServices
.agentBuilder(CreditAgent.class)
.chatModel(BASE_MODEL)
.tools(bankTool)
.build();

ExchangeAgent exchangeAgent = AgenticServices
.agentBuilder(ExchangeAgent.class)
.chatModel(BASE_MODEL)
.tools(new ExchangeTool())
.build();

SupervisorAgent bankSupervisor = AgenticServices
.supervisorBuilder()
.chatModel(PLANNER_MODEL)
.subAgents(withdrawAgent, creditAgent, exchangeAgent)
.responseStrategy(SupervisorResponseStrategy.SUMMARY)
.build();

サブエージェントは、ワークフローを実装する複雑なエージェントである場合もあり、スーパーバイザーからは単一のエージェントとして認識されることに注意してください。

スーパーバイザーはサブエージェントの説明を使って呼び出し先を決めるため、各サブエージェントに説明を付けてください。説明がなくても処理は続きますが、モデルには説明がないことが伝えられ、ID と引数から用途を推測するよう求められます。初回呼び出し時には警告も記録されます。リモート A2A エージェントの説明を明示しない場合は、初回呼び出し時にエージェントカードから取得します(カードの解決を参照)。A2A または MCP エージェントのサーバーが停止して説明を読めず、AgentUnavailableException が報告された場合、その呼び出しではモデルに提示する候補から除外し、次回再試行します。一方、MCP サーバーに指定したツールが存在しないなどの設定エラーは、見落とさないようスーパーバイザーの呼び出しを失敗させます。

結果として得られる SupervisorAgent は通常、ユーザー要求を入力として受け取り、応答を生成するため、その署名は次のようになります。

public interface SupervisorAgent {
@Agent
String invoke(@V("request") String request);
}

ここで、次のリクエストを使用してこのエージェントを起動するとします。

bankSupervisor.invoke("Transfer 100 EUR from Mario's account to Georgios' one")

内部的には、スーパーバイザ エージェントがリクエストを分析し、一連の AgentInvocation によって作成されたタスクを達成するための計画を生成します。

public record AgentInvocation(String agentName, Map<String, String> arguments) {}

たとえば、前者のリクエストの場合、スーパーバイザは次のような一連の呼び出しを生成できます。

AgentInvocation{agentName='exchange', arguments={originalCurrency=EUR, amount=100, targetCurrency=USD}}

AgentInvocation{agentName='withdraw', arguments={user=Mario, amount=115.0}}

AgentInvocation{agentName='credit', arguments={user=Georgios, amount=115.0}}

AgentInvocation{agentName='done', arguments={response=The transfer of 100 EUR from Mario's account to Georgios' account has been completed. Mario's balance is 885.0 USD, and Georgios' balance is 1.23.0 USD. The conversion rate was 1.15 EUR to USD.}}

最後の呼び出しは、タスクが完了したとスーパーバイザーに知らせる特別な呼び出しで、実行されたすべての操作の概要を応答として返します。

今回のように、多くの場合、この概要がユーザーに返される最終応答になりますが、常にそうとは限りません。最初の例のように、単純なシーケンス ワークフローの代わりに SupervisorAgent を使用してストーリーを作成し、指定されたスタイルと対象者に従って編集するとします。この場合、ユーザーは最終的なストーリーのみに興味があり、それを作成するために実行された中間ステップの概要には興味がありません。

概要ではなく、最後に呼び出されたエージェントによって生成された応答を返すのが実際には最も一般的なシナリオであるため、これはスーパーバイザ エージェントのデフォルトの動作でもあります。ただし、この状況では、実行されたすべてのトランザクションの概要を返す方が適切であるため、SupervisorAgent は responseStrategy メソッドを通じてそれに応じて構成されています。

次のセクションでは、スーパーバイザ エージェントのこのカスタマイズとその他の可能なカスタマイズについて説明します。

スーパーバイザーの設計とカスタマイズ​

より一般的には、スーパーバイザーによって生成された要約と、最後に呼び出されたエージェントの最後の応答という 2 つの応答のうち、どちらが返されるのに最も適切であるかを事前に知ることができない場合があります。このような状況では、元のユーザー要求とともにこれら 2 つの可能な応答が渡され、どちらが要求によりよく適合するかを決定し、どちらを返すかを決定するためにそれらの応答をスコアリングする 2 番目のエージェントが利用できるようになりました。

SupervisorResponseStrategy 列挙型を使用すると、このスコアラー エージェントを有効にしたり、スコアリング プロセスをスキップして 2 つの応答のうちの 1 つを常に返すことができます。

public enum SupervisorResponseStrategy {
SCORED, SUMMARY, LAST
}

予想どおり、デフォルトの動作は LAST であり、他の戦略実装は responseStrategy メソッドを使用してスーパーバイザ エージェント上で構成できます。

AgenticServices.supervisorBuilder()
.responseStrategy(SupervisorResponseStrategy.SCORED)
.build();

たとえば、銀行業務の例で SCORED 戦略を使用すると、次の応答スコアが生成される可能性があります。

ResponseScore{finalResponse=0.3, summary=1.0}

したがって、スーパーバイザ エージェントは、ユーザー要求に対する最終応答として概要を返すようになります。

これまで説明してきたスーパーバイザ エージェントのアーキテクチャを次の図に示します。

スーパーバイザーが次に取るべきアクションを決定するために使用する情報も、スーパーバイザーの重要な側面の 1 つです。デフォルトでは、スーパーバイザは単にローカル チャット メモリを使用しますが、場合によっては、コンテキスト エンジニアリングのセクションで説明したのと非常によく似た方法で、サブエージェントの会話を要約することによって生成された、より包括的なコンテキストをスーパーバイザに提供したり、両方のアプローチを同時に組み合わせたりすると便利な場合があります。 3 つの可能性は次の列挙型で表されます。

public enum SupervisorContextStrategy {
CHAT_MEMORY, SUMMARIZATION, CHAT_MEMORY_AND_SUMMARIZATION
}

これは、contextGenerationStrategy メソッドを使用してスーパーバイザ エージェントを構築するときに設定できます。

AgenticServices.supervisorBuilder()
.contextGenerationStrategy(SupervisorContextStrategy.SUMMARIZATION)
.build();

スーパーバイザーのプランナーに提示されるエージェントは、次のエージェントを選択するよう求められた時点でアクティベーション条件が成立しているものだけです。それでもスーパーバイザーが、アクティベーション条件がもはや成立していない、または任意でありながら引数が欠けているためにスキップされるエージェントを呼び出した場合、スーパーバイザーのプランナーは、古い出力ではなく、そのエージェントがスキップされたことと理由を伝えるメッセージを最後のレスポンスとして受け取り、次に何をするかを判断できます。

スーパーバイザ エージェントのその他のカスタマイズ ポイントは、最終的には実装され、将来的に利用可能になる可能性があります。

スーパーバイザーにコンテキストを提供する​

現実の多くのシナリオでは、監督者はオプションのコンテキスト、つまり計画の指針となる制約、ポリシー、または設定 (たとえば、「内部ツールを優先する」、「外部サービスを呼び出さない」、「通貨は米ドルでなければならない」など) から恩恵を受けます。

このコンテキストは、AgenticScope、supervisorContext という名前の変数に保存されます。次の 2 つの方法で提供できます。

  • ビルド時の構成:
SupervisorAgent bankSupervisor = AgenticServices
.supervisorBuilder()
.chatModel(PLANNER_MODEL)
.supervisorContext("Policies: prefer internal tools; currency USD; no external APIs")
.subAgents(withdrawAgent, creditAgent, exchangeAgent)
.responseStrategy(SupervisorResponseStrategy.SUMMARY)
.build();
  • 呼び出し (型指定されたスーパーバイザー): @V("supervisorContext") の注釈が付けられたパラメーターを追加します。
public interface SupervisorAgent {
@Agent
String invoke(@V("request") String request, @V("supervisorContext") String supervisorContext);
}

// Example call (overrides the build-time value for this invocation)
bankSupervisor.invoke(
"Transfer 100 EUR from Mario's account to Georgios' one",
"Policies: convert to USD first; use bank tools only; no external APIs"
);
  • 呼び出し (型なしスーパーバイザー): 入力マップに supervisorContext を設定します。
Map<String, Object> input = Map.of(
"request", "Transfer 100 EUR from Mario's account to Georgios' one",
"supervisorContext", "Policies: convert to USD first; use bank tools only; no external APIs"
);

String result = (String) bankSupervisor.invoke(input);

両方が指定された場合、呼び出し値はビルド時の supervisorContext をオーバーライドします。

カスタムエージェントパターン​

これまでに説明したエージェント パターンは、langchain4j-agentic モジュールによってすぐに使用できるように提供されていますが、それらのどれもアプリケーションの特定のニーズに適合しない場合はどうすればよいでしょうか?この場合、要件に合わせた方法で一連のサブエージェント間の対話を調整する独自のカスタム パターンを作成することができます。

さらに詳しく説明すると、エージェント パターンは、それが調整するサブエージェントの実行計画の仕様にすぎません。このプランは、次の Planner インターフェイスを実装することで定義できます。

public interface Planner {

default void init(InitPlanningContext initPlanningContext) { }

default Action firstAction(PlanningContext planningContext) {
return nextAction(planningContext);
}

Action nextAction(PlanningContext planningContext);
}

このインターフェイスには、init、firstAction、nextAction の 3 つのメソッドがあります。 init メソッドは実行の開始時に 1 回呼び出され、プランナーが必要とするあらゆる状態またはデータ構造を初期化するために使用できます。 firstAction メソッドは、エージェント パターンによって実行される最初のアクションを決定するために呼び出されます。一方、nextAction メソッドは、各エージェントの実行後に呼び出され、AgenticScope の現在の状態と前回のエージェント実行の結果に基づいて実行される次のアクションを決定します。

firstAction メソッドが導入されたのは、多くの場合、Planner によって呼び出される最初のエージェントを定義する個別のコールバックがあると便利であるという理由だけであることに注意してください。ただし、この区別が必要ない状況では、呼び出しを nextAction メソッドに転送するだけのデフォルト実装が提供されるため、厳密にはオーバーライドする必要はありません。

firstAction メソッドと nextAction メソッドによって返される Action クラスは、エージェント パターンによって実行される次のステップを表し、次に呼び出される 1 つ以上のサブエージェントのリスト、または実行が完了したことを示す信号のいずれかになります。アクションでサブエージェント呼び出しが 1 つだけ指定されている場合は、プランナー自体を実行しているのと同じスレッドで順次実行されます。一方、複数ある場合は、提供された Executor または LangChain4j のデフォルトのものを使用して並行して実行されます。

すべての組み込みエージェント パターンも、この Planner 抽象化に関して記述されており、その実装を確認することで、これがどのように機能するかを明確にすることができ、独自のカスタム パターンを作成する良い出発点となります。たとえば、並列ワークフローはおそらくこれらの実装の中で最も単純であり、次のように定義されます。

public class ParallelPlanner implements Planner {

private List<AgentInstance> agents;

@Override
public void init(InitPlanningContext initPlanningContext) {
this.agents = initPlanningContext.subagents();
}

@Override
public Action firstAction(PlanningContext planningContext) {
return call(agents);
}

@Override
public Action nextAction(PlanningContext planningContext) {
return done();
}
}

ここで、init メソッドは、並列ワークフローが構成されているサブエージェントのリストを保存するだけですが、firstAction メソッドは、これらすべてのエージェントを並列に呼び出すアクションを返します。この並列実行が完了すると、他に実行するアクションはないため、nextAction メソッドは実行の終了を通知するために使用される done() を返すだけです。

順次ワークフローを実装する Planner は、内部カーソルを使用して呼び出される次のサブエージェントを追跡し、その後 nextAction メソッドで適切なアクションを返すか、すべてのサブエージェントが呼び出されたら実行の終了を通知する必要があるため、少しだけ複雑になります。

public class SequentialPlanner implements Planner {

private List<AgentInstance> agents;
private int agentCursor = 0;

@Override
public void init(InitPlanningContext initPlanningContext) {
this.agents = initPlanningContext.subagents();
}

@Override
public Action nextAction(PlanningContext planningContext) {
return agentCursor >= agents.size() ? done() : call(agents.get(agentCursor++));
}
}

プランナーの実装からエージェント システムを定義する方法を理解するには、たとえば、次のように、トピックの小説を生成し、特定のスタイルと読者向けに編集する、前述の順次ワークフローのインスタンスを作成することができます。

UntypedAgent novelCreator = AgenticServices.plannerBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.planner(SequentialPlanner::new)
.build();

これは、シーケンシャル ワークフローに専用 API を使用するのとまったく同じです。

UntypedAgent novelCreator = AgenticServices.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.build();

plannerBuilder() メソッドは他のすべてのエージェント ビルダーと似ていますが、唯一の違いは、このエージェント システムで使用される特定のプランナーの新しいインスタンスを返す Supplier<Planner> を提供する必要があることです。もちろん、カスタム プランナーを実装するエージェント システムは、langchain4j-agentic モジュールによってすぐに提供される他のエージェント パターンとシームレスに組み合わせることができます。

プランナーは、サブエージェントのアクティベーション条件を気にする必要はありません。条件はエージェントの呼び出し時に適用されるためです。非アクティブなエージェントはスキップされ、その後プランナーが previousAgentInvocation() として受け取る AgentInvocation は、true を返す skipped() メソッドと、理由を示す skipReason() を持ちます。その出力はエージェントの出力キーの現在の値であるため、たとえば投票を数えるなど、サブエージェントの出力を解釈するプランナーは、スキップされたものを除外する必要があります。AgenticScope の状態から候補を選択するプランナーは、PlanningContext の isActive(agent) を呼び出して非アクティブなエージェントの選択を避けることもできます。スーパーバイザーや、以下で説明するピアツーピア、ブラックボード、ゴール指向、決定ルーター、信頼度カスケードの各パターンはそうしています。このチェックは、一時停止やクラッシュの前にすでにアクティブ化されていた複合エージェントを扱います。これらは、条件がもはや成立していなくても再開されなければなりません。ただしこれは参考情報にすぎません。条件はエージェントの呼び出し時に再度評価され、その間に状態が変わっている可能性があるため、プランナーはいずれにしてもスキップされた呼び出しを処理しなければなりません。

この Planner 抽象化の仕組みを理解したところで、これを実装して独自のエージェント型パターンを作成できます。以降のセクションでは、langchain4j-agentic-patterns モジュールで提供されるカスタムパターンを取り上げます。これらはさまざまなシナリオで役立ちます。同じ方法で他のカスタムパターンを作成することもでき、LangChain4j プロジェクトに還元することもできます。

目標指向のエージェントパターン​

ワークフロー パターンとスーパーバイザー エージェントは、考えられるエージェント システムの範囲の 2 つの極端な例を表します。前者は完全に決定的で厳格であり、呼び出されるエージェントの順序を事前に決定する必要があります。一方、後者は完全に柔軟で適応性がありますが、呼び出されるエージェントの順序の決定は非決定的 LLM に委任されます。ただし、これら 2 つの極端な中間点の方が適切な場合があり、エージェントが比較的柔軟な方法で特定の目標に向かって作業できるようになりますが、これらのエージェントをどのように呼び出すかをアルゴリズム的に決定することもできます。

このアプローチを実践するには、エージェント システム全体で目標を定義する必要があるだけでなく、各サブエージェントが独自の事前条件と事後条件を宣言する必要もあります。これは、可能な限り最速の方法で目標を達成するためのエージェント呼び出しのシーケンスを計算するために必要です。ただし、これらの事前条件と事後条件は各エージェントの必要な入力と生成された出力に他ならず、最終目標は単にエージェント システム全体の望ましい出力であるため、これらの情報はすべて暗黙的にエージェント システムにすでに存在しています。

このアイデアに従って、エージェント システムに参加しているすべてのサブエージェントの依存関係グラフを計算し、AgenticScope の初期状態を分析して目的の目標と比較できる Planner を実装し、そのグラフを使用してその目標の達成につながるエージェント呼び出しのシーケンスを決定することができます。

public class GoalOrientedPlanner implements Planner {

private String goal;

private GoalOrientedSearchGraph graph;
private List<AgentInstance> path;

private int agentCursor = 0;

@Override
public void init(InitPlanningContext initPlanningContext) {
this.goal = initPlanningContext.plannerAgent().outputKey();
this.graph = new GoalOrientedSearchGraph(initPlanningContext.subagents());
}

@Override
public Action firstAction(PlanningContext planningContext) {
path = graph.search(planningContext.agenticScope().state().keySet(), goal);
if (path.isEmpty()) {
throw new IllegalStateException("No path found for goal: " + goal);
}
return call(path.get(agentCursor++));
}

@Override
public Action nextAction(PlanningContext planningContext) {
return agentCursor >= path.size() ? done() : call(path.get(agentCursor++));
}
}

予想どおり、ここでは目標はプランナー ベースのエージェント パターン自体の最終出力と一致しますが、初期状態から目標までのパスは、すべてのサブエージェントの入力キーと出力キーを分析して構築された GoalOrientedSearchGraph を使用して計算されます。次に、呼び出されるエージェントのシーケンスが、現在の状態から目的の目標までのグラフ上の最短パスとして計算されます。

これがどのように機能するかの実際的な例を示すために、プロンプトから人の名前と星座を抽出し、その星座の星占いを生成し、インターネット上で関連するストーリーを探し、最終的にこれらすべての情報を組み合わせた優れた記事を作成できる、目標指向のエージェント システムを構築してみましょう。この一連のタスクは、次の 5 つのエージェントを使用して達成できます。

public interface HoroscopeGenerator {
@SystemMessage("You are an astrologist that generates horoscopes based on the user's name and zodiac sign.")
@UserMessage("Generate the horoscope for {{person}} who is a {{sign}}.")
@Agent("An astrologist that generates horoscopes based on the user's name and zodiac sign.")
String horoscope(@V("person") Person person, @V("sign") Sign sign);
}

public interface PersonExtractor {

@UserMessage("Extract a person from the following prompt: {{prompt}}")
@Agent("Extract a person from user's prompt")
Person extractPerson(@V("prompt") String prompt);
}

public interface SignExtractor {

@UserMessage("Extract the zodiac sign of a person from the following prompt: {{prompt}}")
@Agent("Extract a person from user's prompt")
Sign extractSign(@V("prompt") String prompt);
}

public interface Writer {
@UserMessage("""
Create an amusing writeup for {{person}} based on the following:
- their horoscope: {{horoscope}}
- a current news story: {{story}}
""")
@Agent("Create an amusing writeup for the target person based on their horoscope and current news stories")
String write(@V("person") Person person, @V("horoscope") String horoscope, @V("story") String story);
}

public interface StoryFinder {

@SystemMessage("""
You're a story finder, use the provided web search tools, calling it once and only once,
to find a fictional and funny story on the internet about the user provided topic.
""")
@UserMessage("""
Find a story on the internet for {{person}} who has the following horoscope: {{horoscope}}.
""")
@Agent("Find a story on the internet for a given person with a given horoscope")
String findStory(@V("person") Person person, @V("horoscope") String horoscope);
}

以前に開発した GoalOrientedPlanner を利用して、これらのエージェントを次のように目的指向のエージェント システムに組み合わせることができます。

HoroscopeGenerator horoscopeGenerator = AgenticServices.agentBuilder(HoroscopeGenerator.class)
.chatModel(baseModel())
.outputKey("horoscope")
.build();

PersonExtractor personExtractor = AgenticServices.agentBuilder(PersonExtractor.class)
.chatModel(baseModel())
.outputKey("person")
.build();

SignExtractor signExtractor = AgenticServices.agentBuilder(SignExtractor.class)
.chatModel(baseModel())
.outputKey("sign")
.build();

Writer writer = AgenticServices.agentBuilder(Writer.class)
.chatModel(baseModel())
.outputKey("writeup")
.build();

StoryFinder storyFinder = AgenticServices.agentBuilder(StoryFinder.class)
.chatModel(baseModel())
.tools(new WebSearchTool())
.outputKey("story")
.build();

UntypedAgent horoscopeAgent = AgenticServices.plannerBuilder()
.subAgents(horoscopeGenerator, personExtractor, signExtractor, writer, storyFinder)
.outputKey("writeup")
.planner(GoalOrientedPlanner::new)
.build();

予想どおり、このエージェント システムの全体的な目標は、GOAP ベースのプランナー自体の出力キーでもある writeup を生成することです。すべてのサブエージェントの入力と出力を考慮すると、GoalOrientedSearchGraph によって構築される依存関係グラフは次のようになります。

「私の名前はマリオ、星座はうお座です」のようなプロンプトでこのエージェント システムを呼び出すとき

Map<String, Object> input = Map.of("prompt", "My name is Mario and my zodiac sign is pisces");
String writeup = horoscopeAgent.invoke(input);

GoalOrientedPlanner は、prompt 変数のみを含む AgenticScope の初期状態を分析し、その初期状態から目的の目標 (writeup) までの依存関係グラフ上の最短パスを計算します。その結果、エージェント呼び出しのシーケンスは次のようになります。

Agents path sequence: [extractPerson, extractSign, horoscope, findStory, write]

パスの計算時にアクティベーション条件が false のエージェントは依存グラフから除外されるため、パスはそれらを迂回します。一方、非アクティブなエージェントを経由しなければ到達できないゴールは、到達不能として失敗します。

予想どおり、この目標指向のエージェント パターンは、他の既存のエージェント パターンと混合したり組み合わせることができることに注意してください。たとえば、この可能性は、可能な限り最短のパスをたどって特定の目標に到達するように最適化されているため、構造的にループが許可されていないという、このアプローチの明らかな制限を克服するために使用できます。そのため、場合によっては、この目標指向のパターンのサブエージェントとしてループ エージェント パターンを持つことが役立つ可能性があります。

ピアツーピアエージェントパターン​

これまで説明したすべてのエージェント システムは、集中型の階層アーキテクチャに基づいています。実際、すべてのワークフロー パターンには、プログラムで事前に決定された方法で複数のサブエージェントのアクティビティを調整する、明確に定義されたトップレベル エージェントがありました。 LLM ベースのプランナー エージェントの存在により、より柔軟かつ動的になっているスーパーバイザー パターンでも、依然としてさまざまなサブエージェント間の対話を制御するコーディネーター エージェントに依存しています。このアーキテクチャの類型は多くのアプリケーションやシナリオに適していますが、特にスケーラビリティとフォールト トレランスの点でいくつかの制限がある場合もあります。これが、より分散化された分散戦略を採用することでこれらの制限を克服できる、マルチエージェント システム用の代替ピアツーピア アプローチを提供したい理由です。

ピアツーピア エージェント システムでは、トップレベルのエージェントは存在せず、すべてのエージェントは AgenticScope の状態を通じて調整される同等のピアです。特に、エージェントは、AgenticScope 内の状態変数として独自の必要な入力が存在することによってトリガーされます。その後、別のエージェントの出力によって生成されたこれらの変数の 1 つ以上が変更されると、そのエージェントの呼び出しが再度トリガーされる可能性があります。 AgenticScope が安定状態に達してエージェントを呼び出すことができなくなった場合、事前定義された終了条件が満たされた場合、またはエージェント呼び出しの最大数に達した場合、プロセスは終了します。このピアツーピア エージェント パターンを実現する Planner 実装は、次のように記述できます。

public class P2PPlanner implements Planner {

private final int maxAgentsInvocations;
private final BiPredicate<AgenticScope, Integer> exitCondition;

private int invocationCounter = 0;
private Map<String, AgentActivator> agentActivators;

public P2PPlanner(int maxAgentsInvocations, BiPredicate<AgenticScope, Integer> exitCondition) {
this(null, maxAgentsInvocations, exitCondition);
}

@Override
public void init(InitPlanningContext initPlanningContext) {
this.agentActivators = initPlanningContext.subagents().stream().collect(toMap(AgentInstance::agentId, AgentActivator::new));
}

@Override
public Action nextAction(PlanningContext planningContext) {
if (terminated(planningContext.agenticScope())) {
return done();
}

AgentActivator lastExecutedAgent = agentActivators.get(planningContext.previousAgentInvocation().agentId());
lastExecutedAgent.finishExecution();
agentActivators.values().forEach(a -> a.onStateChanged(lastExecutedAgent.agent.outputKey()));

return nextCallAction(planningContext.agenticScope());
}

private Action nextCallAction(AgenticScope agenticScope) {
AgentInstance[] agentsToCall = agentActivators.values().stream()
.filter(agentActivator -> agentActivator.canActivate(agenticScope))
.peek(AgentActivator::startExecution)
.map(AgentActivator::agent)
.toArray(AgentInstance[]::new);

if (agentsToCall.length == 0 && agentActivators.values().stream().noneMatch(AgentActivator::isExecuting)) {
// no agent can be activated and none is still running: the agentic scope reached a stable state
return done();
}

invocationCounter += agentsToCall.length;
return call(agentsToCall);
}

private boolean terminated(AgenticScope agenticScope) {
return invocationCounter > maxAgentsInvocations || exitCondition.test(agenticScope, invocationCounter);
}
}

ここで P2PPlanner は、これまでに実行されたエージェント呼び出しの回数を追跡し、サブエージェントごとに AgentActivator を使用して、AgenticScope の現在の状態に基づいて呼び出せるかどうかを判断します。nextAction メソッドは、終了条件が満たされたか、または最大呼び出し回数に達したかを確認し、そうでなければ、現在の状態に基づいてアクティブ化できるすべてのエージェントを特定して開始済みとしてマークし、それらを呼び出すアクションを返します。アクティブ化できるエージェントがなく、実行中のエージェントもない場合、エージェント型スコープは安定状態に達しており、プランナーは done アクションを返してループを終了します。アクティベーション条件が false のエージェントは、すべての入力が利用可能な場合でも決してアクティブ化されません。また、その間に条件が変わったために呼び出し時にスキップされたエージェントは、他のエージェントをアクティブ化し得る出力の変更とはみなされません。

これがどのように機能するかの実際的な例を示すために、科学的調査を実行し、特定のトピックについて新しい仮説を立てることができるピアツーピア エージェント システムを構築してみましょう。このサービスの API は次のようになります。

public interface ResearchAgent {

@Agent("Conduct research on a given topic")
String research(@V("topic") String topic);
}

この目的のために、次の 5 つのエージェントを定義できます。

public interface LiteratureAgent {

@SystemMessage("Search for scientific literature on the given topic and return a summary of the findings.")
@UserMessage("""
You are a scientific literature search agent.
Your task is to find relevant scientific papers on the topic provided by the user and summarize them.
Use the provided tool to search for scientific papers and return a summary of your findings.
The topic is: {{topic}}
""")
@Agent("Search for scientific literature on a given topic")
String searchLiterature(@V("topic") String topic);
}

public interface HypothesisAgent {

@SystemMessage("Based on the research findings, formulate a clear and concise hypothesis related to the given topic.")
@UserMessage("""
You are a hypothesis formulation agent.
Your task is to formulate a clear and concise hypothesis based on the research findings provided by the user.
The topic is: {{topic}}
The research findings are: {{researchFindings}}
""")
@Agent("Formulate hypothesis around a give topic based on research findings")
String makeHypothesis(@V("topic") String topic, @V("researchFindings") String researchFindings);
}

public interface CriticAgent {

@SystemMessage("Critically evaluate the given hypothesis related to the specified topic. Provide constructive feedback and suggest improvements if necessary.")
@UserMessage("""
You are a critical evaluation agent.
Your task is to critically evaluate the hypothesis provided by the user in relation to the specified topic.
Provide constructive feedback and suggest improvements if necessary.
If you need to, you can also perform additional research to validate or confute the hypothesis using the provided tool.
The topic is: {{topic}}
The hypothesis is: {{hypothesis}}
""")
@Agent("Critically evaluate a hypothesis related to a given topic")
String criticHypothesis(@V("topic") String topic, @V("hypothesis") String hypothesis);
}

public interface ValidationAgent {

@SystemMessage("Validate the provided hypothesis on the given topic based on the critique provided.")
@UserMessage("""
You are a validation agent.
Your task is to validate the hypothesis provided by the user in relation to the specified topic based on the critique provided.
Validate the provided hypothesis, either confirming it or reformulating a different hypothesis based on the critique.
The topic is: {{topic}}
The hypothesis is: {{hypothesis}}
The critique is: {{critique}}
""")
@Agent("Validate a hypothesis based on a given topic and critique")
String validateHypothesis(@V("topic") String topic, @V("hypothesis") String hypothesis, @V("critique") String critique);
}

public interface ScorerAgent {

@SystemMessage("Score the provided hypothesis on the given topic based on the critique provided.")
@UserMessage("""
You are a scoring agent.
Your task is to score the hypothesis provided by the user in relation to the specified topic based on the critique provided.
Score the provided hypothesis on a scale from 0.0 to 1.0, where 0.0 means the hypothesis is completely invalid and 1.0 means the hypothesis is fully valid.
The topic is: {{topic}}
The hypothesis is: {{hypothesis}}
The critique is: {{critique}}
""")
@Agent("Score a hypothesis based on a given topic and critique")
double scoreHypothesis(@V("topic") String topic, @V("hypothesis") String hypothesis, @V("critique") String critique);
}

これらのエージェントにはすべて、arXiv から学術論文をダウンロードするなど、科学文献の調査を実行できるツールが提供され、P2P エージェント システムに追加されます。

ArxivCrawler arxivCrawler = new ArxivCrawler();

LiteratureAgent literatureAgent = AgenticServices.agentBuilder(LiteratureAgent.class)
.chatModel(baseModel())
.tools(arxivCrawler)
.outputKey("researchFindings")
.build();
HypothesisAgent hypothesisAgent = AgenticServices.agentBuilder(HypothesisAgent.class)
.chatModel(baseModel())
.tools(arxivCrawler)
.outputKey("hypothesis")
.build();
CriticAgent criticAgent = AgenticServices.agentBuilder(CriticAgent.class)
.chatModel(baseModel())
.tools(arxivCrawler)
.outputKey("critique")
.build();
ValidationAgent validationAgent = AgenticServices.agentBuilder(ValidationAgent.class)
.chatModel(baseModel())
.tools(arxivCrawler)
.outputKey("hypothesis")
.build();
ScorerAgent scorerAgent = AgenticServices.agentBuilder(ScorerAgent.class)
.chatModel(baseModel())
.tools(arxivCrawler)
.outputKey("score")
.build();

ResearchAgent researcher = AgenticServices.plannerBuilder(ResearchAgent.class)
.subAgents(literatureAgent, hypothesisAgent, criticAgent, validationAgent, scorerAgent)
.outputKey("hypothesis")
.planner(() -> new P2PPlanner(10, agenticScope -> {
if (!agenticScope.hasState("score")) {
return false;
}
double score = agenticScope.readState("score", 0.0);
System.out.println("Current hypothesis score: " + score);
return score >= 0.85;
}))
.build();

String hypothesis = researcher.research("black holes");

この構成では、researcher p2p コーディネーターに研究のトピックが渡されます。この時点で、呼び出すことができる唯一のエージェントは literatureAgent です。これは、必要な入力をすべて備えている唯一のエージェントであるためです。この場合、AgenticScope に存在する topic です。このエージェントの呼び出しにより researchFindings 変数が生成され、これが AgenticScope 状態に追加され、この新しい変数が HypothesisAgent の呼び出しをトリガーします。次に、これにより hypothesis が生成され、次に criticAgent がトリガーされます。最後に、ValidationAgent は、hypothesis と critique の両方の入力を受け取り、最終的に他のエージェントを再度トリガーする新しい hypothesis を生成します。その間、ScorerAgent は score を hypothesis に渡し、この score が 0.85 以上になるか、最大 10 個のエージェント呼び出しが実行されると、プロセスは終了します。次の図は、この実行に関係するすべてのエージェントと変数をまとめたものです。

たとえば、この例の通常の実行は、ScorerAgent が所定のしきい値を超えるスコアを生成したために終了する可能性があります。

Current hypothesis score: 0.95

最終的な出力は次のようになります。

Based on the provided references, here are some key points about stochastic gravitational wave backgrounds (SGWBs) from primordial black holes (PBHs):

1. **Detection Rates and Sources:**
- The detection rate of gravity waves emitted during parabolic encounters of stellar black holes in globular clusters was estimated by Kocsis et al. [85].
- Gravitational wave bursts from PBH hyperbolic encounters were discussed by García-Bellido and Nesseris [93].

2. **Energy Emission:**
- The energy spectrum of gravitational waves from hyperbolic encounters was studied by De Vittori, Jetzer, and Klein [88].
- Gravitational wave energy emission and detection rates for PBH hyperbolic encounters were analyzed by García-Bellido and Nesseris [90].

3. **Template Banks:**
- Template banks for gravitational waveforms from coalescing binary black holes (including non-spinning binaries) were developed by Ajith et al. [92].

4. **Constraints on PBHs:**
- Constraints on primordial black holes were reviewed by Carr, Kohri, Sendouda, and Yokoyama [98].
- Universal gravitational wave signatures of cosmological solitons were discussed by Lozanov, Sasaki, and Takhistov [100].

5. **Induced SGWBs:**
- Doubly peaked induced stochastic gravitational wave backgrounds were tested for baryogenesis from primordial black holes by Bhaumik et al. [101].
- Distinct signatures of spinning PBH domination and evaporation, including doubly peaked gravitational waves, dark relics, and CMB complementarity, were explored by Bhaumik et al. [101].

6. **Future Detectors:**
- Future detectors like Taiji, LISA, DECIGO, Big Bang Observer, Cosmic Explorer, Einstein Telescope, and KAGRA are expected to contribute significantly to the detection of SGWBs from PBHs.

7. **Pulsar Timing Arrays:**
- Pulsar timing arrays have been used to search for an isotropic stochastic gravitational wave background [73-75].

8. **Template Banks and Simulations:**
- Template banks like those developed by Ajith et al. are crucial for matching observed signals with theoretical predictions.

黒板エージェントパターン​

P2P パターンは、準備ができているすべてのエージェントを並行してアクティブ化し、それらを同等のピアとして扱います。ただし、複数のエージェントが関与する可能性がある場合に競合解決を適用して、集中スケジューラが次に起動する単一エージェントを決定する必要があるシナリオもあります。これは黒板パターンです。エージェントは部分的な結果を AgenticScope (黒板) に投稿する知識源であり、集中プランナーは各ステップの後に黒板を検査して、最も適切なエージェントをアクティブにします。

P2P と同様に、エージェントは、すべての引数がスコープ内に存在する場合に暗黙的にアクティブ化されます。主な違いは、ステップごとに 1 つのエージェントのみが起動し、複数のエージェントの準備ができている場合、ConflictResolutionStrategy によってどのエージェントが優先されるかが決定されることです。戦略が指定されていない場合は、subAgents メソッドの宣言順序がデフォルトのタイブレーカーとして使用されます。

BlackboardPlanner は、目標述語が満たされるか、エージェントが起動できない (静止) 場合に正常に終了します。目標が満たされる前に呼び出しの最大数に達すると、IllegalStateException がスローされます。デフォルトでは、目標述語はプランナーの outputKey がスコープ内に存在するかどうかをチェックします。これは最も一般的な終了条件です。

public class BlackboardPlanner implements Planner {

private final Predicate<AgenticScope> goalPredicate;
private final ConflictResolutionStrategy conflictResolutionStrategy;
private final int maxInvocations;

@Override
public Action nextAction(PlanningContext planningContext) {
// After each agent completes:
// 1. Check goal predicate → done() if satisfied
// 2. Find all agents whose inputs are available
// 3. Pick the best one via conflict resolution (or declaration order)
// 4. Return call(selectedAgent) — always exactly one agent per step
}
}

ConflictResolutionStrategy は、現在のスコープと、発火準備ができているすべての候補エージェントを受け取り、アクティブ化すべきものを返す関数型インターフェースです。アクティベーション条件が false のエージェントは、すべての入力が利用可能な場合でも候補になりません。また、呼び出し時にスキップされたエージェントは、他のエージェントをアクティブ化し得る出力の変更とはみなされません。

@FunctionalInterface
public interface ConflictResolutionStrategy {

AgentInstance resolve(AgenticScope scope, List<AgentInstance> candidates);
}

このインターフェイスには、複数の戦略をチェーンするための or コンビネータとともに、いくつかの便利なファクトリ メソッドが付属しています。たとえば、declarationOrder() は、subAgents メソッドで使用される順序を維持して最初の候補を単純に選択しますが、agentOfType は、指定されたタイプに一致する候補を選択します (オプションで AgenticScope の条件によって保護され、条件が満たされない場合、またはそのタイプの候補が存在しない場合は null を返します)。 or コンビネータは 2 つの戦略を連鎖させます。最初の戦略が null を返した場合、2 番目の戦略が試行されます。これらを組み合わせると、「条件が成立する場合はタイプ X のエージェントを優先し、そうでない場合は宣言順序にフォールバックする」という agentOfType(X.class, condition).or(declarationOrder()) のようなパイプラインを構築できます。

実際の例として、専門エージェントが所見を黒板に投稿し、十分な証拠が蓄積された場合にのみ診断が行われる医療診断システムを考えてみましょう。エージェントが起動する順序はあらかじめ決まっていませんが、利用可能なデータによって異なります。

SymptomExtractor symptomExtractor = AgenticServices.agentBuilder(SymptomExtractor.class)
.chatModel(baseModel()).build();

LabResultAnalyzer labAnalyzer = AgenticServices.agentBuilder(LabResultAnalyzer.class)
.chatModel(baseModel()).build();

DrugInteractionChecker drugInteraction = AgenticServices.agentBuilder(DrugInteractionChecker.class)
.chatModel(baseModel()).build();

DiagnosisAgent diagnosis = AgenticServices.agentBuilder(DiagnosisAgent.class)
.chatModel(baseModel()).build();

MedicalDiagnostics diagnostics = AgenticServices.plannerBuilder(MedicalDiagnostics.class)
.subAgents(symptomExtractor, labAnalyzer, drugInteraction, diagnosis)
.planner(BlackboardPlanner::new)
.outputKey("diagnosis")
.build();

String result = diagnostics.diagnose(patientInput, labResults, medications);

SymptomExtractor は、最初から唯一の入力 (patientInput) が利用可能であるため、最初に起動されます。症状が抽出されると、LabResultAnalyzer と DrugInteractionChecker の両方が対象となる可能性がありますが、ステップごとに起動されるのは 1 つだけです。最後に、symptoms と labAnalysis の両方が黒板上にある場合、DiagnosisAgent が起動されます。デフォルトの目標述語が "diagnosis" (プランナーの outputKey) がスコープ内に存在することを検出したため、システムは終了します。終了条件がより複雑な場合は、カスタムの目標述語を BlackboardPlanner コンストラクターに提供できます。

臨床状況がエージェントのオーダーに重要な場合、ConflictResolutionStrategy はスコープの状態を検査して、情報に基づいた決定を下すことができます。たとえば、患者の症状が薬剤や副作用について述べている場合、臨床検査よりも薬物相互作用分析を優先する必要があります。

MedicalDiagnostics diagnostics = AgenticServices.plannerBuilder(MedicalDiagnostics.class)
.subAgents(symptomExtractor, labAnalyzer, drugInteraction, diagnosis)
.planner(() -> new BlackboardPlanner(
agentOfType(DrugInteractionChecker.class, scope -> {
String symptoms = scope.readState("symptoms", "");
return symptoms.toLowerCase().contains("medication")
|| symptoms.toLowerCase().contains("drug");
})
.or(declarationOrder())))
.outputKey("diagnosis")
.build();

この例をさらに充実させるために、HumanInTheLoop エージェントが黒板の知識源として直接参加することもできます。 inputKey メソッドは人間のレビュー担当者が依存するスコープ キーを宣言するため、ブラックボードはそのデータが利用可能な場合にのみメソッドをアクティブにします。その outputKey は "symptoms" に設定されます。レビュー担当者が診断を拒否すると、戻り値によって症状が追加情報で上書きされ、当然のことながら症状に​​依存するすべてのエージェントが再トリガーされます。

HumanInTheLoop humanReview = AgenticServices.humanInTheLoopBuilder()
.description("Review the diagnosis and decide whether to approve or request additional analysis")
.outputKey("symptoms")
.inputKey(String.class, "diagnosis")
.responseProvider(scope -> {
String diagnosis = scope.readState("diagnosis", "");
String symptoms = scope.readState("symptoms", "");
if (!isAcceptable(diagnosis)) {
return symptoms + ". Patient also reports blurred vision.";
}
scope.writeState("approvedDiagnosis", diagnosis);
return symptoms;
})
.build();

MedicalDiagnostics diagnostics = AgenticServices.plannerBuilder(MedicalDiagnostics.class)
.subAgents(symptomExtractor, labAnalyzer, drugInteraction, diagnosisAgent, humanReview)
.planner(() -> new BlackboardPlanner(
scope -> scope.hasState("approvedDiagnosis"),
agentOfType(DrugInteractionChecker.class, scope -> {
String symptoms = scope.readState("symptoms", "");
return symptoms.toLowerCase().contains("medication")
|| symptoms.toLowerCase().contains("drug");
})
.or(declarationOrder())))
.outputKey("approvedDiagnosis")
.build();

inputKey(String.class, "diagnosis") は、レビューアがスコープ内に "diagnosis" が存在した後にのみアクティブ化する必要があることをブラックボードに指示します。レビュー担当者が拒否すると、戻り値 (強化された症状) が HITL の outputKey 経由で "symptoms" キーに書き込まれます。その後、黒板の通常の onStateChanged("symptoms") メカニズムが症状に応じたエージェント (DrugInteractionChecker や DiagnosisAgent など) を再活性化し、次のレビュー用に修正された診断を生成します。この 2 番目の実装では、BlackboardPlanner を通じて実装された MedicalDiagnostics の OutputKey が、"diagnosis" から "approvedDiagnosis" に変更され、HumanInTheLoop がエージェント システムの実行に参加できるようになっていることに注意してください。このようにして、レビュー担当者が承認すると、"approvedDiagnosis" が AgenticScope に書き込まれ、目標述語が満たされます。

投票エージェントのパターン​

ここまで説明したエージェント パターンはすべて、作業を分割したり、タスクを順序付けたり、決定をルーティングしたりするなど、さまざまな作業を行うエージェントを調整します。ただし、複数のエージェントが同じ問題に個別に取り組み、その回答を集約してより堅牢な結果を生成したい場合があります。これは投票 (または評議会) パターンです。同じ入力に対してすべてのサブエージェントを並行して実行し、その出力を投票として収集し、プラグイン可能な集約戦略を通じてそれらを調整します。

このパターンは、分類、コンテンツのモデレーション、リスク評価、および単一のエージェントの判断よりも多様なアプローチにわたる合意の方が信頼できるあらゆる意思決定に特に役立ちます。異なるプロンプト、モデル、または視点を持つエージェントに同じ入力を分析させることで、単一のエージェントの偏見やエラーが最終結果に伝播する可能性を減らします。

VotingPlanner は、すべてのサブエージェントを並行してディスパッチし、すべてのサブエージェントが完了するまで待機し、VotingStrategy を使用して出力を集約します。

public class VotingPlanner implements Planner {

private final VotingStrategy strategy;

private List<AgentInstance> subagents;
private int completedCount;
private final List<Object> votes = new ArrayList<>();

public VotingPlanner() {
this(VotingStrategy.majority());
}

public VotingPlanner(VotingStrategy strategy) {
this.strategy = strategy;
}

@Override
public void init(InitPlanningContext initPlanningContext) {
this.subagents = initPlanningContext.subagents();
}

@Override
public Action firstAction(PlanningContext planningContext) {
if (subagents.isEmpty()) {
return done();
}
return call(subagents);
}

@Override
public Action nextAction(PlanningContext planningContext) {
votes.add(planningContext.previousAgentInvocation().output());
completedCount++;

if (completedCount < subagents.size()) {
return noOp();
}

return done(strategy.aggregate(votes));
}

@Override
public AgenticSystemTopology topology() {
return AgenticSystemTopology.STAR;
}
}

firstAction メソッドは、すべてのサブエージェントを一度にディスパッチします。トポロジは STAR であるため、フレームワークはそれらを並列実行し、エージェントの完了ごとに nextAction を 1 回呼び出します。各呼び出しでは、完了したエージェントの出力が投票として収集されます。すべてのエージェントが投票すると、プランナーは VotingStrategy を通じて結果を集計し、完了を通知します。

VotingStrategy は、1 つのメソッドと 3 つの組み込み静的ファクトリ メソッドを備えた機能インターフェイスです。

@FunctionalInterface
public interface VotingStrategy {

Object aggregate(Collection<Object> votes);

static VotingStrategy majority() { ... } // most common value wins
static VotingStrategy average() { ... } // mean of numeric values
static VotingStrategy highest() { ... } // max by natural ordering
}
  • majority() は、平等性によって投票をグループ化し、最も一般的な値を返します。エージェントがカテゴリラベルを返す分類タスクに最適です。
  • average() は、数値投票の算術平均を計算します。これは、エージェントが信頼値または評価を返すタスクのスコアリングに役立ちます。
  • highest() は、自然な順序で最大値を選択します。これは、最も楽観的または最も信頼性の高い評価が必要な場合に適しています。

ユーザーは、ラムダ式を介してカスタム戦略を提供することもできます。たとえば、加重投票、信頼度ベースのフィルタリング、またはクォーラム ルールを実装できます。

これがどのように機能するかの実際的な例を示すために、異なるプロンプトを持つ 3 つの独立したエージェントを使用して顧客のフィードバックを分類する、投票ベースのセンチメント分類器を構築してみましょう。各エージェントは、ポジティブ、ネガティブ、またはニュートラルの 1 つの単語を返すように指示されます。

public interface SentimentClassifier1 {

@UserMessage("""
Classify the sentiment of the following text.
Reply with exactly one word: POSITIVE, NEGATIVE, or NEUTRAL.
The text is: "{{text}}"
""")
@Agent("Classify the sentiment of a given text")
String classify(@V("text") String text);
}

public interface SentimentClassifier2 {

@UserMessage("""
You are a sentiment analysis expert.
Analyze the emotional tone of the following text and classify it.
Reply with exactly one word: POSITIVE, NEGATIVE, or NEUTRAL.
The text is: "{{text}}"
""")
@Agent("Analyze the emotional tone of a given text")
String classify(@V("text") String text);
}

public interface SentimentClassifier3 {

@UserMessage("""
You are a customer feedback analyst.
Determine whether the following feedback is positive, negative, or neutral.
Reply with exactly one word: POSITIVE, NEGATIVE, or NEUTRAL.
The text is: "{{text}}"
""")
@Agent("Determine the sentiment of customer feedback")
String classify(@V("text") String text);
}

各分類子は、わずかに異なる角度から同じタスクにアプローチします。1 つは一般的な分類子、1 つは専門アナリスト、もう 1 つは顧客のフィードバックに特化しています。これら 3 つのエージェントを組み合わせて、投票ベースのエージェント システムを構築できます。

SentimentClassifier1 c1 = AgenticServices.agentBuilder(SentimentClassifier1.class)
.chatModel(baseModel())
.outputKey("vote1")
.build();

SentimentClassifier2 c2 = AgenticServices.agentBuilder(SentimentClassifier2.class)
.chatModel(baseModel())
.outputKey("vote2")
.build();

SentimentClassifier3 c3 = AgenticServices.agentBuilder(SentimentClassifier3.class)
.chatModel(baseModel())
.outputKey("vote3")
.build();

SentimentVoter voter = AgenticServices.plannerBuilder(SentimentVoter.class)
.subAgents(c1, c2, c3)
.outputKey("classification")
.planner(VotingPlanner::new)
.build();

ResultWithAgenticScope<String> result = voter.classify(
"I absolutely love this product! It exceeded all my expectations.");

この構成では、3 つの分類子が同じテキストに対して並行して呼び出されます。それぞれがその分類を独自の出力キー (vote1、vote2、vote3) に書き込み、VotingPlanner は 3 つの結果すべてを収集します。デフォルトのコンストラクターは VotingStrategy.majority() を使用するため、最も一般的な分類が優先されます。上記の明らかに肯定的なテキストの場合、3 人のエージェント全員が POSITIVE を返し、全会一致の結果が得られる可能性があります。しかし、1 人のエージェントが同意しないというあいまいなケースでも、多数決により確実な最終分類が保証されます。

別の集計戦略を使用するには、それを VotingPlanner コンストラクターに渡すだけです。

.planner(() -> new VotingPlanner(VotingStrategy.average()))

または、完全にカスタムの戦略を提供します。

.planner(() -> new VotingPlanner(votes ->
votes.stream()
.map(Object::toString)
.map(String::toUpperCase)
.collect(Collectors.groupingBy(Function.identity(), Collectors.counting()))
.entrySet().stream()
.max(Map.Entry.comparingByValue())
.map(Map.Entry::getKey)
.orElse(null)))

このカスタム戦略は、集計前にすべての投票を大文字に正規化し、エージェント間の小さな書式の違い(例: Positive と POSITIVE)を処理します。

アクティベーション条件により、または任意でありながら引数が欠けているためにスキップされた投票者は投票せず、すべての投票者がスキップされた場合、VotingPlanner は集計する代わりに結果を返しません。

ディベートエージェントパターン​

これまで説明したパターンは、エージェントを 1 回派遣する (投票)、データの可用性に基づいてエージェントをアクティブ化する (ブラックボード、P2P)、または目標に向かってエージェントを順序付けする (GOAP) かのいずれかです。それらのどれも、敵対的な洗練、つまりエージェントが互いの推論を確認し、自分の立場を繰り返し修正するプロセスをサポートしていません。ディベート パターンはこのギャップを埋めます。エージェントは独立した回答を並行して生成し、その後、批評ラウンドに参加し、ディベート履歴全体を読んで議論を洗練させることができます。ラウンドは、エージェントが同じ答えに集まるか、ラウンドの最大数に達するまで続き、その時点でジャッジエージェントが最終的な評決を下します。

このパターンは、事実確認、リスク評価、コード レビュー、およびエージェントが競合する議論にさらされることで出力の品質が向上するあらゆる分野で特に役立ちます。エージェントに互いの推論に対峙して応答するよう強制することで、ディベート パターンは、単独のエージェントでは見逃す可能性のある問題を捉え、敵対的な精査を通じて誤検知を除外します。

このパターンは、サブエージェントを 討論者 (最後を除くすべて) と 裁判官 (最後に登録されたサブエージェント) に分割する DebatePlanner を通じて実装されます。プランナーは、maxRounds (デフォルト 3) と ConvergenceStrategy (デフォルト unanimous()) の 2 つのパラメーターで構成されます。

初期化中に、プランナは少なくとも 3 人のサブエージェント (討論者 2 名と裁判官 1 名) が登録されていることを検証し、それに応じてリストを分割します。最初のアクションは、AgenticScope に空の debateContext キーをシードします。これが必要なのは、討論者エージェントが @V(DEBATE_CONTEXT_KEY) 経由でこのキーを参照するためです。これがないと、最初のラウンドは MissingArgumentException で失敗します。次に、すべての討論者を並行して派遣します。

各ディベーターが完了すると、nextAction が呼び出されます (フレームワークのロックの下でシリアル化されます)。プランナーは、各出力をエージェント名をキーとしたマップに記録し、すべての討論者が終了するまで noOp() を返します。すべての応答が収集されると、ConvergenceStrategy が収束を報告するかどうか、および現在のラウンドが maxRounds に到達したかどうかという 2 つの条件がチェックされます。どちらの場合も、プランナーはジャッジフェーズに入ります。プランナーはディベートコンテキストを AgentName: "response" エントリ (1 行に 1 つ) としてフォーマットし、それをスコープに書き込み、ジャッジエージェントを派遣します。ジャッジが完了すると、プランナーはジャッジの出力を最終結果として含む done() を返します。収束にもラウンド制限にも達しない場合、プランナーは現在のディベート コンテキストをスコープに書き込み、ラウンド カウンターを増分し、すべてのディベーターを別の批評ラウンドに再派遣し、そこでお互いの以前の議論を確認して応答することができます。

ConvergenceStrategy は、単一メソッド hasConverged(Collection<Object> positions) を備えた機能インターフェイスです。 2 つの組み込み戦略が提供されています。unanimous() は、すべての位置にわたって正確な同等性をチェックし (承認/拒否などのラベルベースの決定に適しています)、unanimousLastWord() は、各位置から最後の単語を抽出して大文字に正規化し、すべてのエージェントが同じ判定で終了したかどうかをチェックします。意味的な類似性やしきい値ベースの一致など、より微妙な収束ロジックの場合、ユーザーはカスタム戦略をラムダとして提供できます。

このパターンの実際の動作を確認するために、3 人の倫理討論者が異なる哲学的観点から議論し、裁判官が彼らの議論を総合して最終的な評決を下す討論パネルを構築してみましょう。

public interface UtilitarianDebater {

@UserMessage("""
You are a utilitarian ethics debater. \
Consider the following question and argue from a utilitarian perspective, maximizing overall well-being.
If previous debate context is provided, consider the other debaters' arguments and refine your position.
Keep your response to 2-3 sentences. End with a one-word verdict: AGREE or DISAGREE.
Question: {{question}}
Previous debate context: {{debateContext}}
""")
@Agent(value = "Argues from a utilitarian ethics perspective", name = "Utilitarian")
String debate(@V("question") String question, @V(DEBATE_CONTEXT_KEY) String debateContext);
}

public interface DeontologicalDebater {

@UserMessage("""
You are a deontological ethics debater. \
Consider the following question and argue based on moral rules, duties, and rights.
If previous debate context is provided, consider the other debaters' arguments and refine your position.
Keep your response to 2-3 sentences. End with a one-word verdict: AGREE or DISAGREE.
Question: {{question}}
Previous debate context: {{debateContext}}
""")
@Agent(value = "Argues from a deontological ethics perspective", name = "Deontologist")
String debate(@V("question") String question, @V(DEBATE_CONTEXT_KEY) String debateContext);
}

public interface PragmatistDebater {

@UserMessage("""
You are a pragmatist debater. \
Consider the following question and argue based on practical consequences and real-world outcomes.
If previous debate context is provided, consider the other debaters' arguments and refine your position.
Keep your response to 2-3 sentences. End with a one-word verdict: AGREE or DISAGREE.
Question: {{question}}
Previous debate context: {{debateContext}}
""")
@Agent(value = "Argues from a pragmatist perspective", name = "Pragmatist")
String debate(@V("question") String question, @V(DEBATE_CONTEXT_KEY) String debateContext);
}

public interface EthicsJudge {

@UserMessage("""
You are an impartial ethics judge. \
Review the debate context where multiple debaters have argued about a question from different perspectives.
Synthesize their arguments and provide a balanced, well-reasoned final verdict in 3-4 sentences.
Debate context: {{debateContext}}
""")
@Agent(value = "Renders a final verdict by synthesizing debate arguments", name = "Judge")
String judge(@V("debateContext") String debateContext);
}

各ディベーターは、question (元の入力、一定のまま) と debateContext (ディベート履歴を使用してラウンドごとにプランナーによって更新される) の両方を受け取ります。 @V(DEBATE_CONTEXT_KEY) は、DebatePlanner からの公開定数を参照し、各 @Agent の明示的な name は、ディベート コンテキストでエージェントがどのようにラベル付けされるかを制御します。元の質問は討論のやりとりに埋め込まれているため、裁判官は debateContext のみを受け取ります。お互いに上書きしないように、各ディベーターは個別の outputKey を持っている必要があることに注意してください。

最上位のプランナーのインターフェイスと配線は次のようになります。

public interface EthicsPanel {

@Agent
String debate(@V("question") String question);
}

UtilitarianDebater d1 = AgenticServices.agentBuilder(UtilitarianDebater.class)
.chatModel(baseModel())
.outputKey("utilitarian")
.build();

DeontologicalDebater d2 = AgenticServices.agentBuilder(DeontologicalDebater.class)
.chatModel(baseModel())
.outputKey("deontological")
.build();

PragmatistDebater d3 = AgenticServices.agentBuilder(PragmatistDebater.class)
.chatModel(baseModel())
.outputKey("pragmatist")
.build();

EthicsJudge judge = AgenticServices.agentBuilder(EthicsJudge.class)
.chatModel(baseModel())
.outputKey("verdict")
.build();

EthicsPanel panel = AgenticServices.plannerBuilder(EthicsPanel.class)
.subAgents(d1, d2, d3, judge)
.outputKey("verdict")
.planner(() -> new DebatePlanner(3))
.build();

String result = panel.debate(
"Is it ethical to use AI-generated art in commercial products without crediting the AI tool?");

討論者が最初に列挙され、審判は常に最後のサブエージェントです。ラウンド 1 では、3 人の討論者がそれぞれ独立した立場を示します。ラウンド 2 では、各討論者が他の討論者の主張を見て、自分の立場を洗練、反論、または拡張できます。討論者が収束するか、最大ラウンド数に達するかにかかわらず、審判は常に討論の全体的な文脈に基づいて最終的な判断を下します。アクティベーション条件によりスキップされた討論者はそのラウンドに参加せず、前のラウンドの立場があればそれを保持します。スキップされた審判は、その出力キーの現在の値で討論を終了します。

収束チェックまたはラウンド数をカスタマイズするには:

.planner(() -> new DebatePlanner(5))  // allow up to 5 rounds
.planner(() -> new DebatePlanner(positions ->
positions.stream().allMatch(p -> p.toString().contains("AGREE")))) // custom convergence

信念-欲望-意図 (BDI) エージェント パターン​

Belief-Desire-Intention (BDI) パターンは、明示的な目標を維持し、現在達成可能な目標を評価し、環境が変化したときにそれらの目標を反応的に切り替えるエージェントの古典的な AI 概念をモデル化します。このパターンを実装するプランナーは、信念 (AgenticScope からの現在の世界状態)、欲望 (優先順位付けされた一連の目標)、および意図 (現在実行されているコミットされた計画) の 3 つの構造を維持します。各ステップでプランナーは、より優先度の高い願望が達成可能になったかどうかを確認し、達成可能であれば現在の意図を取り下げて再検討します。このため、BDI は、複数の競合する目標のバランスをとる必要があり、優先順位がいつでも変更される可能性がある動的な環境に自然に適しています。

Desire は、名前、優先度レベル、達成可能述語、満足述語、およびその欲求を追求する意図を形成するエージェント タイプの順序付きリストを組み合わせたレコードとして定義されます。

public record Desire(String name, int priority,
Predicate<AgenticScope> achievable,
Predicate<AgenticScope> satisfied,
List<Class<?>> agentTypes) {

public static Desire of(String name, int priority,
Predicate<AgenticScope> achievable,
Predicate<AgenticScope> satisfied,
Class<?>... agentTypes) {
return new Desire(name, priority, achievable, satisfied, List.of(agentTypes));
}

public static Desire of(String name, int priority,
String achievableStateKey,
String satisfiedStateKey,
Class<?>... agentTypes) {
return new Desire(name, priority,
scope -> scope.hasState(achievableStateKey),
scope -> scope.hasState(satisfiedStateKey),
List.of(agentTypes));
}
}

このパターンを実装する BDIPlanner は、Desire インスタンスのリストを取得し、審議サイクルを実装します。初期化中に、登録された各サブエージェントをタイプごとにマップし、デザイアがクラスごとにエージェントを参照できるようにします。実行が開始されると、プランナーはすべての欲求をフィルタリングして、現在達成可能でまだ満たされていない欲求を見つけ、最も高い優先順位を持つものを選択し (同じ優先順位の中で、リストで最初に宣言されたものが優先されます)、その欲求によって定義されるエージェントの順序付けされたシーケンスとして定義されるその意図にコミットします。後続の各ステップで、プランナーは 3 つのチェックを実行します。まず、満足。現在の欲求が満たされているかどうかをテストし、プランナーは次の欲求を選択するために再検討します。 2 番目、プリエンプション。信念の変更 (AgenticScope に書き込まれる新しい値) により、厳密に優先順位の高い願望が達成可能になったかどうかを検証し、現在の意図は一時停止され、優先順位の高いものが引き継ぎます。 3 番目に、実行可能性 で現在の欲求がまだ達成可能か、満たされていないかを確認し、プランナーは意図シーケンスの次のエージェントに進みます。プリエンプトされたディザイアが後で再選択されると、再起動するのではなく中断したところから再開されるため、すでに完了したエージェントが再度呼び出されることはありません。

すべての欲求が満たされるか、何も達成できない場合、実行は正常に終了します。プランナーは、2 つの不正な動作のシナリオで IllegalStateException をスローします。 1 つは、ディザイアのインテント全体が完了したが、ディザイアが満たされないままの場合 (満たされた述語が期待するキーをエージェントが書き込まない場合)、または、満たされていないディザイアがまだ保留中の状態で、構成可能な最大呼び出し回数に達した場合です。

クラッシュからの回復時に、プランナーは最初から再検討します。満たされた欲求はスキップされますが、選択された欲求の意図は最初のエージェントから再開されます。クラッシュ前にすでに完了していたエージェントは再度実行されるため、インテンション エージェントは冪等である必要があります。

このパターンを説明するために、5 つの AI エージェントと 1 つの非 AI エージェントを備えた自律取引システムを考えてみましょう。 MarketRecommendationAgent は MarketRecommendation 列挙型を返し、ヘッジは推奨事項が SELL または STRONG_SELL の場合にのみトリガーされます。 HedgingStrategyDefaulter は、hedgingStrategy が常にスコープ内に存在することを保証する非 AI エージェント (ヘッジがスキップされた場合のデフォルトは "None") であるため、RebalancingAgent は常にそれを入力として受け取ることができます。

public enum MarketRecommendation {
STRONG_BUY, BUY, HOLD, SELL, STRONG_SELL
}

public interface MarketAnalysisAgent {
@UserMessage("Analyze the market data and portfolio. Market: {{marketData}} Portfolio: {{portfolio}}")
@Agent(value = "Analyze market conditions", outputKey = "marketAnalysis")
String analyzeMarket(@V("marketData") String marketData, @V("portfolio") String portfolio);
}

public interface MarketRecommendationAgent {
@UserMessage("Based on the market analysis, provide a trading recommendation. Market analysis: {{marketAnalysis}}")
@Agent(value = "Provide a trading recommendation", outputKey = "recommendation")
MarketRecommendation recommend(@V("marketAnalysis") String marketAnalysis);
}

public static class HedgingStrategyDefaulter {
@Agent(outputKey = "hedgingStrategy")
public String defaultHedging(AgenticScope scope) {
return scope.hasState("hedgingStrategy") ? (String) scope.readState("hedgingStrategy") : "None";
}
}

public interface RebalancingAgent {
@UserMessage("Suggest rebalancing based on: {{marketAnalysis}} Hedging strategy: {{hedgingStrategy}} Portfolio: {{portfolio}}")
@Agent(value = "Rebalance portfolio", outputKey = "rebalancingPlan")
String rebalance(@V("marketAnalysis") String marketAnalysis,
@V("hedgingStrategy") String hedgingStrategy,
@V("portfolio") String portfolio);
}

public interface HedgingAgent {
@UserMessage("Recommend hedging strategies based on: {{marketAnalysis}}")
@Agent(value = "Hedge against risks", outputKey = "hedgingStrategy")
String hedge(@V("marketAnalysis") String marketAnalysis);
}

public interface LiquidityAgent {
@UserMessage("Assess liquidity for portfolio: {{portfolio}}")
@Agent(value = "Maintain liquidity", outputKey = "liquidityAssessment")
String assessLiquidity(@V("portfolio") String portfolio);
}

これらのエージェントは、優先順位の異なる 4 つの欲求を備えた BDI ベースの取引システムに接続されています。 「リスクヘッジ」デザイアでは、推奨値を検査する述語ベースの達成可能性チェックが使用されており、「ポートフォリオのリバランス」デザイアでは、hedgingStrategy スコープ値が存在することを保証するために、RebalancingAgent の前に HedgingStrategyDefaulter が含まれていることに注意してください。

TradingSystem tradingSystem = AgenticServices.plannerBuilder(TradingSystem.class)
.subAgents(marketAnalysis, recommendation, new HedgingStrategyDefaulter(),
rebalancing, hedging, liquidity)
.planner(() -> new BDIPlanner(List.of(
Desire.of("analyze market", 1,
"marketData", "recommendation",
MarketAnalysisAgent.class, MarketRecommendationAgent.class),
Desire.of("hedge risks", 2,
scope -> scope.hasState("recommendation")
&& Set.of(MarketRecommendation.SELL, MarketRecommendation.STRONG_SELL)
.contains(scope.readState("recommendation")),
scope -> scope.hasState("hedgingStrategy"),
HedgingAgent.class),
Desire.of("rebalance portfolio", 1,
"recommendation", "rebalancingPlan",
HedgingStrategyDefaulter.class, RebalancingAgent.class),
Desire.of("maintain liquidity", 1,
"portfolio", "liquidityAssessment",
LiquidityAgent.class)
)))
.build();

市場データとポートフォリオ状態を使用して呼び出される場合、プランナーの検討サイクルは次のように機能します。「市場の分析」と「流動性の維持」の要望は最初に達成可能です。 MarketAnalysisAgent と MarketRecommendationAgent が完了すると、推奨事項によって次のステップが決定されます。推奨事項が SELL または STRONG_SELL の場合、「リスクヘッジ」の要望 (優先度 2) が達成可能になり、優先度の低い作業が優先され、プランナーは HedgingAgent を呼び出します。ヘッジ完了後、プランナーは再検討します。「リバランス ポートフォリオ」デザイアは HedgingStrategyDefaulter (既存のヘッジ戦略を保存) を実行し、続いて RebalancingAgent を実行し、入力としてヘッジ戦略を受け取ります。推奨が SELL または STRONG_SELL ではない場合、ヘッジは完全にスキップされ、HedgingStrategyDefaulter は "None" を書き込むため、RebalancingAgent は引き続き続行できます。この反応的な条件主導型の切り替えが BDI の本質です。システムは、厳格な計画に従うのではなく、変化する信念に基づいて動作を適応させます。

決定ルーターのエージェント型パターン​

备注

決定ルーターは実験的な DecisionModel API に基づいており、将来のリリースで変更される可能性があります。

決定ルーターは langchain4j-agentic-patterns モジュールで提供され、langchain4j-typesafe などの決定モデルのインテグレーションも必要です。

前述の条件付きワークフローは、リクエストを 2 段階で適切な専門家にルーティングします。まず LLM ベースの CategoryRouter エージェントが AgenticScope にカテゴリを書き込み、次に条件付きエージェントが、そのカテゴリに対して専門家ごとに 1 つの述語を評価します。これは機能しますが、ルーティングの判断のたびに、テキストの回答を解析しなければならない完全な LLM 呼び出しが必要になり、列挙型と述語を専門家と同期させておく必要があり、さらに LLM が選択にどれだけ確信を持っていたかについては何も分かりません。

この種のタスクには、決定モデルの方が適しています。テキストを生成する代わりに、入力に関する型付きの質問に答え、可能な各回答の確率を返します。決定ルーターパターンでは、これを使ってサブエージェントの中から直接選択します。各サブエージェントは、名前と説明で記述された単一の選択式の質問の選択肢となり、決定モデルは最も確率の高いものと、すべてのサブエージェントの確率を返します。オプションでアクティベーションしきい値を指定すると、ルーターは代わりに各サブエージェントがそのリクエストを処理すべきかどうかを尋ね、確率がしきい値に達したすべてのサブエージェントを並列に呼び出します。これは、リクエストが複数の領域にまたがる場合に便利です。

このパターンを実装する DecisionRouterPlanner は、DecisionModel と、必要に応じて 0 より大きく 1 より小さいアクティベーションしきい値を指定して作成されます。初期化時にプランナーは、各サブエージェントを単一の ChoiceQuestion「このリクエストの処理に最も適したエージェントはどれですか?」の選択肢に変換し、サブエージェントの名前を選択肢名、その説明をその選択肢が当てはまる場面の説明として使用します。アクティベーションしきい値がある場合は、代わりにサブエージェントごとに 1 つの YesNoQuestion(たとえば「エージェント 'medical'(健康、けが、治療に関する質問に答える医療の専門家)はこのリクエストを処理すべきですか?」)が作成され、すべてが同じリクエストで尋ねられます。つまり、決定モデルはサブエージェントの説明を読んでリクエストをルーティングするため、各サブエージェントがどのリクエストを処理するためのものかを明確に記述する必要があります。質問の入力は、AgenticScope から読み取られるルーターエージェント自身の引数で構成されるため、ルーターは型付きエージェントインターフェースで定義する必要があり、そのサブエージェントの名前は互いに異なっていなければなりません。

ルーターが呼び出されると、プランナーは決定モデルに対してこれらの質問を 1 回の呼び出しで行い、その回答からアクティブ化するサブエージェントを選択します。内部的には、その firstAction メソッドはおおよそ次のことを行います。

DecisionResponse response = decide(planningContext.agenticScope());
activated = activationThreshold == null
? List.of(response.choice(QUESTION_NAME).value())
: routes.keySet().stream()
.filter(name -> response.yesNo(name).probability() >= activationThreshold)
.toList();

アクティベーションしきい値がない場合、最も確率の高いサブエージェントだけが呼び出され、nextAction メソッドはその出力をルーターの結果として返します。アクティベーションしきい値がある場合、「yes」の確率がしきい値以上のすべてのサブエージェントが並列に呼び出され、nextAction メソッドがそれらの出力を収集するため、ルーターの結果は、呼び出された各サブエージェントの名前からその出力へのマップとなり、しきい値に達したサブエージェントがない場合は空になります。

プランナーは、アクティブ化されたサブエージェントの名前と、そのうち完了済みのものの出力も、実行状態として保存します。これにより、たとえばアクティブ化されたサブエージェントの 1 つが人間を待っているために一時停止した後や、クラッシュ後にエージェント型システムが再開されるとき、ルーターは決定モデルに再度問い合わせません。まだ実行されていないアクティブ化されたサブエージェントだけを呼び出し、その結果には中断前に収集された出力が引き続き含まれます。

実用的な例として、条件付きワークフローのセクションにあった専門家ルーターを再実装してみましょう。専門家は同じですが、その説明がどのリクエストを処理するかを示すようになっています。

public interface MedicalExpert {

@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 {{request}}.
""")
@Agent(description = "A medical expert, answering questions about health, injuries and treatments",
outputKey = "medicalResponse")
String medical(@V("request") String request);
}

LegalExpert("A legal expert, answering questions about laws, rights, contracts and lawsuits")と TechnicalExpert("A technical expert, answering questions about computers, software and devices")のエージェントも同様です。CategoryRouter エージェントと RequestCategory 列挙型はもう必要ありません。ExpertRouterAgent インターフェースは、TypeSafe などの決定モデルで構成された DecisionRouterPlanner によって直接実装されます。

DecisionModel decisionModel = TypeSafeDecisionModel.builder()
.apiKey(System.getenv("TYPESAFE_API_KEY"))
.modelName("jev-1.13.0")
.build();

ExpertRouterAgent expertRouterAgent = AgenticServices.plannerBuilder(ExpertRouterAgent.class)
.subAgents(medicalExpert, legalExpert, technicalExpert)
.outputKey("response")
.planner(() -> new DecisionRouterPlanner(decisionModel))
.build();

String response = expertRouterAgent.ask("I broke my leg, what should I do?");

ここで決定モデルは、入力 {"request": "I broke my leg, what should I do?"} と、選択肢 medical、legal、technical を持つ質問「このリクエストの処理に最も適したエージェントはどれですか?」を受け取り、medical を選択します。そのため、MedicalExpert だけが呼び出され、その回答が返されます。

ただし、リクエストによっては複数の領域にまたがるものもあります。確率が指定したしきい値に達したすべての専門家を呼び出すには、しきい値をプランナーに渡し、呼び出された各専門家の名前からその回答へのマップをルーターに返させます。

public interface MultiExpertRouterAgent {

@Agent
Map<String, String> ask(@V("request") String request);
}

MultiExpertRouterAgent multiExpertRouterAgent = AgenticServices.plannerBuilder(MultiExpertRouterAgent.class)
.subAgents(medicalExpert, legalExpert, technicalExpert)
.outputKey("responses")
.planner(() -> new DecisionRouterPlanner(decisionModel, 0.5))
.build();

Map<String, String> responses = multiExpertRouterAgent.ask(
"I broke my leg in a car accident caused by another driver: " +
"how should I take care of my leg, and can I sue the driver for damages?");

このリクエストでは、MedicalExpert と LegalExpert の両方がしきい値に達すると予想されるため、並列に呼び出され、返されるマップには medical と legal のキーの下に 2 つの回答が含まれます。たとえばチョコレートケーキのレシピを尋ねるリクエストのように、しきい値に達する専門家がいない場合は、どの専門家も呼び出されず、返されるマップは空になります。

各サブエージェントには、他とは独立した固有の確率が割り当てられることに注意してください。複数のサブエージェントが高いしきい値に達することがあり、サブエージェントを追加しても既存のものの確率は変わりません。同じ理由で、あらゆる種類の質問に答える汎用アシスタントのような、非常に広範な説明を持つサブエージェントは、ほとんどのリクエストでアクティブ化される傾向があります。そのため、しきい値を使う場合は各サブエージェントを正確に記述し、空の結果は関連するサブエージェントがない場合として扱うのが望ましいです。また、確率の較正の仕方はモデルによって異なるため、しきい値は自分のリクエストで調整し、決定モデルやそのバージョンを変更した際にも再調整する必要があります。

他のエージェント型パターンと同様に、決定ルーターはより複雑なエージェント型システムの 1 ステップにできます。たとえば、アクティブ化された専門家の回答は、シーケンス内でルーターの後に呼び出される ResponseSynthesizer エージェントによって 1 つにまとめられます。

public interface ResponseSynthesizer {

@UserMessage("""
Merge the answers that different experts gave to the same user request into a single answer.
The user request is: {{request}}
The answers of the experts, keyed by expert, are: {{responses}}
""")
@Agent(description = "Merges the answers of several experts into one", outputKey = "answer")
String synthesize(@V("request") String request, @V("responses") Map<String, String> responses);
}

public interface ExpertPipeline {

@Agent
String process(@V("request") String request);
}

ResponseSynthesizer responseSynthesizer = AgenticServices.agentBuilder(ResponseSynthesizer.class)
.chatModel(BASE_MODEL)
.build();

ExpertPipeline pipeline = AgenticServices.sequenceBuilder(ExpertPipeline.class)
.subAgents(multiExpertRouterAgent, responseSynthesizer)
.outputKey("answer")
.build();

同じルーターは、@PlannerSupplier をアノテートした静的メソッドでプランナーを提供することで、宣言型 API でも定義できます。

public interface DeclarativeExpertRouter {

@PlannerAgent(
outputKey = "response",
subAgents = {MedicalExpert.class, LegalExpert.class, TechnicalExpert.class})
String ask(@V("request") String request);

@PlannerSupplier
static Planner planner() {
return new DecisionRouterPlanner(TypeSafeDecisionModel.builder()
.apiKey(System.getenv("TYPESAFE_API_KEY"))
.modelName("jev-1.13.0")
.build());
}
}

ここで専門家は、宣言型 API のセクションで説明したように、@ChatModelSupplier を通じてチャットモデルを提供します。

最後に、ルーターエージェントの引数はそのまま決定モデルに送信されるため、文字列、数値、ブール値、またはそれらのマップやリストにできることに留意してください。それ以外の型の引数は、サポートされる型を説明するエラーとともに決定モデルによって拒否されます。また、ルーティングの判断はユーザーの入力に従うため、認可の境界ではないことにも注意してください。たとえば許可されたユーザーのみなど、特定の条件下でのみ使用すべきサブエージェントは、たとえばアクティベーション条件を通じて、独自のアクセスチェックを実施する必要があります。アクティベーション条件が成立しているサブエージェントだけが決定モデルに提示され、どれも成立していない場合は決定モデルにまったく問い合わせず、その場合ルーターは結果を返さないか、アクティベーションしきい値がある場合は空のマップを返します。アクティベーションしきい値がない場合、アクティブなサブエージェントが 1 つだけなら、決定モデルに問い合わせずにそれが呼び出されます。判断後に条件が変わったために呼び出し時にスキップされたサブエージェントは、アクティベーションしきい値がある場合は返されるマップから除外され、しきい値がない場合はルーターが結果を返しません。

信頼度カスケードのエージェント型パターン​

备注

信頼度カスケードは実験的な DecisionModel API に基づいており、将来のリリースで変更される可能性があります。

信頼度カスケードは langchain4j-agentic-patterns モジュールで提供され、langchain4j-typesafe などの決定モデルのインテグレーションも必要です。

多くのエージェント型システムでは、ほとんどのリクエストは簡単で、小さく安価なモデルで回答できますが、一部のリクエストには大きなモデルや、場合によっては人間が必要です。すべてのリクエストを最も高性能なエージェントに送ると、すべてに最高のコストを支払うことになり、最も安価なエージェントに送ると、難しいリクエストに対して質の低い回答しか得られません。リクエストの難易度がリクエストだけから判断できる場合は、決定ルーターがそれを安価なエージェントまたは高性能なエージェントへ直接送ることができます。しかし多くの場合、安価なエージェントで十分だったかどうかは、その回答を見てからでないと判断できません。

信頼度カスケードパターンは、このトレードオフに対処します。そのサブエージェントは、たとえば小さなモデル上のエージェント、大きなモデル上の同じエージェント、そして最後に人間というように、最も安価なものから最も高性能なものへと宣言され、これらがカスケードの階層(ティア)になります。最初のティアがリクエストに回答し、次に決定モデルがリクエストに照らしてその回答を評価します。回答が十分に良い確率が受け入れしきい値に達すれば、その回答が返され、そうでなければ次のより高価なティアが試されます。決定モデルはこの評価に適しています。解析が必要なテキストではなく確率を返し、回答の評価は回答の生成よりはるかに安価だからです。

このパターンを実装する ConfidenceCascadePlanner は、DecisionModel、0 より大きく 1 より小さい受け入れしきい値、および必要に応じて回答を受け入れる条件を記述した受け入れ基準を指定して作成されます。初期化時にプランナーは、宣言順のサブエージェントをティアとして、カスケードエージェント自身の引数をリクエストとして扱うため、カスケードは型付きエージェントインターフェースで定義する必要があり、少なくとも 2 つのサブエージェントが必要です。その firstAction メソッドは最初のティアを呼び出し、nextAction メソッドは直前に完了したティアの回答を評価します。具体的には、決定モデルに対して YesNoQuestion「回答はリクエストに完全かつ正確に対応していますか?」を、カスケードエージェントの引数と candidateAnswer フィールドの回答で構成された入力とともに尋ね、受け入れ基準があればそれを質問の yesWhen の説明として使用します。内部的には、ティアの回答が得られると、プランナーはおおよそ次のことを行います。

double probability = acceptance(planningContext.agenticScope(), answer);
if (probability >= acceptanceThreshold) {
return done(answer);
}
return call(tiers.get(++tier));

最後のティアは評価されません。その回答はいずれにせよ返されます。より正確には、サブエージェントのアクティベーション条件に照らして後続のアクティブなティアがない場合は常に、そのティアの回答は評価されずに返され、決定の呼び出しが 1 回節約されます。また、呼び出し時にスキップされたティアは、評価なしで通り過ぎられます。残りのティアがすべてスキップされた場合、カスケードは最後に得た回答を返します。

プランナーは、試行中のティアを実行状態として保存するため、たとえばティアが人間を待っているために一時停止した後や、クラッシュ後に、カスケードはより安価なティアに再度コストをかけることなく、そのティアから再開します。人間はカスケードの途中のティアになることもでき、その場合、カスケードが再開されたときにその回答は他の回答と同様に評価されます。このため、回答が遅延し得るティア、つまりヒューマン・イン・ザ・ループと非同期エージェントは、プランナーがその回答を読み取る出力キーを宣言する必要があります。

実用的な例として、コーヒーマシンのサポートアシスタントを考えてみましょう。最初のティアは、小さなモデルで動作し、製品に関する質問に限定された、安価な FAQ エージェントです。

public interface FaqAgent {

@UserMessage("""
You are the FAQ assistant of the Brewmaster 3000 coffee machine.
Answer the following user request in no more than 3 sentences, using only your knowledge of the
Brewmaster 3000 coffee machine: how to set it up, brew coffee, clean and descale it, and fix its common issues.
If the request is not about the Brewmaster 3000 coffee machine, answer exactly:
"I can only help with the Brewmaster 3000 coffee machine."
The user request is {{request}}.
""")
@Agent(description = "Answers frequently asked questions about the Brewmaster 3000 coffee machine",
outputKey = "faqAnswer")
String faq(@V("request") String request);
}

2 番目のティアは、大きなモデルで動作し、あらゆるリクエストに回答できる ExpertAgent です。

public interface ExpertAgent {

@UserMessage("""
You are an expert assistant able to answer any question.
Provide the best possible answer to the following user request in no more than 3 sentences.
The user request is {{request}}.
""")
@Agent(description = "An expert assistant answering any question", outputKey = "expertAnswer")
String expert(@V("request") String request);
}

SupportCascade インターフェースは、TypeSafe などの決定モデルで構成された ConfidenceCascadePlanner によって直接実装されます。

public interface SupportCascade {

@Agent
String ask(@V("request") String request);
}

FaqAgent faqAgent = AgenticServices.agentBuilder(FaqAgent.class)
.chatModel(SMALL_MODEL)
.build();
ExpertAgent expertAgent = AgenticServices.agentBuilder(ExpertAgent.class)
.chatModel(LARGE_MODEL)
.build();

DecisionModel decisionModel = TypeSafeDecisionModel.builder()
.apiKey(System.getenv("TYPESAFE_API_KEY"))
.modelName("jev-1.13.0")
.build();

SupportCascade supportCascade = AgenticServices.plannerBuilder(SupportCascade.class)
.subAgents(faqAgent, expertAgent)
.outputKey("answer")
.planner(() -> new ConfidenceCascadePlanner(decisionModel, 0.5))
.build();

String answer = supportCascade.ask("How do I descale my Brewmaster 3000 coffee machine?");

ここでは FaqAgent がリクエストに回答し、次に決定モデルが入力 {"request": "How do I descale my Brewmaster 3000 coffee machine?", "candidateAnswer": "..."} と質問「回答はリクエストに完全かつ正確に対応していますか?」を受け取ります。「yes」の確率は高いため、FAQ エージェントの回答が返され、ExpertAgent は呼び出されません。一方、「ルーターを 2 台使って家庭内ネットワークを構築するには?」のようなリクエストでは、FAQ エージェントはコーヒーマシンにしか対応できないと答え、確率は低くなり、リクエストは ExpertAgent にエスカレーションされます。これは最後のティアなので、その回答は評価されずに返されます。

受け入れ基準を使うと、デフォルトの質問だけの場合よりも評価を厳しくしたり、アプリケーションに特化したものにしたりできます。

new ConfidenceCascadePlanner(decisionModel, 0.5,
"The answer gives concrete instructions that solve the user's problem, " +
"instead of saying that it cannot help or redirecting the user elsewhere")

いくつか留意すべき点があります。カスケードがコストと時間を節約できるのは、ほとんどのリクエストが安価なティアで受け入れられる場合だけです。エスカレーションされたリクエストは、通過したすべてのティアに加えて、評価された回答ごとに 1 回の決定呼び出しのコストを負担し、これらの呼び出しは順番に実行されます。評価は関連性と完全性のシグナルであって、正確性の証明ではありません。決定モデルは回答がリクエストに対応しているかどうかは判断できますが、事実を検証することはできないため、カスケードは安価なチェックで良い回答と悪い回答を見分けられるケースに適しています。同じ理由で、安価なティアは、そのモデルがたまたま知っていることから回答するのではなく、たとえば RAG などで根拠づけられているべきです。決定モデルが見られるのはカスケードエージェントの引数とティアの回答だけで、チャットメモリやティアの指示は見えないため、引数には回答を評価するために必要なすべてを含める必要があります。リクエストと回答はどちらも信頼できない入力であるため、巧妙に作られたリクエストや回答が評価に影響を与える可能性があります。カスケードはコストと品質のトレードオフであり、セキュリティやレビューの境界ではないため、常により高性能なティアや人間に到達しなければならないステップは、たとえばアクティベーション条件を通じて、独自にそれを強制する必要があります。確率の較正の仕方は決定モデルによって異なるため、受け入れしきい値は自分のリクエストで調整し、決定モデルやそのバージョンを変更した際にも再調整する必要があります。決定ルーターと同様に、カスケードエージェントの引数はそのまま決定モデルに送信されるため、文字列、数値、ブール値、またはそれらのマップやリスト、あるいは画像などの Content にできます。それ以外の型の引数は、サポートされる型を説明するエラーとともに決定モデルによって拒否されます。これにより、決定モデルのプロバイダーに何を送るかは利用者が選択でき、それは各ティアのチャットモデルのプロバイダーとは異なっていても構いません。ティアの回答は、そのような値であればそのまま送信され、そうでなければ JSON のラウンドトリップを通じてマップとリストに変換されるため、ティアは型付きの値を返せます。決定モデルの失敗は、カスケードの呼び出しを失敗させます。最後に、実行状態は評価の後にのみ保存されるため、評価の呼び出し自体の最中にクラッシュすると、カスケードの再開時に評価中だったティアが再び実行されます。また、実行状態はティアを位置で参照しているため、一時停止後にサブエージェントが変更されたカスケードは再開できず、IllegalStateException で失敗します。

非AIエージェント​

これまで説明したすべてのエージェントは AI エージェントです。つまり、LLM に基づいており、自然言語の理解と生成を必要とするタスクを実行するために呼び出すことができます。ただし、langchain4j-agentic モジュールは非 AI エージェントもサポートしており、REST API の呼び出しやコマンドの実行など、自然言語処理を必要としないタスクの実行に使用できます。これらの非 AI エージェントは確かにツールに似ていますが、この文脈では、AI エージェントと同じように使用したり、AI エージェントと混合してより強力で完全なエージェント システムを構成したりできるように、エージェントとしてモデル化するのが便利です。

たとえば、スーパーバイザーの例で使用されている ExchangeAgent は、おそらく AI エージェントとして不適切にモデル化されており、単に REST API を呼び出して為替を実行する非 AI エージェントとして定義する方が適切かもしれません。

public class ExchangeOperator {

@Agent(value = "A money exchanger that converts a given amount of money from the original to the target currency",
outputKey = "exchange")
public Double exchange(@V("originalCurrency") String originalCurrency, @V("amount") Double amount, @V("targetCurrency") String targetCurrency) {
// invoke the REST API to perform the currency exchange
}
}

これにより、スーパーバイザーに提供される他のサブエージェントと同じように使用できます。このようにインスタンスとして渡されるエージェントは、それ自体がヘルパーオブジェクトでもあります。その @ActivationCondition と @AgentListenerSupplier はインスタンスメソッドにでき、そのエージェントメソッドのパラメーターは SupplierParameterResolver を通じて解決できます。

WithdrawAgent withdrawAgent = AgenticServices
.agentBuilder(WithdrawAgent.class)
.chatModel(BASE_MODEL)
.tools(bankTool)
.build();
CreditAgent creditAgent = AgenticServices
.agentBuilder(CreditAgent.class)
.chatModel(BASE_MODEL)
.tools(bankTool)
.build();

SupervisorAgent bankSupervisor = AgenticServices
.supervisorBuilder()
.chatModel(PLANNER_MODEL)
.subAgents(withdrawAgent, creditAgent, new ExchangeOperator())
.build();

基本的に、langchain4j-agentic のエージェントは、@Agent アノテーションが付けられたメソッドを 1 つだけ持つ任意の Java クラスにすることができます。

専用クラスを定義するのが現実的でない場合、たとえばエージェントのロジックが実行時にしか分からない場合は、同じ非 AI エージェントをプログラムで作成することもできます。AgenticServices の nonAiAgentBuilder ファクトリメソッドは、エージェントの結果を計算する AgenticScope の関数を受け取り、本来は @Agent アノテーションとメソッドのパラメーターで定義される名前、説明、型付き入力キー、出力キーを設定できます。この方法で、上記の ExchangeOperator は次のように等価に定義できます。

AgenticScopeFunction<Double> exchangeOperator = AgenticServices
.nonAiAgentBuilder(agenticScope -> exchange(
agenticScope.readState("originalCurrency", ""),
agenticScope.readState("amount", 0.0),
agenticScope.readState("targetCurrency", "")))
.name("exchange")
.description("A money exchanger that converts a given amount of money from the original to the target currency")
.inputKeys(String.class, "originalCurrency", Double.class, "amount", String.class, "targetCurrency")
.outputKey("exchange")
.build();

そして、new ExchangeOperator() インスタンスの代わりにスーパーバイザーに渡します。関数を呼び出す前に、宣言された入力が AgenticScope から読み取られ、宣言された型に変換されるため、たとえばスーパーバイザーが整数または文字列として生成した amount を Double として安全に読み取れます。一方、入力が欠けていると呼び出しは MissingArgumentException で失敗します。このビルダーでは、出力キーとしての TypedKey、エージェントの結果の outputType(関数のジェネリック型は実行時には利用できないため、デフォルトは Object)、エージェントを async で実行するかどうか、およびその呼び出し用の AgentListener も設定できます。名前が指定されない場合、エージェントには、関数をラップする AgenticScopeFunction のメソッドにちなんで accept という名前が付けられます。

最後に、非 AI エージェントも、AgenticScope の状態を読んだり、小さな操作を実行したりするのに役立ちます。このため、AgenticServices は、Consumer<AgenticServices> から単純なエージェントを作成するための agentAction ファクトリ メソッドを提供します。たとえば、score を String 値として生成する scorer エージェントと、その score を double として消費する必要がある後続の reviewer エージェントがあるとします。この場合、2 つのエージェントには互換性がありませんが、agentAction を使用して、AgenticScope の score 状態を次のように書き換えることで、最初のエージェントの出力を 2 番目のエージェントが必要とする形式に適合させることができます。

UntypedAgent editor = AgenticServices.sequenceBuilder()
.subAgents(
scorer,
AgenticServices.agentAction(agenticScope -> agenticScope.writeState("score", Double.parseDouble(agenticScope.readState("score", "0.0")))),
reviewer)
.build();

ヒューマン・イン・ザ・ループ​

エージェント システムを構築する際のもう 1 つの一般的なニーズは、人間が関与することで、システムが特定のアクションを続行する前に不足している情報の入力や承認をユーザーに求めることができるようにすることです。この人間参加型機能は、特別な非 AI エージェントと見なすこともできるため、そのように実装されます。

public record HumanInTheLoop(Function<AgenticScope, ?> responseProvider) {

@Agent("An agent that asks the user for missing information")
public Object askUser(AgenticScope scope) {
return responseProvider.apply(scope);
}
}

この実装はかなり素朴ですが非常に汎用的で、現在の AgenticScope を入力として受け取る単一の関数に基づいています。そこから適切な質問をするためのコンテキストを抽出でき、ユーザーに提供すべきレスポンスを返します。インスタンスとして渡されるすべてのエージェントと同様に、このようなオブジェクトもそれ自体がヘルパーオブジェクトです。

langchain4j-agentic モジュールによってすぐに提供される HumanInTheLoop エージェントを使用すると、この関数をエージェントの説明、およびユーザーの応答が書き込まれる出力変数とともに定義できます。

たとえば、次のように AstrologyAgent を定義するとします。

public interface AstrologyAgent {
@SystemMessage("""
You are an astrologist that generates horoscopes based on the user's name and zodiac sign.
""")
@UserMessage("""
Generate the horoscope for {{name}} who is a {{sign}}.
""")
@Agent("An astrologist that generates horoscopes based on the user's name and zodiac sign.")
String horoscope(@V("name") String name, @V("sign") String sign);
}

次のように、この AI エージェントと HumanInTheLoop エージェントの両方を使用して、ホロスコープを生成する前にユーザーに星座を尋ね、その質問をコンソールの標準出力に送信し、標準入力からユーザーの応答を読み取るシーケンス ワークフローを作成することができます。

HumanInTheLoop humanInTheLoop = AgenticServices.humanInTheLoopBuilder()
.description("An agent that asks the zodiac sign of the user")
.outputKey("sign")
.responseProvider(scope -> {
System.out.println("Hi " + scope.readState("name") + ", what is your sign?");
System.out.print("> ");
try {
BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
return reader.readLine();
} catch (IOException e) {
throw new RuntimeException("Failed to read input", e);
}
})
.build();

AstrologyAgent astrologyAgent = AgenticServices.agentBuilder(AstrologyAgent.class)
.chatModel(baseModel())
.outputKey("horoscope")
.build();

UntypedAgent horoscopeAgent = AgenticServices.sequenceBuilder()
.subAgents(humanInTheLoop, astrologyAgent)
.outputKey("horoscope")
.build();

このようにして、ユーザーが次のようなリクエストで horoscopeAgent を呼び出した場合、

horoscopeAgent.invoke(Map.of("name", "Mario"));

このシーケンスは、まず HumanInTheLoop エージェントを呼び出してユーザーに不足している星座を尋ね、次の出力を生成します。

Hi Mario, what is your sign?
>

ユーザーが回答を提供するのを待ちます。回答は AstrologyAgent を呼び出してホロスコープを生成するために使用されます。

ユーザーが回答を提供するまでに時間がかかる場合があるため、HumanInTheLoop エージェントを非同期エージェントとして構成することが可能であり、実際に推奨されています。このようにして、ユーザーの入力を必要としないエージェントは、エージェント システムがユーザーの回答を待っている間に実行を続行できます。

決定エージェント​

备注

決定エージェントは実験的な DecisionModel API に基づいており、将来のリリースで変更される可能性があります。

エージェント型システムがモデルに求めるのは、テキストの生成ではなく、小さな判断を下すことである場合があります。たとえば、このリクエストはどのカテゴリに属するか、この回答は十分に良いか、この取引は疑わしく見えるか、この顧客は資格を満たしているか、といったものです。これまでに説明したエージェントは、これらの判断を LLM で行います。たとえば、ちょうど 1 語で答えるよう指示する必要がある条件付きワークフローの CategoryRouter や、数値をテキストとして生成するループワークフローの StyleScorer です。決定モデルは、まさにこうした質問のために作られています。入力に関する型付きの質問に答え、可能な各回答の確率を返し、そのコストは LLM 呼び出しのごく一部です。

決定エージェントは、決定モデルへの単一の呼び出しとして実装される、エージェント型システムのエージェントです。メソッドに @Agent アノテーションも付いた Decision Service インターフェースで定義されます。質問は @Decide のもので、メソッドのパラメーターが判断の入力となり、その戻り値の型が回答の種類を決定します。

public enum RequestCategory {
@Description("Questions about laws, contracts, liabilities and legal rights") LEGAL,
@Description("Questions about symptoms, diseases, treatments and drugs") MEDICAL,
@Description("Questions about software, hardware, networks and devices") TECHNICAL,
@Description("Requests that belong to none of the other categories") UNKNOWN
}

public interface CategoryRouter {

@Decide("Which kind of expert should handle this request?")
@Agent(value = "Categorizes a user request", outputKey = "category")
RequestCategory classify(@V("request") String request);
}

条件付きワークフローの LLM ベースの CategoryRouter と比べると、プロンプトを設計する必要も、テキストを解析する必要もありません。選択肢は列挙型の定数で、その @Description で記述され、決定モデルがそのうちの 1 つを返します。このエージェントは、チャットモデルの代わりに決定モデルを指定して、AgenticServices の decisionAgentBuilder メソッドで構築されます。

CategoryRouter routerAgent = AgenticServices
.decisionAgentBuilder(CategoryRouter.class)
.decisionModel(decisionModel)
.build();

同じ category キーに回答を書き込むため、他の変更なしに、条件付きワークフローの LLM ベースのルーターの代わりに使用できます。ビルダーの decisionModelProvider メソッドは、AI エージェントの chatModel(Function) と同様に、各呼び出しの前に決定モデルを解決する AgenticScope の関数を受け取ります。name、description、outputKey、async、optional、activationCondition、listener は、他のエージェントのビルダーと同じ意味を持ちます。

2 つの決定ベースのパターンも決定モデルを使用しますが、それはオーケストレーションの内部で使われます。決定ルーターはどのサブエージェントを実行するかを選択し、信頼度カスケードはエスカレーションをいつ止めるかを決定します。判断がパターンのオーケストレーションを駆動する場合はそのどちらかを使い、判断がコードや他のエージェントが利用する値である場合は決定エージェントを使います。たとえば、述語がルーティングの基準とするカテゴリ、終了条件が比較するスコア、副作用を制御するフラグ、スーパーバイザーが次のステップの前に必要とする回答などです。

戻り値の型としきい値​

戻り値の型は Decision Service のものと同じです。はい/いいえの質問には boolean または YesNoAnswer、列挙型の定数から選ぶ場合は列挙型または Choice<enum>、その定数で構成される順序尺度上の位置には Scale<enum>、1 回の呼び出しで複数の質問に答える場合はこれらの型のフィールドを持つオブジェクトまたはレコードを使います。これらはそれぞれ、モデルの生のレスポンスも取得するために DecisionResult でラップすることもできます。CompletableFuture の戻り値の型はサポートされません。ワークフローをブロックしてはならないエージェントは、他のエージェントと同様に async(true) で非同期にし、その決定呼び出しは、すべての非同期エージェントが使用するエグゼキューター上で実行されます。決定エージェントにはプロンプトがないため、メソッドに @UserMessage や @SystemMessage を付けてはならず、そのパラメーターを @MemoryId、AgenticScope、DecisionRequestParameters にすることもできません。モデル名などの決定リクエストのパラメーターは、ビルダーの requestParameters メソッドで、または決定モデルのデフォルトパラメーターとして設定します。これらの規則はすべて、エージェントの構築時に検証されます。

boolean の回答は、「yes」の確率がしきい値(デフォルトは 0.5)以上のとき true になります。しきい値は threshold(double) で固定するか、thresholdProvider(...) で設定した ThresholdProvider によって呼び出しのたびに提供できます。たとえば、実行時に変更される設定から読み取る場合です。決定ベースのパターンで説明したように、確率の較正の仕方は決定モデルによって異なるため、しきい値は自分の入力で調整し、決定モデルやそのバージョンが変わった際にも再調整する必要があります。しきい値は boolean の回答にのみ適用されるため、boolean の回答を持たないエージェントにしきい値またはプロバイダーを設定すると、エージェントの構築時に失敗します。YesNoAnswer、Choice、Scale には、しきい値を適用するための確率が含まれています。

入力​

決定エージェントの引数は、他のすべてのエージェントと同様に、名前で AgenticScope から読み取られ、パラメーターの宣言された型に変換されるため、前のエージェントやスーパーバイザーがテキストとして生成した金額は Double として安全に読み取れます。その後、Decision Service が送信するのと同じ方法で決定モデルに送信されます。文字列、数値、ブール値はそのまま、列挙型はその名前、マップとリストは要素ごと、ImageContent などの Content はコンテンツとして送信されるため、決定エージェントは前のステップで生成された画像を判断することもできます。それ以外のオブジェクトは JSON コーデックでマップに変換されるため、他のエージェントが生成した型付きの値を引数にできます。決定モデルに届くものはすべてそのプロバイダーに送信されることに留意してください。これは他のエージェントのチャットモデルのプロバイダーと異なる場合があります。

回答の読み取り​

回答はそのまま出力キーに書き込まれるため、Choice、Scale、YesNoAnswer はその確率を保持し、条件付きワークフローの述語、ループの終了条件、後続のエージェントがそれらを読み取れます。たとえば、Choice<RequestCategory> を返すルーターを使うと、条件付きワークフローは、決定モデルが確信を持てないリクエストを人間に送れます。

public interface ConfidentCategoryRouter {

@Decide("Which kind of expert should handle this request?")
@Agent(value = "Categorizes a user request", outputKey = "category")
Choice<RequestCategory> classify(@V("request") String request);
}

private static boolean confident(AgenticScope scope, RequestCategory category) {
Choice<RequestCategory> choice = (Choice<RequestCategory>) scope.readState("category");
return choice.value() == category && choice.probabilities().getOrDefault(category, 0.0) >= 0.6;
}

UntypedAgent expertsAgent = AgenticServices.conditionalBuilder()
.subAgents(scope -> confident(scope, RequestCategory.MEDICAL), medicalExpert)
.subAgents(scope -> confident(scope, RequestCategory.LEGAL), legalExpert)
.subAgents(scope -> !confident(scope, RequestCategory.MEDICAL) && !confident(scope, RequestCategory.LEGAL), humanInTheLoop)
.build();

同様に、ループワークフローの StyleScorer は Scale を返す決定エージェントにできます。その mean() は、各レベルのインデックスの確率加重平均で、Quality では列挙型の最初の定数の 0 から最後の定数の 3 までの値を取ります。そのため、平均が 2 以上であれば、物語は平均して少なくとも GOOD であることを意味します。これは、テキストとして生成された数値ではなく、決定モデルの確率から得られるスコアです。

public enum Quality {
@Description("The story ignores the required style") POOR,
@Description("The story follows the required style only in places") FAIR,
@Description("The story mostly follows the required style") GOOD,
@Description("The story is a perfect example of the required style") EXCELLENT
}

public interface StyleScorer {

@Decide("How well does the story match the required style?")
@Agent(value = "Scores a story against a style", outputKey = "styleScore")
Scale<Quality> scoreStyle(@V("story") String story, @V("style") String style);
}

UntypedAgent styleReviewLoop = AgenticServices.loopBuilder()
.subAgents(styleScorer, styleEditor)
.maxIterations(5)
.exitCondition(scope -> ((Scale<Quality>) scope.readState("styleScore")).mean() >= 2)
.build();

3 つ目の典型的な使い方は、副作用の前のゲートです。ここでは、はい/いいえの決定エージェントが LLM の決めた送金を確認し、疑わしいものはゲートがそう判断したときにのみアクティブ化される HumanInTheLoop エージェントを通じて人間が承認し、非 AI エージェントがそれを実行します。これにより、LLM が決定し、決定モデルが確認し、決定論的なコードが実行します。

public interface TransactionGate {

@Decide("""
Does this money transfer look suspicious?
Yes: an unusually large amount, an unknown or foreign beneficiary, an urgent or unusual justification.
No: a routine payment to a known beneficiary.""")
@Agent(value = "Checks whether a money transfer looks suspicious", outputKey = "suspicious")
boolean check(@V("transfer") String transfer);
}

TransactionGate gate = AgenticServices.decisionAgentBuilder(TransactionGate.class)
.decisionModel(decisionModel)
.threshold(0.5)
.build();

HumanInTheLoop complianceApproval = AgenticServices.humanInTheLoopBuilder()
.description("Compliance approval of a suspicious transfer")
.outputKey("approval")
.responseProvider(scope -> new SuspendedResponse<>("compliance-approval"))
.activationCondition("the transfer looks suspicious", scope -> scope.readState("suspicious", true))
.build();

UntypedAgent transfers = AgenticServices.sequenceBuilder()
.subAgents(gate, complianceApproval, moneyMover)
.outputKey("receipt")
.build();

レコードの回答は出力キーの下の単一の値です。複数の @Decide フィールドを持つレコードは 1 回の呼び出しで複数の質問に答え、そのフィールドを別々のキーの下で必要とする場合は、条件付きワークフローで示したように、後続のエージェントの beforeCall または agentAction がそれらを展開します。決定エージェントはスーパーバイザーのサブエージェントの 1 つにもでき、その場合は他のサブエージェントと同様に引数が生成され、型付きの回答が読み取られます。このとき、その説明にはエージェントがどの質問に答えるかを記述する必要があります。

エラー、可観測性、永続化​

決定モデルの失敗、無効なレスポンス、拒否は、チャットモデルの失敗が AI エージェントを失敗させるのと同様に、エージェントの呼び出しを失敗させます。出力キーには何も書き込まれず、エージェント型システムのエラーハンドラーが、再試行するか、代替の結果を返すか、失敗させるかを決定します。拒否は、Decision Service と同様に ContentFilteredException として報告されます。

決定エージェントの呼び出しごとに、決定モデルへのブロッキング呼び出しが 1 回行われます。回答とその確率、モデル名、トークン使用量を含むそのレスポンスは、AI エージェントが報告するチャットリクエストおよびレスポンスと並んで、AgentResponse の decisionResponse() メソッドを通じてリスナーに報告され、AgentMonitor によって記録されます。AgentInvocation の decisionResponse()、tokenUsage()、modelName() メソッドがそれを返すため、決定エージェントのトークンは LLM 呼び出しのトークンと同様にモニタリングレポートに計上され、HTML レポートでは決定エージェントが「Decision」バッジとともに表示され、その出力のツールチップに回答と確率が表示されます。決定エージェントにはチャットメモリ、ツール、検索、ガードレール、ストリーミングはありません。質問に答えるものであり、会話するものではありません。

決定エージェントの回答は、回復可能性のセクションで説明した AgenticScope の JSON シリアライズでも保持されます。YesNoAnswer、Choice、Scale の値は、スコープの保存時に永続化可能な形式に変換され、読み込み時に復元されます。一方、DecisionResult は TokenStream と同様に永続化されず、これら 3 つの型のフィールドで複数の質問に答えるレコードやオブジェクトも、そのフィールドをその場で変換できないため永続化されません。したがって、回復可能なシステムは DecisionResult を返すべきではなく、複数の質問に答えるレコードは boolean と列挙型のフィールドを持つべきです。

宣言型の決定エージェント​

宣言型 API では、決定モデルは @DecisionModelSupplier をアノテートした静的メソッドで提供されます。パラメーターがない場合、メソッドはエージェントの構築時に 1 回呼び出されます。@V をアノテートしたパラメーターがある場合は、AgenticScope から読み取った値で呼び出しのたびに呼び出されるため、@ChatModelSupplier が AI エージェントに対して行うように、モデルを状態に依存させられます。boolean の回答のしきい値は、質問を記述する ThresholdContext を受け取り double を返す静的メソッドに @DecisionThresholdSupplier を付けて宣言します。ThresholdProvider と同様に呼び出しのたびに実行されるため、しきい値は実行時に変更される設定から取得できます。@ActivationCondition と @AgentListenerSupplier は他のエージェントと同じように動作します。これらのアノテーションを使うと、上で示したゲートの TransactionGate は次のように宣言されます。

public interface TransactionGate {

@Decide("""
Does this money transfer look suspicious?
Yes: an unusually large amount, an unknown or foreign beneficiary, an urgent or unusual justification.
No: a routine payment to a known beneficiary.""")
@Agent(value = "Checks whether a money transfer looks suspicious", outputKey = "suspicious")
boolean check(@V("transfer") String transfer);

@DecisionModelSupplier
static DecisionModel decisionModel() {
return TypeSafeDecisionModel.builder()
.apiKey(System.getenv("TYPESAFE_API_KEY"))
.modelName("jev-1.13.0")
.build();
}

@DecisionThresholdSupplier
static double threshold(ThresholdContext context) {
// thresholds are specific to a model, so the one tuned for the model that answered is read,
// at every invocation, from a system property like suspicious.threshold.jev-1.13.0
return Double.parseDouble(System.getProperty("suspicious.threshold." + context.modelName(), "0.5"));
}
}

インターフェースは、その @Agent メソッドに @Decide がアノテートされているか、@DecisionModelSupplier を宣言している場合に、決定エージェントとして認識されます。そのため、レコード(質問はレコードのフィールドにあります)を返すエージェントは、認識されるためにサプライヤーが必要です。このようなインターフェースは、宣言型のワークフロー、プランナー、スーパーバイザーの subAgents に列挙したり、プログラム的なビルダーの subAgents にクラスとして渡したり、createAgenticSystem に直接渡したりできます。createAgenticSystem に渡される ChatModel は決定エージェントには適用されないため、@DecisionModelSupplier のない決定エージェントは、その旨のメッセージとともに構築時に失敗します。@ChatModelSupplier も宣言している決定エージェントや、@DecisionModelSupplier または @DecisionThresholdSupplier を宣言している他の種類のエージェント(AI エージェント、ワークフロー、非 AI エージェントなど)も同様に失敗します。AgentConfigurator のコールバックは、作成コンテキストの decisionAgentBuilder() メソッドを通じて決定エージェントの DecisionAgentBuilder を受け取り、その場合 agentBuilder() は null です。

メモリとコンテキストエンジニアリング​

これまで説明したすべてのエージェントはステートレスです。これは、エージェントが以前の対話のコンテキストや記憶を保持しないことを意味します。ただし、他の AI サービスと同様に、エージェントに ChatMemory を提供して、エージェントが複数の呼び出しにわたってコンテキストを維持できるようにすることができます。

以前の MedicalExpert にメモリを提供するには、@MemoryId の注釈が付けられたフィールドをその署名に追加するだけで十分です。

public interface MedicalExpertWithMemory {

@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 {{request}}.
""")
@Agent("A medical expert")
String medical(@MemoryId String memoryId, @V("request") String request);
}

そして、エージェントを構築するときにメモリプロバイダーを設定します。

MedicalExpertWithMemory medicalExpert = AgenticServices
.agentBuilder(MedicalExpertWithMemory.class)
.chatModel(BASE_MODEL)
.chatMemoryProvider(memoryId -> MessageWindowChatMemory.withMaxMessages(10))
.outputKey("response")
.build();

一般に、単一のエージェントを単独で使用する場合はこれで十分ですが、エージェント システムに参加するエージェントの場合は制限となる可能性があります。技術専門家と法律専門家にもメモリが提供され、ExpertRouterAgent もそれを持つように再定義されていると仮定します。

public interface ExpertRouterAgentWithMemory {

@Agent
String ask(@MemoryId String memoryId, @V("request") String request);
}

このエージェントに対するこれら 2 つの呼び出しのシーケンス

String response1 = expertRouterAgent.ask("1", "I broke my leg, what should I do?");

String legalResponse1 = expertRouterAgent.ask("1", "Should I sue my neighbor who caused this damage?");

2 番目の質問は法律専門家に送られるため、期待どおりの結果は得られません。法律専門家は初めて呼び出され、前の質問の記憶がありません。

この問題を解決するには、法律の専門家にコンテキストとその発動前に何が起こったのかを提供する必要があります。これは、AgenticScope に自動的に保存される情報が役立つもう 1 つのユースケースです。

特に、AgenticScope はすべてのエージェントの呼び出しのシーケンスを追跡し、それらの呼び出しを 1 つの会話に連結したコンテキストを生成できます。このコンテキストはそのまま使用することも、必要に応じて、たとえば ContextSummarizer エージェントを定義するなど、短いバージョンに要約して使用することもできます。

public interface ContextSummarizer {

@UserMessage("""
Create a very short summary, 2 sentences at most, of the
following conversation between an AI agent and a user.

The user conversation is: '{{it}}'.
""")
String summarize(String conversation);
}

このエージェントを使用すると、法律専門家を再定義して、以前の会話のコンテキストの要約を提供できるため、新しい質問に答えるときに以前のやり取りを考慮に入れることができます。

LegalExpertWithMemory legalExpert = AgenticServices
.agentBuilder(LegalExpertWithMemory.class)
.chatModel(BASE_MODEL)
.chatMemoryProvider(memoryId -> MessageWindowChatMemory.withMaxMessages(10))
.context(agenticScope -> contextSummarizer.summarize(agenticScope.contextAsConversation()))
.outputKey("response")
.build();

より一般的には、エージェントに提供されるコンテキストは、AgenticScope 状態の任意の関数にすることができます。この設定により、法律専門家は、隣人が引き起こした損害について訴訟を起こすべきかどうか尋ねられたときに、医療専門家との以前の会話を考慮に入れて、より多くの情報に基づいた回答を提供することができます。

内部的には、エージェント フレームワークは、送信されたユーザー メッセージを自動的に書き換えることにより、法律専門家に追加のコンテキストを提供します。これにより、以前の会話の要約されたコンテキストが含まれるため、この場合、実際のユーザー メッセージは次のようになります。

"Considering this context \"The user asked about what to do after breaking their leg, and the AI provided medical advice on immediate actions like immobilizing the leg, applying ice, and seeking medical attention.\"
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 Should I sue my neighbor who caused this damage?."

エージェントで可能なコンテキスト生成の例としてここで説明した要約コンテキストは一般的に役立つため、次のように summarizedContext メソッドを使用して、より便利な方法でエージェント上でコンテキストを定義できます。

LegalExpertWithMemory legalExpert = AgenticServices
.agentBuilder(LegalExpertWithMemory.class)
.chatModel(BASE_MODEL)
.chatMemoryProvider(memoryId -> MessageWindowChatMemory.withMaxMessages(10))
.summarizedContext("medical", "technical")
.outputKey("response")
.build();

この場合、内部的には、前述の ContextSummarizer エージェントのものと同様の要約プロンプトを、それが定義されているエージェントと同じモデルに送信します。これは StreamingChatModel で構成されたエージェントでも動作します。その場合、要約はそのストリーミングモデルで生成されますが、エージェントが自身のリクエストを送信する前に完全に収集されます。どちらの場合も、要約はエージェントが回答を始める前に行われる、追加のブロッキング LLM 呼び出しです。このメソッドに、コンテキストを要約すべきエージェントの名前を可変長引数で追加することもできます。そうすると、エージェント型システムで使用されるすべてのエージェントではなく、それらのエージェントのみが要約されます。

AgenticScope レジストリと永続性​

AgenticScope は、エージェント システムの実行中に作成および使用される一時的なデータ構造です。エージェント システムごとにユーザーごとに 1 つの AgenticScope があります。ステートレス実行の場合、メモリが使用されていない場合、AgenticScope は実行の終了時に自動的に破棄され、その状態はどこにも保持されません。

逆に、エージェント型システムがメモリを使用する場合、AgenticScope は内部レジストリに保存されます。この場合、ユーザーがエージェント型システムとステートフルで会話的にやり取りできるよう、AgenticScope は永久にレジストリに残ります。そのため、特定の ID を持つ AgenticScope が不要になったときは、レジストリから明示的に削除する必要があります。そのためには、エージェント型システムのルートエージェントが AgenticScopeAccess インターフェースを実装する必要があります。これにより、そのエージェントに対して evictAgenticScope メソッドを呼び出し、エージェントのチャットメモリオブジェクトとともにレジストリから削除すべき AgenticScope の ID を渡せます。また、保存されたメッセージも削除するには deleteAgenticScope を呼び出します。

agent.evictAgenticScope(memoryId);

evictAgenticScope は、レジストリから AgenticScope を削除し、システムのエージェントがその ID に対して保持しているチャットメモリオブジェクトを破棄します。これは AI サービスの ChatMemoryAccess.evictChatMemory と同じ意味で、保存されたメッセージは ChatMemoryStore に残ります。MessageWindowChatMemory.withMaxMessages(10) のように独自のストアを持たないチャットメモリは、メッセージをオブジェクト内に保持するため、メッセージはそのオブジェクトとともに失われます。会話も削除する必要がある場合は、代わりに deleteAgenticScope(memoryId) を呼び出します。これは、それらのチャットメモリをクリアしてストアからメッセージを削除してから、削除します。どちらのメソッドも、その ID のために、この JVM で作成されたチャットメモリにのみ作用します。別のノードによって、または再起動前に保存されたメッセージは、ストアを通じて削除する必要があります。

AgenticScope とそのレジストリはどちらも純粋にメモリ データ構造内にあります。通常、単純なエージェント システムにはこれで十分ですが、場合によっては、AgenticScope 状態をデータベースやファイル システムなどのより耐久性のあるストレージに保持すると便利な場合があります。これを実現するために、langchain4j-agentic モジュールは、AgenticScopeStore インターフェイスの実装であるカスタム永続層をプラグインするための SPI を提供します。この永続層はプログラム的に設定できます。

AgenticScopePersister.setStore(new MyAgenticScopeStore());

または、標準の Java サービス プロバイダー インターフェイスを使用して、AgenticScopeStore インターフェイスを実装するクラスの完全修飾名を含む META-INF/services/dev.langchain4j.agentic.scope.AgenticScopeStore という名前のファイルを作成します。

AgenticScope JSON シリアル化​

LangChain4j は、AgenticScopeSerializer クラスを介して AgenticScope の組み込み JSON シリアル化を提供します。セキュリティ上の理由から、逆シリアル化では、JSON から逆シリアル化できるクラスを制限する許可リスト ポリシーが使用されます。デフォルトでは、標準の JDK 型 (java.util.*、java.math.*、プリミティブ ラッパー、列挙型) と内部 LangChain4j 型 (AgentMessage、AgentInvocation) が許可されます。

エージェントがカスタム ドメイン オブジェクトを AgenticScope 状態で保存する場合、逆シリアル化が発生する前にそれらを登録する必要があります。単一のクラスを登録できます。

AgenticScopeSerializer.allowDeserializationType(LoanApplication.class);

またはパッケージのプレフィックス全体:

AgenticScopeSerializer.allowDeserializationPackagePrefix("com.acme.myapp.");

未登録の型を逆シリアル化しようとすると、UnserializableAgenticScopeException がスローされ、そのメッセージは拒否されたクラスを指定し、その登録方法を提案します。

AgenticScope とエージェント システムの回復可能性​

AgenticScopeStore が構成されている場合、langchain4j-agentic モジュールは組み込みの回復可能性サポートを提供し、エージェント システムがクラッシュまたはプロセスの再起動後に中断したところから実行を再開できるようにします。これは、プロセスが意図的に停止され、後で再起動される可能性がある人間参加型のステップを含む、長時間実行されるエージェント システムにとって特に有益です。

回復可能性は、ステップごとのチェックポイント と プランナー実行状態の永続性 という 2 つのメカニズムが連携して機能することに基づいています。

エージェントが呼び出されるたびに、現在の AgenticScope が構成されたストアに自動的にチェックポイントされます。これは、エージェントによって (writeState 経由で) 書き込まれたすべての中間状態が永続的に保持されることを意味します。さらに、実行ループはプランナの内部位置 (シーケンス内のどのエージェントに到達したかなど) を保存するため、回復時にワークフローが最初から再開するのではなく、正しいステップから再開されます。

Planner インターフェイスの実装は、オプションで次の 2 つの方法を通じてこのメカニズムに参加できます。

// Returns the planner's current internal state for persistence
default Map<String, Object> executionState() { return Map.of(); }

// Restores internal state from a previously saved map
default void restoreExecutionState(Map<String, Object> state) { }

たとえば、シーケンシャル プランナやループ プランナなどのステートフル プランナは、カーソル位置と反復カウンタを保存および復元するためにこれらのメソッドを実装します。ステートレス プランナー (ParallelPlanner や ConditionalPlanner など) は、デフォルトの no-op 実装を使用します。カスタム Planner 実装は、これらのメソッドをオーバーライドして、回復可能性に参加することもできます。また、実行ループは、プランナーの状態とともに自身の内部状態 (並列ブロックでどのエージェントが完了したかなど) も追跡するため、再開時に完了していないエージェントのみが再ディスパッチされます。

これがどのように機能するかを示す実際の例として、大量の注文を履行する前に人間がレビューする必要がある注文処理ワークフローを考えてみましょう。ワークフローには、注文を検証し、人間の承認を待ち、注文を発送するという 3 つのステップがあります。

public interface OrderWorkflow extends AgenticScopeAccess {
@Agent
String processOrder(@MemoryId String orderId, @V("order") String orderDetails);
}

@MemoryId アノテーションは必須です。これは、回復可能性に必要な永続スコープをアクティブ化します。ワークフローを 3 つのエージェントのシーケンスとして構築します。

// Step 1: Validate the order and write results to shared state
AgenticScopeAction validateOrder = AgenticServices.agentAction(scope -> {
String order = scope.readState("order", "");
scope.writeState("validated_order", "VALIDATED: " + order);
});

// Step 2: Pause for human approval using SuspendedResponse
HumanInTheLoop approvalGate = AgenticServices.humanInTheLoopBuilder()
.description("Wait for manager approval on large orders")
.outputKey("approval")
.responseProvider(scope -> new SuspendedResponse<>("manager-approval"))
.build();

// Step 3: Finalize based on the approval decision
AgenticScopeAction shipOrder = AgenticServices.agentAction(scope -> {
String validated = scope.readState("validated_order", "");
String approval = scope.readState("approval", "");
scope.writeState("result", "Order " + validated + " — " + approval);
});

OrderWorkflow workflow = AgenticServices.sequenceBuilder(OrderWorkflow.class)
.subAgents(validateOrder, approvalGate, shipOrder)
.outputKey("result")
.build();

このワークフローを実行すると、注文が検証され、HumanInTheLoop ステップに到達します。応答プロバイダーが SuspendedResponse を返すため、エージェント システムは呼び出しスレッドをブロックする代わりに、AgenticSystemSuspendedException をスローして実行を一時停止します。検証された注文データ、プランナーのカーソル位置 (ステップ 2 が完了)、および SuspendedResponse を含む全スコープがストア (構成されている場合) にチェックポイントされ、スレッドを解放するために AgenticSystemSuspendedException がスローされます。

try {
String result = workflow.processOrder("order-12345", "1000 widgets");
// Workflow completed normally
} catch (AgenticSystemSuspendedException e) {
// Workflow suspended — waiting for human input
AgenticScope scope = e.scope();
Set<String> pendingIds = scope.pendingResponseIds(); // → ["manager-approval"]
// Store the scope/pendingIds for your UI / REST API to present to the human
}

SuspendedResponse の代わりに、人間参加者は PendingResponse クラスのインスタンスを返し、人間の応答が提供されるまで呼び出しスレッドをブロックできます。本質的には:

応答タイプ行動
SuspendedResponseエージェント システムを 一時停止します。スコープにチェックポイントを設定し、AgenticSystemSuspendedException をスローし、呼び出しスレッドを解放します。システムは、応答を完了し、エージェント メソッドを再度呼び出すことによって再開されます。
PendingResponsecomplete() が別のスレッドから呼び出されるまで、基になる CompletableFuture の呼び出しスレッドを ブロックします。例外はスローされません。エージェント システムは所定の位置で待機します。

ユーザーは、応答が作成される時点 (responseProvider ラムダまたは @HumanInTheLoop 静的メソッド) でこの選択を行うことができます。

// Suspension: the agentic system checkpoints and throws AgenticSystemSuspendedException
.responseProvider(scope -> new SuspendedResponse<>("approval-id"))

// Blocking: the calling thread waits until complete() is called from another thread
.responseProvider(scope -> new PendingResponse<>("approval-id"))

クラッシュ耐性が重要な長時間実行のインタラクション (数時間/日) には SuspendedResponse を使用し、バックグラウンド スレッドがすぐに答えを提供する短期間のインプロセス待機には PendingResponse を使用することをお勧めします。

メソッドの戻り値の型が ResultWithAgenticScope の場合、中断時に例外はスローされません。代わりに、結果には suspended() == true と result() == null が含まれます。その後、保留中の応答を完了し、1 回の呼び出しで実行を再開できます。

ResultWithAgenticScope<String> result = workflow.processOrder("order-12345", "1000 widgets");
if (result.suspended()) {
result = result.completePendingResponse("APPROVED by manager");
// result.result() → "Order VALIDATED: 1000 widgets — APPROVED by manager"
}

これは、複数の連続した HITL ゲートを持つマルチステップ ワークフローで自然に機能します。各 completePendingResponse 呼び出しは、それ自体が一時停止される可能性がある新しい ResultWithAgenticScope を返します。

ResultWithAgenticScope<String> result = workflow.processOrder("order-12345", "1000 widgets");

result = result.completePendingResponse("Manager OK"); // resumes, suspends at legal gate
result = result.completePendingResponse("Legal OK"); // resumes, completes
// result.result() → final output

ResultWithAgenticScope は、制御フローの例外の使用を回避するため、一時停止を処理する場合に推奨されるアプローチです。

逆に、メソッドが ResultWithAgenticScope ではなくプレーン タイプ (例: String) を返す場合、システムは中断時に AgenticSystemSuspendedException をスローします。その場合、またはスコープを介して直接再開する必要がある場合(クラッシュ/再起動後など)、AgenticScope で応答を完了し、エージェント メソッドを再度呼び出すことができます。

AgenticScope scope = workflow.getAgenticScope("order-12345");

// Complete the single deferred response (when there is exactly one)
scope.completePendingResponse("APPROVED by manager");

// Or complete by explicit ID (useful when multiple responses are pending)
scope.completePendingResponse("manager-approval", "APPROVED by manager");

// Then re-invoke — the planner resumes from the checkpoint
String result = workflow.processOrder("order-12345", "1000 widgets");

completePendingResponse は、メモリ内のフューチャーを完了する (待機中のスレッドのブロックを解除する) ことと、状態マップ エントリを解決された値に置き換える (シリアル化が存続する) ことの両方に注意してください。遅延応答が 1 つだけ存在しない場合、単一引数のオーバーロードは IllegalStateException をスローします。

中断時から監視していた AgentMonitor は、再開後も元の呼び出し記録を継続します。詳細はモニタリングを参照してください。再起動後などに作られたモニターは、再開した呼び出しを新しい実行として記録します。

エージェントレジストリ​

langchain4j-agentic モジュールは、AgentsRegistry の SPI (サービス プロバイダー インターフェイス) を提供し、外部プロバイダーが名前で検出して任意のエージェント パターンに接続できるエージェントを登録できるようにします。これは、リモート A2A プロトコル エージェントなどの外部システムによって提供されるエージェントをローカルに定義されたエージェント ワークフローに統合する場合に特に役立ちます。

AgentsRegistry インターフェイスは、エージェントを検出するための 2 つの方法を定義します。

public interface AgentsRegistry {

Map<String, AgentInstance> allAgents();

AgentInstance getAgent(String name);

static AgentsRegistry get() { ... }
}
  • allAgents() は、名前をキーとしたすべての登録済みエージェントのマップを返します。
  • getAgent(String name) は指定された名前のエージェントを返し、見つからない場合は RuntimeException をスローします。

静的 get() メソッドは、Java の ServiceLoader を使用してレジストリ実装を検出します。複数のプロバイダーがサポートされており、単一の複合レジストリに自動的にマージされます。プロバイダー間でエージェント名が重複すると、検出時に例外が発生します。プロバイダーが見つからない場合は、検索をスローする空のレジストリが返されます。

レジストリ実装を提供するには、AgentsRegistry インターフェイスを実装するクラスを作成し、実装クラスの完全修飾名を含むファイル META-INF/services/dev.langchain4j.agentic.planner.AgentsRegistry を作成することで、標準の Java SPI メカニズムを介してそれを登録します。

public class MyAgentsRegistry implements AgentsRegistry {

private final Map<String, AgentInstance> agents;

public MyAgentsRegistry() {
AgentInstance audienceEditor = (AgentInstance) AgenticServices
.agentBuilder(AudienceEditor.class)
.chatModel(myModel())
.outputKey("story")
.build();

AgentInstance styleEditor = (AgentInstance) AgenticServices
.agentBuilder(StyleEditor.class)
.chatModel(myModel())
.outputKey("story")
.build();

this.agents = Map.of(
"audienceEditor", audienceEditor,
"styleEditor", styleEditor);
}

@Override
public Map<String, AgentInstance> allAgents() {
return agents;
}

@Override
public AgentInstance getAgent(String name) {
AgentInstance agent = agents.get(name);
if (agent == null) {
throw new RuntimeException("No agent found with name: " + name);
}
return agent;
}
}

レジストリによって返されるエージェントは標準の AgentInstance オブジェクトであり、通常は AgenticServices.agentBuilder() を使用して構築されるため、あらゆるエージェント パターンでサブエージェントとして使用できるようになります。

SPI 経由でレジストリが利用可能になると、エージェントをロードし、任意のエージェント パターンでローカルに定義されたエージェントと混合できます。

AgentsRegistry registry = AgentsRegistry.get();

CreativeWriter creativeWriter = AgenticServices
.agentBuilder(CreativeWriter.class)
.chatModel(BASE_MODEL)
.outputKey("story")
.build();

AgentInstance audienceEditor = registry.getAgent("audienceEditor");
AgentInstance styleEditor = registry.getAgent("styleEditor");

UntypedAgent novelCreator = AgenticServices.sequenceBuilder()
.subAgents(creativeWriter, audienceEditor, styleEditor)
.outputKey("story")
.build();

String story = (String) novelCreator.invoke(Map.of(
"topic", "dragons and wizards",
"style", "fantasy",
"audience", "young adults"));

ここで、CreativeWriter はローカルに構築されますが、AudienceEditor と StyleEditor は名前によってレジストリからロードされ、ローカルに定義されたものと並んでサブエージェントとして使用されます。

@RegistryAgent アノテーションを使用すると、宣言型 API でレジストリからエージェントをロードできます。これを使用するには、レジストリ内のエージェントの名前を指定して、@RegistryAgent アノテーションが付けられたメソッドを使用して単純なインターフェイスを定義します。

public interface AudienceEditorFromRegistry {
@RegistryAgent("audienceEditor")
String editStory(@V("story") String story, @V("audience") String audience);
}

public interface StyleEditorFromRegistry {
@RegistryAgent("styleEditor")
String editStory(@V("story") String story, @V("style") String style);
}

これらのインターフェイスは、完全に宣言的なエージェント システム定義のサブエージェントとして使用できます。

public interface DeclarativeStoryCreator {

@SequenceAgent(outputKey = "story",
subAgents = {CreativeWriter.class, AudienceEditorFromRegistry.class, StyleEditorFromRegistry.class})
String write(@V("topic") String topic, @V("style") String style, @V("audience") String audience);

@ChatModelSupplier
static ChatModel chatModel() {
return BASE_MODEL;
}
}

そしていつものように AgenticServices.createAgenticSystem() でインスタンス化します。

DeclarativeStoryCreator storyCreator = AgenticServices.createAgenticSystem(DeclarativeStoryCreator.class);

String story = storyCreator.write("dragons and wizards", "fantasy", "young adults");

宣言型システムが @RegistryAgent アノテーションを検出すると、対応するエージェントを名前でレジストリから自動的にロードし、エージェント システムに接続します。 This allows mixing locally defined agents (like CreativeWriter with its @ChatModelSupplier) and registry-provided agents in the same declarative workflow.

A2A統合​

追加の langchain4j-agentic-a2a モジュールは、A2A プロトコルとのシームレスな統合を提供し、リモート A2A サーバー エージェントを使用し、最終的にはそれらを他のローカルに定義されたエージェントと混合できるエージェント システムを構築できるようにします。

たとえば、最初の例で使用した CreativeWriter エージェントがリモート A2A サーバー上で定義されている場合、ローカル エージェントと同じように使用できる A2ACreativeWriter エージェントを作成できますが、リモート エージェントを呼び出します。

UntypedAgent creativeWriter = AgenticServices
.a2aBuilder(A2A_SERVER_URL)
.inputKeys("topic")
.outputKey("story")
.build();

エージェントの機能の説明は、A2A サーバーが提供するエージェントカードから自動的に取得されます。このカードは、エージェントカードの解決のセクションで説明するように、エージェントの構築時ではなく、最初に必要になったときに取得されます。ただし、このカードには入力引数の名前は含まれないため、inputKeys メソッドを使用して明示的に指定する必要があります。

あるいは、次のように A2A エージェントのローカル インターフェイスを定義することもできます。

public interface A2ACreativeWriter {

@Agent
String generateStory(@V("topic") String topic);
}

これにより、より型安全な方法で使用できるようになり、入力名はメソッドの引数から自動的に派生されます。

A2ACreativeWriter creativeWriter = AgenticServices
.a2aBuilder(A2A_SERVER_URL, A2ACreativeWriter.class)
.outputKey("story")
.build();

このエージェントは、ワークフローを定義するとき、またはスーパーバイザのサブエージェントとして使用するときに、ローカル エージェントと同じ方法で使用したり、ローカル エージェントと混合したりできます。

リモート A2A エージェントは Task タイプを返す必要があります。

エージェントカードの解決​

A2A クライアントエージェント、またはそれを含むエージェント型システムを構築しても、A2A サーバーに接続することはありません。エージェントカードは遅延取得され、最初に必要になったとき、通常はそのエージェントの最初の呼び出し時に取得されます。これにより、エージェント型システムの構築時にダウンしている、または遅いリモートエージェントは、実際にそれに到達する呼び出しにのみ影響します。たとえば、アクティベーション条件によってスキップされる A2A エージェントは、そのサーバーが稼働している必要が一切ありません。構築時に行われるチェックは、サーバー URL(絶対 http または https URL でなければなりません)とテナントのみであり、不正な形式のものは、エージェントの構築時に AgenticSystemConfigurationException で失敗します。

このため、最初の呼び出しの前にエージェントについて分かっていることに、いくつかの影響があります。

  • 名前: A2A エージェントの名前は、カードなしでも常にローカルで分かります。これは、@A2AClientAgent アノテーションの name 属性またはビルダーの name メソッドで設定したものです。設定されていない場合、型付きエージェントは、他のエージェントと同様に、エージェントメソッドの @Agent アノテーションの名前、それも設定されていなければメソッド自体の名前を使用します。一方、a2aBuilder(A2A_SERVER_URL) で作成した型なしのエージェントには、サーバー URL のホスト、ポート、パスから導出されるプレースホルダー名が付けられます。たとえば http://remote-host:8080 なら a2a-remote-host-8080 です。型なしエージェント、特にスーパーバイザーが使用するものには、意味のある名前を設定することをお勧めします。スーパーバイザーのモデルはすべてのサブエージェントの名前を目にするためです。エージェント ID は名前から導出され、AgentMonitor のレポート、スーパーバイザーに送信されるエージェントのリスト、エラーハンドラーが受け取る ErrorContext で使用され、カードの取得後も決して変わりません。
  • 説明: 説明が @A2AClientAgent または @Agent アノテーションの description(または value)属性でも、ビルダーの description メソッドでも設定されていない場合、最初に要求されたときに取得されるエージェントカードから読み取られます。スーパーバイザーのようにサブエージェントの説明に依存するエージェント型パターンは、呼び出されたときにそれらを読み取るため、その場合はスーパーバイザーの最初の呼び出しでカードが取得されます。カードを取得できない場合、スーパーバイザーはその呼び出しについて、そのエージェントを警告とともにモデルに提示するサブエージェントから除外し、次回の呼び出しで再度試行します。また、HtmlReportGenerator の HTML レポートでは、失敗する代わりに、エージェントの説明が利用不可と表示されます。説明を明示的に設定すると、これらすべてを回避でき、リモートサーバーによって制御されるテキストをスーパーバイザーのプロンプトに含めずに済みます。
  • テナント: 明示的に設定されたテナントはすべてのメッセージとともに送信され、エージェントカードからの自動検出は最初のメッセージが送信されるときに実行されます。
  • クライアントのカスタマイズ: a2a-java の Client はカードから作成されるため、クライアントカスタマイザーは、エージェントの構築時ではなく、最初の呼び出し時に実行されます。ただし、SupplierParameterResolver によって提供される @A2AClientCustomizer メソッドのパラメーターは、他のサプライヤーメソッドのものと同様に、エージェントの構築時に解決されます。そのため、トークンのようにリクエストごとに解決される値は、最初の呼び出し元のものではなく、エージェントを構築したスレッドのものになります。

エージェントの最初の呼び出しは、カード取得のレイテンシを負担します。すべての A2A クライアントエージェントが実装する A2AClientInstance インターフェースの agentCard() メソッドを呼び出すと、カードがすぐに取得されます。これは、エージェントのウォームアップや、カードを取得できない場合に最初の呼び出しの前に早期に失敗させるために使用できます。

AgentCard agentCard = ((A2AClientInstance) creativeWriter).agentCard();

エージェントカードの取得は LangChain4j executor のスレッドで実行されます。a2a-java SDK の HTTP クライアントにタイムアウトがないため、デフォルトで 30 秒の制限があります。これはカード取得だけを制限し、エージェントに送るメッセージには適用されません。builder の resolutionTimeout または @A2AClientAgent の resolutionTimeoutSeconds で変更できます。ゼロにすると制限がなくなり、カードを最初に必要とする呼び出しのスレッドで取得します。

UntypedAgent creativeWriter = AgenticServices
.a2aBuilder(A2A_SERVER_URL)
.inputKeys("topic")
.outputKey("story")
.resolutionTimeout(Duration.ofSeconds(5))
.build();

時間内に取得できなければ取得処理を中断し、下記のように java.util.concurrent.TimeoutException を原因として呼び出しが失敗します。取得中に到着したほかの呼び出しは同じ取得を待ち、別々に要求しません。失敗時は全員が失敗し、順番に再試行することはありません。中断に反応しない取得は継続し、終わるまで新しい取得はできません。その間の呼び出しは直ちに失敗し、前回のタイムアウトした取得がまだ実行中である旨を示します。後から返されたカードは保持されます。タイムアウト時と遅れて返ったカードを保持した時に警告が記録されます。

カードを取得できないと A2AAgentCardException がスローされます。エージェント名、サーバー URL、元のエラーを保持し、A2A と MCP に共通の利用不能エラー AgentUnavailableException を継承します。この失敗はキャッシュされないため、次回はカードを再取得し、サーバー復旧後はシステムを再構築せずに動作します。例外は AgentInvocationException の原因チェーンを通じてエラーハンドラーにも届きます。具体的な型で A2A のみを扱うことも、AgentUnavailableException で利用不能な MCP エージェントも同様に扱うこともできます。

UntypedAgent pipeline = AgenticServices.sequenceBuilder()
.subAgents(analyzer, remoteFixer)
.outputKey("fix")
.errorHandler(errorContext -> {
for (Throwable cause = errorContext.exception(); cause != null; cause = cause.getCause()) {
if (cause instanceof A2AAgentCardException) {
return ErrorRecoveryResult.result("no fix available, the remote fixer is unreachable");
}
}
return ErrorRecoveryResult.throwException();
})
.build();

A2A サーバーとのマルチターン会話​

A2A プロトコルは、メッセージエンベロープの contextId と taskId フィールドによってマルチターンの会話をサポートします。contextId は関連するタスクを 1 つの会話にまとめ、taskId はその会話内の特定のタスクを参照します。省略した場合、A2A サーバーは新しい値を生成します。taskId が指定された場合、サーバーは新しいタスクを作成する代わりに、その既存のタスクを継続します。

これらのフィールドを送信メッセージ エンベロープで渡すには、メソッド パラメーターに @A2AContextId および @A2ATaskId の注釈を付けます。これらのパラメータはメッセージ コンテンツとして送信されません**。代わりにメッセージ エンベロープに設定されます。

public interface ChatAgent {

@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
String chat(@V("question") String question,
@A2AContextId @V("contextId") String contextId,
@A2ATaskId @V("taskId") String taskId);
}

null が contextId または taskId に渡されると、フィールドはエンベロープから省略され、サーバーは新しい値を作成します。

@A2AContextId パラメーターにも認識可能な名前がある場合(@V アノテーションで設定されている場合もあります)、レスポンスにあるサーバー側で割り当てられた値は、その名前で AgenticScope に自動的に書き戻されます。これにより、最初の呼び出しがコンテキストを取得し、後続の呼び出しが同じ会話を継続するマルチターンのフローが可能になります。サーバーはコンテキストを保持し、呼び出しごとにその中に新しいタスクを作成します。

taskId は別のルールに従います。リモートタスクが呼び出しの戻り時点でまだ開いている場合にのみ AgenticScope に書き戻され、そうでなければスコープのエントリはクリアされます。呼び出しは通常、タスクが終了状態に達してから戻り、A2A サーバーはそのようなタスクへの以降のメッセージを拒否するため、一般的なケースでは何も伝播されず、次の呼び出しは新しいタスクを開始します。唯一の例外は、ストリームの消費を早期に停止するストリーミングクライアントリスナーです。リモートタスクは実行を続け、その識別子はスコープに保持されるため、ポーリング、キャンセル、継続が引き続き可能です。

それ以外の場合、taskId は呼び出しの引数から取得されます。サーバーに新しいタスクを作成させるには null を渡す(またはパラメーターを省略する)か、既存のタスクを継続するにはそのタスクの識別子を渡します。

メソッドが ResultWithAgenticScope を返す場合は、コンテキストに直接アクセスできます。

public interface ChatAgent {

@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
ResultWithAgenticScope<String> chat(
@V("question") String question,
@A2AContextId @V("contextId") String contextId,
@A2ATaskId @V("taskId") String taskId);
}

// First turn — server generates contextId and taskId
ResultWithAgenticScope<String> first = chatAgent.chat("hello", null, null);
String contextId = (String) first.agenticScope().readState("contextId");

// Second turn — reuse the server-generated context to continue the conversation,
// while letting the server create a new task for this invocation
ResultWithAgenticScope<String> second = chatAgent.chat("follow-up", contextId, null);

このように、A2A エージェントをエージェント型システムで使用すると、contextId は共有された AgenticScope を通じて自動的に伝播されます。つまり、同じサーバーに対する 2 つの A2A 呼び出しのシーケンスは、自然にマルチターンの会話を形成します。

public interface EchoSubAgent {

@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
String echo(@V("question") String question,
@A2AContextId @V("contextId") String contextId,
@A2ATaskId @V("taskId") String taskId);
}

public interface MultiTurnWorkflow extends AgenticScopeAccess {

@Agent
ResultWithAgenticScope<String> converse(@V("question") String question);
}

EchoSubAgent firstTurn = AgenticServices
.a2aBuilder("http://localhost:8080", EchoSubAgent.class)
.outputKey("firstResponse").build();
EchoSubAgent secondTurn = AgenticServices
.a2aBuilder("http://localhost:8080", EchoSubAgent.class)
.outputKey("secondResponse").build();

MultiTurnWorkflow workflow = AgenticServices.sequenceBuilder(MultiTurnWorkflow.class)
.subAgents(firstTurn, secondTurn)
.outputKey("secondResponse").build();

ResultWithAgenticScope<String> result = workflow.converse("hello");

このシーケンスでは、最初のエージェントが contextId/taskId なし(スコープ内では null)でメッセージを送信します。サーバーは新しいコンテキストと新しいタスクを作成し、その後 contextId がスコープに書き込まれます。2 番目のエージェントが実行されると、スコープから、この時点で設定済みの contextId を読み取り、メッセージエンベロープに載せて送信するため、会話が継続されます。最初のエージェントが完了したタスクはこれ以上メッセージを受け付けられないため、taskId はスコープ内で未設定のままとなり、サーバーは同じコンテキスト内に新しいタスクを作成します。

マルチテナント A2A エージェント​

マルチテナントの A2A デプロイメントでは、サーバーが正しいルーティング、分離、ポリシーを適用できるよう、メッセージを特定のテナントにスコープする必要があります。langchain4j-agentic-a2a モジュールは、テナントを設定する 3 つの方法をサポートしています。テナントが固定か、動的か、サーバー URL から自動的に導出されるかによって使い分けます。

エージェントカード URL からの自動検出​

テナントが設定されていない場合、クライアントはエージェントカード URL から自動的にテナントを抽出します。マルチテナントの A2A サーバーは通常、/.well-known/{tenant}/agent-card.json という規約に従います。エージェントカード URL がこのパターンに一致する場合、抽出されたテナントは、設定不要で、送信されるすべてのメッセージに暗黙的に適用されます。カードは遅延取得されるため、検出は最初のメッセージが送信されるときに行われます。

@A2AClientAgent アノテーションによる静的テナント​

テナントがビルド時に分かっていて、すべての呼び出しで同じ場合は、@A2AClientAgent アノテーションに tenant 属性を直接設定します。

public interface MyA2AAgent {

@A2AClientAgent(a2aServerUrl = "http://localhost:8080", tenant = "acme", outputKey = "response")
String chat(@V("question") String question);
}

テナントは、このエージェントが送信するすべてのメッセージの MessageSendParams に設定されます。メソッドのパラメーターは不要です。メッセージの内容に TextPart として含まれることはありません。アノテーションで tenant を設定すると、エージェントカード URL からの自動検出よりも優先されます。

プログラムで構築する場合は、テナントを a2aBuilder の第 2 引数として渡します。

UntypedAgent agent = AgenticServices
.a2aBuilder("http://localhost:8080", "acme")
.inputKeys("question")
.outputKey("response")
.build();

// Or with a typed interface:
MyA2AAgent agent = AgenticServices
.a2aBuilder("http://localhost:8080", "acme", MyA2AAgent.class)
.outputKey("response")
.build();

@A2ATenantId による動的テナント​

テナントが呼び出しごとに異なる場合は、メソッドパラメーターに @A2ATenantId をアノテートします。パラメーターの値は、送信される MessageSendParams の tenant フィールドとして設定されます。メッセージの内容に TextPart として含まれることはありません。

public interface MyA2AAgent {

@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
String chat(@V("question") String question,
@A2AContextId String contextId,
@A2ATenantId String tenant);
}

tenant に null または空文字列が渡された場合、フィールドは MessageSendParams から省略され、サーバーはデフォルトのテナント解決を適用します。

@A2ATenantId は、@A2AContextId および @A2ATaskId と自由に組み合わせられます。

public interface MultiTenantChatAgent {

@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
String chat(@V("question") String question,
@A2AContextId @V("contextId") String contextId,
@A2ATaskId @V("taskId") String taskId,
@A2ATenantId String tenant);
}

@A2AContextId や @A2ATaskId とは異なり、テナントの値が AgenticScope に書き戻されることはありません。呼び出し元が、呼び出しのたびにそれを指定する責任を負います。

まとめ:テナント解決の順序​

方法使用する場面
エージェントカード URL からの自動検出サーバー URL が /.well-known/{tenant}/agent-card.json に従い、テナントが一定である
@A2AClientAgent の tenant(または a2aBuilder(url, tenant, ...))テナントが固定で、ビルド時に分かっている
@A2ATenantId メソッドパラメーターテナントが呼び出しごとに異なる

ヒューマン・イン・ザ・ループ A2A エージェント​

A2A サーバーは、タスクを input-required または auth-required の状態で一時停止できます。これがエージェント型システム内で起こると、A2A クライアントは SuspendedResponse を AgenticScope に保存し、ワークフローのチェックポイントを作成して、呼び出しスレッドを解放します。この中断には、同じリモートタスクを継続するために必要なタスク ID とコンテキスト ID が含まれます。

呼び出し元は、これらの詳細を Kafka トピックなどの外部システムに公開できます。

try {
workflow.invoke("request-123", "Book the trip");
} catch (AgenticSystemSuspendedException e) {
AgenticScope scope = e.scope();
String responseId = scope.pendingResponseIds().iterator().next();
A2ATaskInterruptedException interruption = A2ATaskInterruptedException.from(scope, responseId);

inputRequests.publish(new InputRequest(
scope.memoryId(), responseId, interruption.taskId(),
interruption.contextId(), interruption.reason()));
}

人間の応答が後で届いたら、保留中のレスポンスを完了し、ワークフローを再度呼び出します。プランナーはチェックポイントから再開し、A2A クライアントは新しいタスクを開始する代わりに、保存された contextId と taskId を付けてレスポンスを送信します。

void onInputResponse(InputResponse response) {
AgenticScope scope = workflow.getAgenticScope(response.memoryId());
scope.completePendingResponse(response.responseId(), response.text());
workflow.invoke(response.memoryId(), "Book the trip");
}

completePendingResponse(...) は、一時停止されたスコープに人間の回答を記録しますが、ワークフロー自体を再開するわけではありません。続く呼び出しは、元のリクエストで使用したのと同じ workflow.invoke(...) メソッドを、同じメモリ ID と元の引数で呼び出すものです。メモリ ID によって保存されたプランナーのチェックポイントが復元され、実行が A2A クライアントに到達すると、完了したレスポンスが保存された contextId と taskId とともに送信され、既存のリモートタスクが継続されます。

エージェント型システムの外部で A2A クライアントが呼び出された場合は、一時停止するスコープがありません。その場合は A2ATaskInterruptedException が直接スローされるため、呼び出し元は中断を手動で処理できます。

A2A クライアントのカスタマイズ​

デフォルトでは、A2A エージェントはデフォルト設定の JSONRPC トランスポートを使用します。clientCustomizer メソッドは、基盤となる a2a-java SDK の ClientBuilder を公開しており、別のトランスポートの設定、カスタム HTTP クライアントの設定、インターセプターの追加、その他のクライアント設定の変更ができます。カスタマイザーは、エージェントのビルド時ではなく、Client が作成されるとき、つまりエージェントの最初の呼び出し時でエージェントカードが利用可能になった後に適用されます。

A2A エージェントをプログラムで構築する場合は、Consumer<ClientBuilder> を clientCustomizer に渡します。

UntypedAgent creativeWriter = AgenticServices
.a2aBuilder(A2A_SERVER_URL)
.clientCustomizer((ClientBuilder cb) ->
cb.withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder()))
.inputKeys("topic")
.outputKey("story")
.build();

カスタマイザーが提供されると、デフォルトのトランスポート設定が完全​​に置き換えられ、Client の構築方法を完全に制御できるようになります。

宣言型エージェントでは、静的メソッドに @A2AClientCustomizer をアノテートします。メソッドは ClientBuilder パラメーターを受け取り、void を返す必要があります。それ以外のパラメーターは SupplierParameterResolver によって提供される必要があります。これはエージェントの構築時に解決され、メソッド自体はクライアントの作成時、つまりエージェントの最初の呼び出し時に実行されます。

public interface DeclarativeA2AWithCustomizer {

@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "story")
String generateStory(@V("topic") String topic);

@A2AClientCustomizer
static void customizer(ClientBuilder cb) {
cb.withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder());
}
}

ストリーミング A2A クライアントリスナー​

ストリーミングを有効にしてリモート A2A エージェントを呼び出す場合、A2AStreamingClientListener を使用して、リモートエージェントから受信したイベントを監視し、クライアントがストリームの消費をいつ停止すべきかを制御できます。

これは、リモートタスクの完了を待つ代わりに、特定のイベントにのみ反応すればよい場合に便利です。たとえば、リモートエージェントが追加の入力を要求したときにリッスンを停止し、そのメッセージを直ちに呼び出し元に返すことができます。

UntypedAgent creativeWriter = AgenticServices.a2aBuilder(A2A_SERVER_URL)
.inputKeys("topic")
.outputKey("story")
.streamingClientListener((TaskUpdateEvent event) -> {
UpdateEvent updateEvent = event.getUpdateEvent();
if (updateEvent instanceof TaskStatusUpdateEvent taskStatusUpdateEvent
&& taskStatusUpdateEvent.status().state() == TaskState.TASK_STATE_WORKING) {
return A2AStreamingClientListenerResult.stopWithResponse(
"stop when status update to TASK_STATE_WORKING, and return this message to the caller");
}
return A2AStreamingClientListenerResult.continueStreaming();
})
.build();

リスナーは、リモート A2A エージェントから受信したイベントごとに呼び出されます。イベントの消費を続けるには continueStreaming() を、ストリームの消費を停止して指定したレスポンスを呼び出し元に返すには stopWithResponse(response) を、ストリームの消費を停止してこれまでに受信したアーティファクトを、デフォルトの A2A クライアントのアーティファクトからテキストへの抽出ロジックを使って返すには stopWithCurrentArtifacts() を返します。

クライアント側のストリームを停止しても、リモートの A2A タスクはキャンセルされません。リモートタスクは非同期に実行を続ける場合があります。呼び出しが戻った時点でそのタスクはまだ開いているため、エージェントが @A2ATaskId パラメーターを宣言している場合、その識別子はそのパラメーターの名前で AgenticScope に書き戻され、呼び出し元はそれをポーリング、キャンセル、継続できます。これは、taskId がスコープを通じて伝播される唯一のケースであり、A2A サーバーとのマルチターン会話のセクションで説明したとおりです。

A2A サーバー URL を動的に構成する​

デフォルトでは、@A2AClientAgent アノテーションには、a2aServerUrl 属性を介したコンパイル時の文字列リテラルとして A2A サーバー URL が必要です。 URL が異なる環境 (開発、ステージング、運用など) の場合は、代わりに、@A2AServerUrlSupplier アノテーションが付けられた静的メソッドを使用して、ビルド時に URL を動的に提供できます。

public interface DeclarativeA2AWithUrlSupplier {

@A2AClientAgent(outputKey = "story")
String generateStory(@V("topic") String topic);

@A2AServerUrlSupplier
static String serverUrl() {
return System.getenv("A2A_SERVER_URL");
}
}

サプライヤー メソッドは static である必要があり、パラメーターを受け取らず、String を返します。これは、エージェントの構築時に 1 回呼び出されます。URL は呼び出し間で変更されません。アノテーション内の a2aServerUrl または @A2AServerUrlSupplier メソッドの 1 つだけを指定する必要があります。両方を指定しても (またはどちらも指定しなくても) エラーになります。

このパターンは、@McpClientSupplier が @McpClientAgent に MCP クライアントを提供する方法と同様です。ただし、そのメソッドはクライアントが初めて必要になった時点で実行されます。

MCPベースのツールエージェント​

追加の langchain4j-agentic-mcp モジュールを使用すると、単一の MCP ツールをエージェント システム内の非 AI エージェントとしてラップできます。 LLM を使用する通常のエージェントとは異なり、MCP ツール エージェントは単純に MCP ツールを直接実行し、その結果を返します。これにより、ツールの実行自体に LLM を関与させることなく、大規模なエージェント システムで他のエージェントを使用して MCP ツールを構成することが可能になります。

MCP ツールエージェントは McpClient を渡して McpAgent.builder() で作成します。ツールの仕様(名前、説明、入力スキーマ)は初めて必要になったときに MCP サーバーから読み取られます(ツールの解決を参照)。呼び出しはそのツールへ転送されます。

たとえば、MCP サーバーが generate_story ツールを公開する場合、それを型なしエージェントとしてラップできます。

McpClient mcpClient = new DefaultMcpClient.Builder()
.transport(myMcpTransport)
.build();

UntypedAgent storyGenerator = McpAgent.builder(mcpClient)
.toolName("generate_story")
.inputKeys("topic")
.outputKey("story")
.build();

String story = (String) storyGenerator.invoke(Map.of("topic", "dragons and wizards"));

toolName はサーバーに複数のツールがあるときの対象を指定します。ツールが一つなら省略できます。inputKeys は入力パラメーター名です。型なしエージェントでは必須で、省略するとツール解決前に引数を報告できず、構築時に IllegalArgumentException が発生します。型付きエージェントでは、未指定ならメソッドのパラメーターから取得します。

DefaultMcpClient は作成時にサーバーへ接続します。接続も初めて必要になるまで遅らせるには、クライアントの代わりに Supplier<McpClient> を builder に渡します。

UntypedAgent storyGenerator = McpAgent.builder(() -> new DefaultMcpClient.Builder()
.transport(new StreamableHttpMcpTransport.Builder()
.url("http://localhost:8081/mcp")
.build())
.build())
.toolName("generate_story")
.inputKeys("topic")
.outputKey("story")
.build();

サプライヤーはクライアントが初めて必要になったとき、通常はその呼び出しのスレッドで実行されます。エージェントに解決タイムアウトを設定した場合は LangChain4j executor のスレッドで実行されます。そのスレッドで呼び出し元のスレッドローカルなコンテキストを利用できるのは、captureContext() を実装した ExecutorProvider が登録されている場合だけです。返されたクライアントは全呼び出しで共有されるため、現在のユーザーの資格情報など、リクエスト固有の状態に依存させないでください。失敗すると待機中の呼び出しがすべて失敗し、次に必要になったときに再試行します。DefaultMcpClient の接続失敗時にはトランスポートが停止し、開始したサブプロセス、コンテナ、接続が解放されます。したがって上記のようにサプライヤー内でトランスポートを作成することも、保持するものを再利用することもできます。エージェントはクライアントを閉じないため、必要ならサプライヤー側で参照を保持してください。

他のエージェントと同様に、MCP ツール エージェントも型付きインターフェイスを使用して作成できます。

public interface StoryGenerator {

@Agent
String generateStory(@V("topic") String topic);
}

StoryGenerator storyGenerator = McpAgent.builder(mcpClient, StoryGenerator.class)
.toolName("generate_story")
.outputKey("story")
.build();

String story = storyGenerator.generateStory("dragons and wizards");

この場合、入力パラメーター名はメソッド パラメーター (またはその @V 注釈) から派生し、戻り値の型によってツールのテキスト結果が解析される方法が決まります。

MCP ツールエージェントは @McpClientAgent でも宣言できます。@McpClientSupplier は McpClient を提供する静的メソッドを示します。このメソッドはシステム構築時ではなく、通常はエージェントの初回呼び出し時にそのスレッドで実行されます。解決タイムアウトを設定した場合は LangChain4j executor のスレッドで実行されます。返されたクライアントは全呼び出しで共有され、エージェントは閉じません。

public interface DeclarativeMcpStoryGenerator {

@McpClientAgent(toolName = "generate_story", outputKey = "story",
description = "Generates a story based on the given topic")
String generateStory(@V("topic") String topic);

@McpClientSupplier
static McpClient mcpClient() {
McpTransport transport = new StreamableHttpMcpTransport.Builder()
.url("http://localhost:8081/mcp")
.build();
return new DefaultMcpClient.Builder()
.transport(transport)
.build();
}
}

ツールの解決​

MCP ツールエージェントやそれを含むシステムを構築しても、MCP サーバーには接続しません。ツールは初めて必要になったとき、通常は初回呼び出し時に McpClient.listTools() で解決します。構築時にサーバーが停止または低速でも、実際にそのエージェントを使う呼び出しだけが影響を受け、有効化条件でスキップされたエージェントはサーバーを必要としません。呼び出し元が DefaultMcpClient を直接作成して渡すと、クライアント作成時には接続します。接続も遅らせるには上記の Supplier<McpClient> を、宣言型エージェントでは @McpClientSupplier を使います。

初回呼び出し前に分かる情報は次のとおりです。

  • 名前:サーバーに接続せずに決まります。@McpClientAgent または builder の name、型付きエージェントでは @Agent の名前またはメソッド名を使います。型なしエージェントは toolName を使い、それもなければ警告を伴う mcp-agent という仮名になります。同じシステムでこの仮名を使えるのは一つだけで、二つあると構築時に AgenticSystemConfigurationException が発生します。特にスーパーバイザーで使う型なしエージェントには意味のある名前を設定してください。名前とエージェント ID は監視、レポート、スーパーバイザーのプロンプト、エラーコンテキストで使われ、ツール解決後も変わりません。McpClientInstance.toolName() で実際のツール名を取得できますが、未設定ならツールの解決が必要です。
  • 説明:注釈や builder で明示しないと、初めて説明を要求したときにツールを解決し、その説明を使います。スーパーバイザーは呼び出し時に説明を読みます。サーバーが利用不能なら、その呼び出しでは候補から除外して次回再試行し、HTML レポートには説明が利用不能と表示されます。ツールが存在しないなどの設定エラーは、スーパーバイザーの呼び出しとレポート生成を失敗させます。説明を明示すると、サーバーが制御するツール説明をスーパーバイザーのプロンプトに入れずに済みます。ただし、解決後の入力パラメーターの説明はプロンプトに届きます。
  • 引数:ワークフロー構築時に引数を読んでもサーバーには接続しません。解決前、型付きエージェントはメソッド引数を、型なしエージェントは型情報のない必須の inputKeys を使います。解決後はスキーマの説明、型なしエージェントでは型と任意性も得られます。型付きエージェントは接続前に必要な入力を確認します。型なしエージェントは必須入力を知るため先にツールを解決します。
  • クライアントのサプライヤー:@McpClientSupplier の引数は SupplierParameterResolver によりエージェント構築時に解決され、メソッド自体はクライアントが必要になった時点で実行されます。リクエストごとの値は初回呼び出し元ではなく構築スレッドの値です。戻り値の宣言型も構築時に確認されます。McpClient、そのサブタイプ、または Object などのスーパータイプを使用でき、後者はクライアント作成時に実際のインスタンスを確認します。

ツールは一度だけ解決され、サーバー側の変更を反映するにはエージェントを作り直す必要があります。初回呼び出しには解決の待ち時間が発生します。McpClientInstance.toolSpecification() を呼べば事前に解決してウォームアップや早期エラー検出ができます。

ToolSpecification tool = ((McpClientInstance) storyGenerator).toolSpecification();

宣言型システムでは MCP エージェントはラップされます。AgentInstance.subagents() から名前で探し、as(McpClientInstance.class) で取得できます。上記の DeclarativeMcpStoryGenerator を使うシーケンスの例です。

public interface StoryPipeline {

@SequenceAgent(outputKey = "story", subAgents = DeclarativeMcpStoryGenerator.class)
String write(@V("topic") String topic);
}

StoryPipeline storyPipeline = AgenticServices.createAgenticSystem(StoryPipeline.class);
AgentInstance mcpSubagent = ((AgentInstance) storyPipeline).subagents().stream()
.filter(subagent -> subagent.name().equals("generateStory"))
.findFirst()
.orElseThrow();
ToolSpecification tool = mcpSubagent.as(McpClientInstance.class).toolSpecification();

解決にはサプライヤーによるクライアントの作成とツール一覧の取得が含まれます。デフォルトでは最初に必要とする呼び出しのスレッドで実行されます。同時に到着した呼び出しは同じ解決を待ち、失敗した場合や解決スレッドが中断された場合にはすべて失敗し、順番に再試行しません。デフォルトの制限時間は MCP クライアントによります。DefaultMcpClient はプロトコルバージョンの検出に最大 30 秒(protocolVersion を明示すると省略)、初期化に最大 30 秒、ツール一覧の各要求に最大 60 秒待ちます。builder の resolutionTimeout または @McpClientAgent の resolutionTimeoutSeconds を指定すると、クライアントの種類に関係なく解決全体に一つの上限を設け、LangChain4j executor のスレッドで実行します。ゼロは統一上限なしを意味します。この設定はツールの実行時間を制限しません。

UntypedAgent storyGenerator = McpAgent.builder(mcpClient)
.toolName("generate_story")
.inputKeys("topic")
.outputKey("story")
.resolutionTimeout(Duration.ofSeconds(10))
.build();

制限時間内に解決できないと処理は中断されます。接続中の DefaultMcpClient はトランスポートを停止し、呼び出しは下記のように java.util.concurrent.TimeoutException を原因として失敗します。クライアントの各段階のタイムアウトも引き続き適用され、先に切れたものが有効です。中断に反応しない解決は継続し、終わるまでは再解決できません。その間の呼び出しは直ちに失敗し、前回のタイムアウトした解決がまだ実行中である旨を示します。後から見つかったツールは保持され、タイムアウト時と遅れて見つかったツールを保持した時に警告が記録されます。

クライアントを作成できない、またはツール一覧を取得できない場合は、エージェント名、設定されたツール名、元のエラーを保持する McpToolResolutionException が発生します。これは A2A の A2AAgentCardException と同様、AgentUnavailableException を継承します。失敗はキャッシュされず、次回再試行します。サーバーにツールがない場合や、複数のツールがあるのに toolName がない場合は設定エラーとなり、初回解決時に AgenticSystemConfigurationException が発生します。これらの例外は AgentInvocationException の原因チェーンを通じてエラーハンドラーにも届きます。以下では、上記の MCP エージェント storyGenerator と、必要な topic を書き込む別のエージェント analyzer を使用し、利用不能なリモートエージェントを共通の例外型で処理します。

UntypedAgent pipeline = AgenticServices.sequenceBuilder()
.subAgents(analyzer, storyGenerator)
.outputKey("story")
.errorHandler(errorContext -> {
for (Throwable cause = errorContext.exception(); cause != null; cause = cause.getCause()) {
if (cause instanceof AgentUnavailableException unavailable) {
return ErrorRecoveryResult.result("no story available, " + unavailable.agentName() + " is unreachable");
}
}
return ErrorRecoveryResult.throwException();
})
.build();