ARA — Agent Runtime Architecture for Java

Build autonomous AI agents and multi-agent systems in plain Java 21. LLM integration, tool calling, deterministic I/O contracts, RAG and human-in-the-loop — no annotations, no reflection, no Spring, no Kotlin.

Quick start · Documentation · Examples · Website · Discussions

ARA is a Java 21 agent runtime: a place where agents actually run, with sessions, memory, execution strategies, cost budgets, approval gates and a full execution trace — not a thin wrapper around a chat completion endpoint.

It works with OpenAI, Anthropic, Ollama, Mistral, LM Studio, Groq and any OpenAI-compatible endpoint, and it is published on Maven Central as io.github.xmor:ara-runtime.

Your code ──▶ AraRuntime ──▶ Agent (strategy + contract + session)
                                │
                     ┌──────────┼───────────┐
                     ▼          ▼           ▼
                 LlmClient   Tools      Retriever
             OpenAI/Claude/  (yours,   (in-memory
             Ollama/Mistral  parallel   or Qdrant)
                             on vthreads)

1. Add the dependency (check the badge above for the latest version):

<dependency>
    <groupId>io.github.xmor</groupId>
    <artifactId>ara-runtime</artifactId>
    <version>1.0.3</version>
</dependency>

The version shown above is the latest published release and is recommended for production use. During development and testing, you may also use the next -SNAPSHOT version, provided that the corresponding snapshot repository is configured.

2. Run an agent offline. ScriptedLlmClient replays canned responses, so the first run needs no key, no network and no local model:

import io.ara.runtime.AraRuntime;
import io.ara.runtime.stubs.ScriptedLlmClient;

try (var runtime = AraRuntime.builder()
        .llmClient(ScriptedLlmClient.script()
                .thenFinalAnswer("Virtual threads are lightweight JVM threads.")
                .build())
        .build()) {

    System.out.println(runtime.askText("Explain virtual threads"));
}

Virtual threads are lightweight JVM threads.

That is the whole loop, runnable as basics/MinimalAgentExample. What just happened: runtime.askText(...) runs the prompt on a shared default agent and returns the answer string directly — the runtime auto-started on first use, and close() shuts it down. The default react strategy called the LLM, ended at a final answer, and returned it.

When the agent needs a role, a system prompt, tools or a specific model, create one explicitly and call agent.execute(...): you get the full AgentResponse — iteration count, token usage, cost and step trace — instead of just the string. AgentConfig.of("assistant", "...") is the one-line form; reach for AgentConfig.defaults() as soon as a third field is involved. See basics/AraSimpleExample for that fuller shape.

3. Swap in a real model — one line changes, everything else stays:

LlmClient gpt4o = AraLlmClientFactory.openAi()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o")
        .build();

// or fully local, no API key:
LlmClient llama = AraLlmClientFactory.ollama()
        .model(OllamaLlmClient.Models.LLAMA_3_2)
        .build();

Requires Java 21+ and Maven 3.9+. Add ara-adapters for real providers → Providers guide. Models can also be declared in ara.yml and loaded with AraLlmClientFactory.fromConfig → Models in a configuration file.

git clone https://github.com/xmor/ara.git && cd ara
mvn clean install -DskipTests

crew/CodeReviewCrewExample is the same runtime doing multi-agent work. Three specialist reviewers — security, performance, style — run concurrently on virtual threads, then a lead agent merges their findings into a prioritised report. The fan-out is a pipeline step; there are no threads to wire up:

AgentPipeline pipeline = AgentPipeline.builder()
        .parallel("review", List.of(security, performance, style),
                  runtime.executor(), AgentChain.MergeStrategy.joining("\n\n"))
        .step("synthesize", lead)
        .build();

AraAgent crew = PipelineAgents.of(AgentId.of("code-review-crew"), config, pipeline);

Run it offline with main(): the console shows the three reviewers starting together on different threads and finishing in an order decided by their work, then the lead's report and the crew's token/cost summary. Pass live to run the same crew against a real model.

• Plain Java, no magic. Pure interfaces — zero annotations, zero reflection, no Kotlin runtime, no Spring. The call stack you debug is the call stack you wrote.
• Deterministic I/O contracts. AgentContract validates, sanitises and transforms in plain Java before and after every call, spending zero tokens.
• Java 21 by design. Virtual threads are the concurrency model, not an option: when the LLM asks for several tools at once they are dispatched in parallel automatically, with no executor to wire up.
• A runtime, not a toolkit. Execution strategies, FSM pipelines, session isolation, human-in-the-loop and cost budgets come in the box rather than assembled from parts.
• Built on LangChain4j, not against it. Provider integration is inherited through ara-adapters, so you get LangChain4j's provider coverage plus the runtime on top.

