quarkus-langchain4j-scaffolding

Quarkus + LangChain4j Scaffolding

Version: 0.7.0

1. When to use this skill

Use this skill when creating something new in a Quarkus + LangChain4j project:

• Create, scaffold, bootstrap, initialize, start, generate, or kickstart a new Quarkus + LangChain4j project or module.
• Add a new AI service (@RegisterAiService interface).
• Add a new agent or multi-agent workflow (declarative LangChain4j Agentic).
• Set up a RAG component or embedding store.
• Generate a baseline pom.xml, application.properties, project layout, or starter classes for this stack.

This skill covers how to lay things out and get them running. It does not restate coding conventions — see §9.

Required tooling (mandatory). This skill must not scaffold without it. Create the project and discover extensions through the Quarkus Agents MCP (quarkus_create, quarkus_searchTools), and call quarkus_skills for each chosen extension before writing any code — never create a Quarkus project or add an extension by hand. Use context7 for every LangChain4j and other library API lookup. If either tool is unavailable, stop and report it rather than guessing. These are project prerequisites; see CLAUDE.md §1 or AGENTS.md §1.

2. Project layout convention

Single-module Quarkus application (no multi-module reactor by default). Organize one root package into focused sub-packages:

src/main/java/<group>/<app>/
  ai/         # @RegisterAiService interfaces (AI services and agents)
  dto/        # records: inputs, reports, and event/step types
  workflow/   # agentic orchestrators + the streaming-bridge beans
  rest/       # JAX-RS resources (@Path)
  web/        # WebSocket endpoints (@WebSocket)
  rag/        # RagConfig producers (only when escalating beyond Easy RAG)
  memory/     # chat-memory store + provider (optional, persistent memory)
src/main/resources/
  application.properties
  rag/        # documents folder ingested by Easy RAG (quarkus.langchain4j.easy-rag.path)

Start with only the sub-packages a feature needs; add the rest as the project grows.

3. Dependency baseline

Create the project with quarkus_create and let it generate the shell. The generated pom.xml already imports the quarkus-bom and quarkus-langchain4j-bom platform BOMs, sets Java 25, enables the -parameters compiler flag, adds a native profile, and pulls in the test stack (quarkus-junit + rest-assured) — all at the current platform version. Do not hand-maintain any of that: quarkus_create (the same codestart generator behind code.quarkus.io) keeps it up to date.

Pass these extensions to quarkus_create:

• core: rest, rest-jackson, smallrye-openapi, websockets-next, langchain4j-ollama
• agents: add langchain4j-agentic
• RAG: add langchain4j-easy-rag

(quarkus-arc comes in automatically.) Then add the non-extension dependencies listed in templates/pom.xml.template — the dev.langchain4j embedding model (required by Easy RAG) and, for PDFs, the document parser — since project generators add only Quarkus extensions, not those.

4. AI service scaffolding

Use templates/AiService.java.template. It is a @RegisterAiService interface with @SystemMessage / @UserMessage prompts and a typed return value, plus an optional @RegisterAiService(modelName = "…") for selecting a named model. Pair it with a rest/ resource or a web/ WebSocket endpoint to expose it.

5. Agent scaffolding

Use templates/Agent.java.template. It shows the full declarative agentic shape:

• individual @Agent AI services (sub-agents) returning records;
• an orchestrator interface using @SequenceAgent / @ParallelAgent (and the @SupervisorAgent + @SupervisorRequest variant for routing) with @Output assembling the result from the AgenticScope;
• an @ApplicationScoped streaming bridge that runs the blocking workflow on a virtual thread and emits progress over a Mutiny Multi;
• the @WebSocket endpoint that delegates to the bridge.

Requires the quarkus-langchain4j-agentic extension. Call quarkus_skills for it before writing the workflow.

6. RAG pipeline scaffolding

Use templates/RagSetup.java.template. Default to Easy RAG: add quarkus-langchain4j-easy-rag plus an in-process embedding model (langchain4j-embeddings-all-minilm-l6-v2), drop documents into the folder referenced by quarkus.langchain4j.easy-rag.path, and let Quarkus ingest them on startup — no retriever code required. The template also includes a commented, opt-in manual path (a CDI-produced EmbeddingStore + EmbeddingStoreContentRetriever + RetrievalAugmentor) to use only when a project needs control Easy RAG does not provide.

7. application.properties baseline

Use templates/application.properties.template. It configures the Ollama provider with a local default model (cloud models shown as comments), a named smaller model for cheap subtasks, generous timeouts, request/response logging, disabled Dev Services, and the Easy RAG documents path.

8. After scaffolding

Run and verify through the Quarkus Agents MCP (start dev mode, run tests via the Dev MCP tools) rather than invoking Maven directly.

9. Cross-reference

For coding conventions to apply once scaffolding is done — Java language level, virtual threads, records/sealed/pattern matching, declarative AI services, streaming, RAG, testing — see the project's CLAUDE.md (Claude) or AGENTS.md (Codex). This skill does not duplicate those conventions.