LangChain4J-CDI is the pivotal component that enables developers to integrate their AI services into their enterprise Java applications with ease, thanks to CDI.

Whether you're a seasoned developer or getting started with integrating AI in your existing Java application, here are the best practices that will ensure you get building your AI solutions with ease.

1. Applying CDI scopes to your AI service or AI agent

Whether you're creating an AI Service or an AI agent, you would feel compelled to apply the CDI scopes in this manner:

@RegisterAIService
@ApplicationScoped //<-- Do not do this. It doesn't work, and there's no side effect.
public interface ChatAiService {

    String chat(String message);
};

This won't work as the interface is not CDI managed. For those who want to be too technical, the CD scopes cannot propagate down to its proxy.

Instead, each of the LangChain4J-CDI stereotype annotations contains a scope() parameter where you can assign your CDI scope.

Example:

@RegisterAIService(scope = ApplicationScoped.class) //Better approach, it works.
public interface ChatAiService {

    String chat(String message);
};

This applies to all of these annotations:

//For AI Service
@RegisterAIService,

//For AI Agent
@RegisterSimpleAgent,
@RegisterSequenceAgent,
@RegisterLoopAgent,
@RegisterParallelAgent,
@RegisterParallelMapperAgent,
@RegisterConditionalAgent,
@RegisterSupervisorAgent,
@RegisterPlannerAgent,
@RegisterA2AAgent,
@RegisterMcpClientAgent,
@RegisterHumanInTheLoopAgent

## 2. Using MicroProfile Fault Tolerance Retry

If you want to apply a retry policy to your AI service or AI agent using MicroProfile @Retry annotation, you first have to disable LangChain4J's internal retry policy (which is set to 3 retries by default).

There are various ways to do this. Using MicroProfile config, set the maxRetries = 0.

For example:

dev.langchain4j.cdi.plugin.<bean-model-name>.config.max-retries=0

Or, if you're using LangChain4J's provider's ChatModelBuilder, then you can simply apply the same value by setting builder.maxRetries(0);.

Without disabling LangChain4J's internal retry policy, your application server will invoke the retry with the total complexity of O(n*m), where n is the max retries by MicroProfile and m is the max retries by LangChain4J.

Please note that not all LangChain4J AI providers provide a maxRetries on their ChatModel. If you're declaratively configuring maxRetries using MicroProfile Config on a bean without such property, the config property will be ignored.

3. Finally

These are the few caveats that we identified and thought were worth sharing so that you don't have to suffer in your AI discovery.
Happy coding! ☕👩🏾‍💻