Runnable examples for building multi-agent LLM workflows in Java — RAG, support-ticket triage, web research, Slack bots, batch document processing, and cost-aware routing — with af4j and Spring AI.
If you want to orchestrate governed, production-ready multi-agent workflows on the JVM — with budget caps, tool policies, human approval gates, and checkpoint-based recovery — this is a copy-paste starting point. Every recipe is a self-contained Maven module: clone, pick a recipe, run it. Local-first — each one runs against Ollama with zero API keys and zero cost, and swaps to OpenAI, Mistral, or Anthropic by changing one Spring AI starter dependency.
Java has a vibrant LLM ecosystem (LangChain4j, Spring AI, Embabel, af4j) but most tutorials stop at single-agent chatbots. Real production AI systems need more:
- multiple specialised agents coordinating on one task (triage → specialist → review)
- durable state that survives restarts and crashes
- governance — budget caps, tool allowlists, human-in-the-loop approval gates
- observable execution traces for debugging non-deterministic LLM behaviour
This cookbook shows those production patterns end-to-end in idiomatic Java + Spring, with code you can lift straight into your own project. No Python, no microservice sidecar, no YAML DSL — just typed Java on the JVM you already run.
| # | Recipe | What you'll learn |
|---|---|---|
| 1 | RAG agent | Retrieval-augmented generation with a retriever agent + answerer agent + cited sources, all governed by a budget cap |
| 2 | Support ticket triage | Classify customer tickets, route to specialist agents, enforce a content policy, draft a reply — with ToolPolicy denylists |
| 3 | Web research agent | Real-time research over Hacker News with a parse → search → classify → synthesize graph, streaming tokens via Flux<AgentEvent> |
| 4 | Slack bot | Multi-agent Slack assistant — listens to mentions, runs a planning + executor graph, posts a threaded reply |
| 5 | Batch document processor | Process N documents through the same agent graph with checkpointing — resume from the last successful doc after a crash |
| 6 | Cost-aware routing | Degrade a squad from a premium model to a cheaper fallback as the budget depletes with RoutingStrategy.budgetAware, and retry only what's worth retrying via a reason-aware RetryPolicy (transient vs permanent vs over-budget) |
| 7 | Governed MCP agent | Use the tools of an MCP server from an AgentGraph: a ToolPolicy refuses risky calls before they reach the server, every call is audited, and the model is told when it was refused |
| 8 | Self-correcting writer | A bounded revise-until-valid loop: a writer revises its draft until a deterministic reviewer accepts it, and escalates to a human after three attempts |
| 9 | LLM as a judge | Score an answer with a judge agent that returns a typed verdict, route on the score (send, revise, escalate) and cap what judging costs |
| 10 | Parallel research squad | Fan out three researchers over one brief and join their findings, with a shared budget cap and an approval gate that pauses only its own branch |
| 11 | Governed OpenHands workflow | Delegate a ticket to the OpenHands coding agent behind an approval gate, a cost cap and checkpoints, and bring the pull request back into the workflow |
- Java 17+ (Adoptium Temurin recommended)
- Maven 3.9+ (or use the wrapper)
- Ollama running locally (optional — recipes fall back to stubs when Ollama isn't reachable)
Every recipe also runs in stub mode without Ollama so you can verify the wiring before adding an LLM.
git clone https://github.com/datallmhub/agentflow4j-cookbook.git
cd agentflow4j-cookbook
# Build everything (uses JitPack to fetch af4j)
mvn -DskipTests install
# Run a single recipe (no LLM required — falls back to stubs)
mvn -pl 01-rag-agent exec:javaThe cookbook talks to Ollama by default — free, offline, no API key.
# 1. Install Ollama (macOS / Linux)
brew install ollama # or: curl -fsSL https://ollama.com/install.sh | sh
# 2. Start the daemon (defaults to http://localhost:11434)
ollama serve &
# 3. Pull a small, fast chat model (~2 GB)
ollama pull llama3.2:3bThat's it — every recipe auto-detects Ollama on localhost:11434 and runs in LIVE mode.
Two env vars, both optional:
| Variable | Default | Notes |
|---|---|---|
OLLAMA_HOST |
http://localhost:11434 |
Use http://localhost:11435 (etc.) if port 11434 is taken (e.g. LM Studio) |
OLLAMA_MODEL |
llama3.2:3b |
Any model you've pulled — ollama list to check |
# Example: bigger model
ollama pull llama3.1:8b
OLLAMA_MODEL=llama3.1:8b mvn -pl 01-rag-agent exec:java
# Example: Ollama on a non-default port (when 11434 is in use)
OLLAMA_HOST=http://localhost:11435 mvn -pl 01-rag-agent exec:javaA fast TCP probe at startup decides between LIVE and STUB mode — no hang if Ollama isn't running.
The recipes are intentionally Ollama-coupled to keep the cookbook clone-and-run. To use a hosted provider, swap the Spring AI starter dependency in the recipe's pom.xml (e.g. spring-ai-starter-model-openai) and replace the OllamaChatModel builder block with the equivalent for your provider. The rest of the recipe (graph, state, policies) is unchanged.
agentflow4j-cookbook/
├── pom.xml # Parent POM, BOM imports, shared deps
├── 01-rag-agent/ # Each recipe is a standalone Maven module
│ ├── pom.xml
│ ├── README.md # ← detailed walkthrough
│ └── src/main/java/...
├── 02-support-ticket-triage/
├── 03-web-research-agent/
├── 04-slack-bot/
├── 05-batch-document-processor/
└── 06-cost-aware-routing/
- af4j — the multi-agent orchestration framework these recipes use
- af4j docs — concepts, governance, resilience, observability
- Two API levels — when to use the high-level squad API vs the low-level graph API
- Stop your agent burning $1000 overnight — tutorial on the four governance gates
- Spring AI reference — the Spring abstraction over LLM providers
How does this compare to LangGraph or LangChain?
af4j is not a port of LangGraph. It's a governed orchestration runtime — the difference is BudgetPolicy, ToolPolicy, ApprovalGate, and FailureClassifier built into the execution model, not bolted on top. If you're on Spring and need production governance over your agent workflows, these recipes show what that looks like end to end.
Do I need an OpenAI API key? No. Every recipe runs against a local Ollama model out of the box. Cloud providers (OpenAI, Mistral, Anthropic) are a one-dependency swap.
Can I use these in production? The patterns (graph composition, typed state, governance gates, checkpoint-based resume) are production-grade. The sample data is illustrative — replace the in-memory stores with your real vector store / database.
java · llm · ai-agents · multi-agent · agent-orchestration · spring-ai · spring-boot · rag · llm-governance · langchain4j · ollama · generative-ai · agentflow4j
Have a use case that isn't covered? Open an issue describing the scenario — we add recipes that solve concrete production problems, not toy demos.
Apache License 2.0 — same as af4j. See LICENSE.