Inspired by wasm-agents-blueprint and wasm-browser-agents-blueprint experimenting with WebAssembly agents, we wanted to explore running these powerful AI systems within an alternative, and extremely popular runtime: the Java Virtual Machine (JVM).
The JVM is one of the most widely used systems in the world, powering everything from enterprise applications to mobile development. Its platform independence enables applications to run seamlessly across diverse operating systems without modification, while its robust memory management with automatic garbage collection simplifies development and reduces memory leaks. The JVM's security model enforces strict policies including bytecode verification and sandboxing, and it supports multiple programming languages beyond Java, fostering a versatile and expansive ecosystem. These attributes make it an ideal platform for deploying AI agents at scale.
This blueprint demonstrates how to build AI agents using WebAssembly modules within a Java application, leveraging the JVM's robust ecosystem and enterprise-grade capabilities. You can run agents written in multiple languages (Rust, Go, Python, JavaScript) seamlessly within the JVM, combining the performance benefits of WebAssembly with the reliability and maturity of the Java platform.
LangChain4j proves to be exceptionally effective for Java-based AI applications, providing seamless integration with both local and cloud-based language models. The framework's modular architecture makes it easy to switch between different model providers, while its type-safe API ensures reliable communication with AI services. We've tested it with TinyLlama-1.1B-Chat-v1.0, which works well for demo purposes and can run efficiently on development machines. The integration with JLama (Java implementation of LLaMA) further enhances the local model experience, offering optimized inference and memory management specifically designed for the JVM environment. Both JLama and Chicory run entirely within the JVM boundaries, ensuring everything is self-contained in the JVM.
Want a quick preview? Here's a short screen recording of the app in action:
- Java 21+ (required for Vector API support)
-
Clone the repository:
git clone https://github.com/mozilla-ai/wasm-java-agents-blueprint.git cd wasm-java-agents-blueprint -
Start the application in development mode:
./mvnw quarkus:dev
-
Test the agents:
# Test Rust agent curl -X PUT "http://localhost:8080/hello/rust/en/Alice" \ -H "Content-Type: text/plain" \ --data "Tell me about yourself" # Test Go agent curl -X PUT "http://localhost:8080/hello/go/fr/Bob" \ -H "Content-Type: text/plain" \ --data "What can you do?" # Test Python agent curl -X PUT "http://localhost:8080/hello/py/de/Charlie" \ -H "Content-Type: text/plain" \ --data "Explain your capabilities" # Test JavaScript agent curl -X PUT "http://localhost:8080/hello/js/es/Diana" \ -H "Content-Type: text/plain" \ --data "How do you work?"
JVM Mode:
./mvnw package
java -jar target/quarkus-app/quarkus-run.jarThis containerized option is convenient but currently slower than running directly on the host.
-
Build the image:
./mvnw package -DskipTests -Dquarkus.container-image.build=true -Dquarkus.container-image.platforms=linux/amd64
-
Run the container:
docker run --platform linux/amd64 -p8080:8080 wasm-java-agents-blueprint:1.0.0-SNAPSHOT
-
Or use the pre-built image:
docker run --platform linux/amd64 -p8080:8080 docker.io/andreatp/wasm-java-agents-blueprint:1.0.0-SNAPSHOT
Note for ARM hosts
- If amd64 emulation isn't available, enable it once:
docker run --rm --privileged tonistiigi/binfmt --install amd64
This blueprint showcases a multi-language WebAssembly architecture running within the Java Virtual Machine:
- Rust: High-performance systems programming with memory safety
- Go: Efficient concurrent operations and clean syntax
- Python: Flexible scripting via PyO3 compilation to WASM
- JavaScript: Dynamic scripting with QuickJS integration
- Quarkus Framework: Modern, cloud-native Java framework with fast startup times
- LangChain4j: Java AI framework for LLM integration
- Chicory: Pure Java WebAssembly runtime
- LLM Integration: Built-in support for local and cloud-based language models
- Context-Aware Processing: Agents receive contextual information about greetings and user prompts
- Multi-Language Support: Agents can respond in different languages based on user preferences
- RESTful API: Simple HTTP interface for agent interaction
Default local model
- This blueprint uses a local, in-JVM model by default via LangChain4j + JLama:
mariofusco/TinyLlama-1.1B-Chat-v1.0-JQ4(upstreamTinyLlama-1.1B-Chat-v1.0quantized to 4 bits). - You can change the model in
src/main/resources/application.propertiesvia:quarkus.langchain4j.jlama.chat-model.model-name=<provider/model> - Other providers (e.g., cloud LLMs) can be enabled by switching the LangChain4j provider configuration.
wasm-java-agents-blueprint/
├── src/main/java/org/acme/getting/started/
│ ├── GreetingResource.java # REST API endpoints
│ ├── ChatService.java # LLM integration service
│ ├── RustGreetingService.java # Rust WASM agent
│ ├── GoGreetingService.java # Go WASM agent
│ ├── PythonGreetingService.java # Python WASM agent
│ └── JsGreetingService.java # JavaScript agent
├── src/main/resources/demos/
│ ├── rust/ # Rust WASM modules
│ ├── go/ # Go WASM modules
│ ├── python/ # Python WASM modules
│ └── js/ # JavaScript modules
└── scripts/ # Build scripts for WASM modules
Compiling Rust to WebAssembly is a blissful experience.
Compiled to WebAssembly thanks to TinyGo.
Leveraging Extism SDK and the Python PDK (which uses PyO3)
JavaScript is compiled and executed on the fly thanks to QuickJS4j.
The project includes the scripts used to build WASM modules from source:
./scripts/build-rust.sh
./scripts/build-go.sh
./scripts/build-python.shThere are also scripts to download toolchains and dependencies. You might need to tweak those to match your OS/architecture.
- Multi-Language Support: Run agents written in Rust, Go, Python, and JavaScript
- Enterprise Java: Built on Quarkus for cloud-native deployment
- WebAssembly Integration: Seamless WASM module execution within the JVM
- LLM Integration: Built-in support for local and cloud language models
- RESTful API: Simple HTTP interface for agent interaction
For detailed guides and advanced usage, check out our comprehensive documentation:
- Getting Started: Quick setup and first steps
- Architecture Overview: System design and component interactions
- Customization Guide: Tailor the blueprint to your needs
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Contributions are welcome! To get started, you can check out the CONTRIBUTING.md file.
This Blueprint is built on top of:
- Quarkus - Modern Java framework
- LangChain4j - Java AI framework
- Chicory - Pure Java WebAssembly runtime