Skip to content

Agents

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.

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:

  1. A client sends a message to the pod (alias = domain).
  2. The pod forwards the value to its resource actor and marks the reply as pending (Reply.pending()).
  3. The resource actor calls the model and sends the result back to the pod, with the same interaction.
  4. The pod creates the reply in handleIoRequest and sends it to the client.
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

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.

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).

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.

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");

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.

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;
}
}

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.

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 receive of 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 handleIoRequest free of exceptions.
  • OpenAiCompatibleChatModelResourceActor always sets temperature and topP. Some models or servers reject one of these values.
  • The tests need a running model server at localhost:9090.