• Human-in-the-loop as a runtime primitive — an ApprovalGate wired into the tool dispatch chain; ApprovalDecision is a sealed interface, so approve / reject / modify is exhaustive at compile time. → HITL guide
• A per-caller tool catalog — a tool that declares requiredScopes() is hidden from the model's catalog for any task that doesn't carry the scopes, before the LLM ever reads it; scopes come from the task's execution context, attenuated through delegation like any other call. → Tools guide
• Conversation and self-correction inside the loop — "respact" asks a clarifying question mid-task and resumes on the same session; "reflact" recovers from a failed tool call without discarding what the run already accomplished.
• Private per-agent data — AgentInstanceContext holds API keys or tenant ids that both prompt shaping and tool execution can read, and that never reach the LLM.
• Per-agent cost accounting — unit prices and a costBudget cap are part of the LLM profile, not an afterthought.
• Multimodal input — attach a PDF or an image and the model reads it natively; a provider that can't handle the type fails loudly before the request goes out.
• Tools that return images — a tool can hand the model an image (a crop, a rendered page) and the model looks at it; the one it cites in its answer comes back to the caller as an artifact. See Media returned by tools.
• A full execution trace, always — AgentResponse.steps() records the reasoning and tool trace on every run, including the partial trace when a run fails.
• LLM failover and circuit breaking — an ordered model chain with a passive breaker per candidate, so an outage stops costing a timeout per request.

• Single agents on any LLM (OpenAI, Anthropic, Ollama, Mistral, LM Studio, Groq, …)
• Deterministic I/O contracts: sanitize input, validate output, strip markdown fences — zero tokens consumed
• Multi-agent pipelines with conditional routing and FSM-style state machines
• Parallel specialist crews: a fan-out step runs several agents at once on virtual threads and merges their answers with a pluggable strategy
• Classify-and-act triage: one classification decides the single worker that handles the task, escalating from keyword rules to a model to a human as confidence drops — the whole dispatch table loadable as a JSON document
• Tool calling from LLM responses, including parallel dispatch on virtual threads
• Conversational agents that ask clarifying questions mid-task ("respact") and self-correcting ones that recover from failed tool calls without restarting ("reflact")
• RAG as a strategy decorator — retrieval before every LLM call, no tool configuration needed
• Fully offline testing with ScriptedLlmClient and AssociativeLlmClient

class WeatherTool implements AraTool {
    @Override public String toolId()      { return "get_weather"; }
    @Override public String description() { return "Returns current weather for a city."; }
    @Override public String argumentSchema() {
        return """
               {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}
               """;
    }
    @Override public ToolResult execute(String argumentJson) {
        return ToolResult.success(toolId(), "Milan: Sunny, 22°C");
    }
}

AgentConfig config = AgentConfig.defaults()
        .agentType("travel-assistant")
        .plannerStrategy("react")
        .enabledTools(List.of("get_weather"))
        .build();

AgentContract contract = AgentContract.builder()
        .addInputProcessor(InputSanitizer.instance())      // blocks prompt-injection patterns
        .addInputProcessor(ContentTruncator.to(4000))
        .addPromptShaper(PromptTemplate.withDefaults(Map.of("date", LocalDate.now().toString())))
        .outputSchema(JsonSchemaValidator.forOutput(SCHEMA))
        .addOutputProcessor(MarkdownFenceStripper.instance())
        .build();

AraAgent agent = runtime.createAgent(config, contract);

AgentPipeline pipeline = AgentPipeline.fsmBuilder()
        .state("draft",  draftAgent)
        .state("review", reviewAgent)
        .state("revise", reviseAgent)
        .state("done",   doneAgent)
        .initial("draft")
        .terminal("done")
        .transition("draft",  "review")
        .transition("review", execution -> execution.lastOutput().contains("APPROVED") ? "done" : "revise")
        .transition("revise", "review")
        .maxSteps(12)
        .build();

IntentRouter router = IntentRouter.onField("intent")
        .route("BILLING", "billing")
        .route("TECH",    "tech")
        .confidenceField("confidence")
        .escalateBelow(0.7, "human")       // low confidence → escalate, not guess
        .orElse("fallback");

AgentPipeline triage = AgentPipeline.builder()
        .classify("classify", classifierAgent, router)
        .worker("billing", billingAgent)
        .worker("tech",    techAgent)
        .worker("human",   humanReviewAgent)
        .worker("fallback", fallbackAgent)
        .build();

All strategies support cooperative cancellation and record a full execution trace, including on failure paths. → Strategy README

ara-gateway — an optional HTTP layer (Javalin/Jetty) for HTTP-side HITL approvals — ships separately and is not part of this build.

Everything below lives in ara-examples and runs with main().

The guides form a path, not a reference dump. Start at the top and stop when your use case is covered.

Issues, discussions and PRs are welcome — including README and documentation fixes, which are the easiest first contribution.

Code style is enforced through docs/CODING-GUIDELINES.md: simplicity first, no premature abstractions, short single-responsibility functions, honest naming. Read it before opening a PR.

ARA is developed with heavy AI assistance under human architectural review.

If ARA is useful to you, a ⭐ helps other Java developers find it.

Apache 2.0 — see LICENSE.