Agents
Purpose
Section titled “Purpose”actor4j-agents makes an agent a pod. An agent pod receives a task as a message, passes it to a chat model and sends the answer back to the client. The chat model is integrated via LangChain4j, so prompts, typed answers (AiServices) and JSON schemas of LangChain4j can be used.
The call of the model is blocking and can take long. Therefore, it does not run in the pod actor itself but in a separate resource actor. The pod actor stays responsive and handles further messages while the model is working.
Relation to Actor4j - Core
Section titled “Relation to Actor4j - Core”Agent pods are function pods of actor4j-functions, which build on the pods of Actor4j - Core. They are deployed with PodDeployment, addressed via their domain as alias, and can be replicated. Remote variants accept a RemotePodMessage. Pods, Reply, PodDeployment and remote pods are described in Pods and are not repeated here.
The interplay of the actors:
- A client sends a message to the pod (alias = domain).
- The pod forwards the value to its resource actor and marks the reply as pending (
Reply.pending()). - The resource actor calls the model and sends the result back to the pod, with the same interaction.
- The pod creates the reply in
handleIoRequestand sends it to the client.
Modules
Section titled “Modules”| Artifact | Content |
|---|---|
actor4j-agents-pod |
AgentFunctionPod, AgentRemoteFunctionPod: function pods with the domain as constructor argument |
actor4j-agents-langchain4j |
ChatModelPod, ChatModelRemotePod, ChatModelResourceActor, OpenAiCompatibleChatModelResourceActor, ChatModelConfig, JsonSchemaUtils |
actor4j-agents-mcp |
dependency on the MCP Java SDK only, no Actor4j code yet |
Installation
Section titled “Installation”actor4j-agents depends on Actor4j - Core 2.5.0. As long as this version is not on Maven Central, install actor4j-core from source first, then actor4j (both with mvn install). Java 21 or newer is required.
<dependency> <groupId>io.actor4j</groupId> <artifactId>actor4j-agents-langchain4j</artifactId> <!-- includes actor4j-agents-pod --> <version>2.5.0</version></dependency>An application also needs a runtime of Actor4j - Core, e.g. actor4j-core-runtime (see SDK and Runtimes):
<dependency> <groupId>io.actor4j</groupId> <artifactId>actor4j-core-runtime</artifactId> <version>2.5.0</version></dependency>If only the pod base classes are needed (without LangChain4j), actor4j-agents-pod is enough.
Runtime Requirements
Section titled “Runtime Requirements”actor4j-agents-langchain4j brings langchain4j and langchain4j-open-ai. The included OpenAiCompatibleChatModelResourceActor talks to any server that offers an OpenAI-compatible chat API, e.g. a local inference server or a hosted provider. For another provider, add its LangChain4j module and implement createAiChatModel in an own ChatModelResourceActor (see below).
Configuration
Section titled “Configuration”ChatModelConfig holds the settings of the chat model. It is built in code or loaded from a JSON file (Jackson), also as part of a larger configuration:
ChatModelConfig config = ChatModelConfig.create() .baseUrl("http://localhost:9090/v1") .apiKey(System.getenv("LLM_API_KEY")) .modelName("your-model") .temperature(0.2) .timeout(Duration.ofMinutes(10)) .build();
ChatModelConfig config2 = ChatModelConfig.load(Path.of("model.json"));{ "baseUrl": "http://localhost:9090/v1", "modelName": "your-model", "temperature": 0.2, "timeout": "PT10M"}| Setting | Default | Meaning |
|---|---|---|
baseUrl |
http://localhost:9090/v1 |
endpoint of the chat API |
apiKey |
dummy |
API key (hidden in toString()) |
modelName |
test |
name of the model on the server |
temperature, topP |
0.2, 1.0 |
sampling |
timeout |
5 minutes | ISO-8601 ("PT10M") or seconds in JSON |
maxTokens, seed |
-1 |
-1 means not set (no limit, random seed) |
maxRetries |
2 |
retries of LangChain4j |
strictJsonSchema, returnThinking |
false |
passed to the model builder |
logRequests, logResponses |
false |
logging of LangChain4j |
customParameters |
empty | additional parameters of the request |
Values not given keep the defaults. Unknown keys in the JSON file are ignored.
Example: Agent Pod with a Typed Answer
Section titled “Example: Agent Pod with a Typed Answer”A ChatModelPod needs a domain, a ChatModelConfig and a factory method for its resource actor. The resource actor creates the model (here OpenAiCompatibleChatModelResourceActor), optionally a LangChain4j AiServices agent, and answers each message to its sender with the same interaction:
public class AnalystPod extends ChatModelPod { public record TaskAnalysis(String summary, List<String> steps, double confidence) { }
interface AnalystAgent { @SystemMessage("You are a precise system analyst.") TaskAnalysis analyze(String task); }
public AnalystPod(String domain, ChatModelConfig chatModelConfig) { super(domain, chatModelConfig); }
@Override public ChatModelResourceActor createChatModelResourceActor(ChatModelConfig chatModelConfig) { return new OpenAiCompatibleChatModelResourceActor(chatModelConfig) { protected AnalystAgent agent;
@Override public void createAiServices(ChatModel chatModel) { agent = AiServices.create(AnalystAgent.class, chatModel); }
@Override public void receive(ActorMessage<?> message) { TaskAnalysis result = agent.analyze(message.valueAsString()); tell(result, 0, message.source(), message.interaction()); } }; }}The answer of the resource actor is passed to the client unchanged. To transform it, override handleIoRequest(ActorMessage<?> message, UUID interaction, FunctionPodContext ctx) in the pod.
ActorSystem system = ActorSystem.create(ActorRuntime.factory(), ActorSystemConfig.builder().serverMode().build());
system.deployPods(() -> new AnalystPod("AnalystPod", config), new PodDeployment(1, 1));ActorId client = system.addActor(() -> new Actor() { @Override public void receive(ActorMessage<?> message) { if (message.value() instanceof TaskAnalysis result) System.out.println(result.summary() + " " + result.steps()); }});system.start();
system.sendViaAlias(ActorMessage.create("Create a concept for automated database backups.", 0, client, null), "AnalystPod");Direct Calls and JSON Schemas
Section titled “Direct Calls and JSON Schemas”Without AiServices, the resource actor calls the model directly, e.g. with prompts from a configuration file:
| Method | Meaning |
|---|---|
chat(system, user) |
free text answer (system may be null) |
chat(system, user, schema) |
answer as JSON text according to a JsonSchema |
chatJson(system, user, schemaName) |
answer according to a registered schema |
addJsonSchema(schema), addJsonSchemas(map) |
registers schemas under their names |
JsonSchemaUtils creates the schemas: load(Path) from a file (the name is the file name without .json), loadAll(Path) from all *.json files of a directory, fromJson(name, json) from text, and from(Class) from a record. A schema created from a record is strict: all fields are required and no further fields are allowed. Schema names may contain letters, digits, _ and -.
return new OpenAiCompatibleChatModelResourceActor(chatModelConfig) { @Override public void preStart() { super.preStart(); // creates the model and the schema registry try { addJsonSchema(JsonSchemaUtils.from(TaskAnalysis.class)); // name "TaskAnalysis" } catch (IOException e) { throw new UncheckedIOException(e); } }
@Override public void receive(ActorMessage<?> message) { String json = chatJson("You are a precise system analyst.", message.valueAsString(), "TaskAnalysis"); tell(json, 0, message.source(), message.interaction()); }};Register schemas in preStart (after super.preStart()) or in createAiServices. The registry is created in preStart, so addJsonSchema fails in the constructor.
Other Providers
Section titled “Other Providers”ChatModelResourceActor is independent of the provider. An own subclass implements createAiChatModel and returns any LangChain4j ChatModel:
public abstract class MyChatModelResourceActor extends ChatModelResourceActor { public MyChatModelResourceActor(ChatModelConfig chatModelConfig) { super(chatModelConfig); }
@Override public ChatModel createAiChatModel(ChatModelConfig chatModelConfig) { ChatModel model = ...; // ChatModel of your LangChain4j provider module, built from chatModelConfig return model; }}Remote Agent Pods
Section titled “Remote Agent Pods”ChatModelRemotePod works like ChatModelPod, but also accepts a RemotePodMessage from outside the actor system (see Remote Pods). The payload of the request is passed to the resource actor, the answer is delivered via the InternalServerCallback.
actor4j-agents-mcp currently contains only the dependency on the MCP Java SDK (io.modelcontextprotocol.sdk:mcp). There is no Actor4j integration for MCP yet.
Known Limitations
Section titled “Known Limitations”The module is a preview. Known limitations of the current state:
- No error replies: if the model call fails (timeout, HTTP error, invalid answer), the resource actor does not answer, and the client waits without limit. Catch exceptions in
receiveof the resource actor and send an own error reply. - Restart of the pod actor: the resource actor is a child of the pod actor. It is stopped and created again with the pod actor (also on undeploy and update). An answer of the old resource actor that is still on its way can still be taken as a new request, and the client of that request gets no answer. Keep
handleIoRequestfree of exceptions. OpenAiCompatibleChatModelResourceActoralways setstemperatureandtopP. Some models or servers reject one of these values.- The tests need a running model server at
localhost:9090.