Build stateful multi-agent workflows in Java — with graphs, retries, and persistence.
No orchestration code. No glue logic. Just define your agents and run.
git clone https://github.com/datallmhub/agentflow4j.git
cd agentflow4j
mvn install -DskipTests -q
mvn -pl agentflow4j-samples exec:javaRuns SupportTriageDemo — a customer-support ticket flowing through a graph: triage → specialist → policy gate → reply. Falls back to deterministic stubs offline, or calls Mistral when MISTRAL_API_KEY is set.
ExecutorAgent researcher = ExecutorAgent.builder()
.chatClient(chatClient)
.systemPrompt("Find key facts.")
.build();
ExecutorAgent writer = ExecutorAgent.builder()
.chatClient(chatClient)
.systemPrompt("Write a clear report.")
.build();
CoordinatorAgent coordinator = CoordinatorAgent.builder()
.executors(Map.of("research", researcher, "writing", writer))
.routingStrategy(RoutingStrategy.llmDriven(chatClient))
.build();
AgentResult result = coordinator.execute(
AgentContext.of("Compare Claude 4 and GPT-5"));A multi-step, stateful workflow with routing, coordination, and resilience — without writing orchestration code.
⭐ If this saves you time, consider starring the repo.
Real-world AI systems are multi-step, stateful, failure-prone, and long-running.
Spring AI gives you agent primitives. AgentFlow4J gives you a runtime.
| Spring AI | AgentFlow4J |
|---|---|
Primitives (ChatClient, tools) |
Structured runtime (AgentGraph, CoordinatorAgent) |
| Manual orchestration | Graph-based execution |
| No durable state | Typed shared state + checkpoints |
| Retry logic in user code | Built-in retry + circuit breaker |
| No resume | Interrupt + resume support |
| Agents fully trusted | Governed execution — tools, state writes and cost are gated |
Use it if your agent needs multiple LLM calls, your workflow has branches or loops, failures matter, or multiple agents must coordinate.
Skip it if you just call ChatClient once.
Agents are not implicitly trusted. Gate what they can call, what they can change, what they can spend, and when a human must step in — without writing governance glue:
// 1. restrict which tools an agent may call (gated on the executor)
ExecutorAgent paymentAgent = ExecutorAgent.builder()
.chatClient(chatClient)
.tools(webSearch, shellTool)
.toolPolicy(ToolPolicy.allowList("web.search").and(ToolPolicy.denyList("shell.execute")))
.build();
// state, cost and approval are gated on the graph
AgentGraph.builder()
.addNode("assistant", assistant)
.addNode("payment.transfer", paymentAgent)
// 2. protect sensitive state keys from being written
.statePolicy(StatePolicy.denyWriteKeys("payment.confirmed"))
// 3. cap spend per run / node / call
.budgetPolicy(BudgetPolicy.hierarchical(BudgetLimits.run(2.00), estimator, meter))
// 4. pause for a human before high-stakes nodes
.approvalGate(ApprovalGate.requireFor("payment.transfer"))
.checkpointStore(store)
.build();Each gate is opt-in with a zero-overhead default. See Tool policy, State policy, Approval gate, and Budget policy.
- Squad API — dynamic routing, minimal setup. A
CoordinatorAgentdispatches toExecutorAgents. - Graph API — explicit flows, loops, conditions, full control.
Both are covered in the docs.
Requirements: Java 17+, Spring Boot 3.x, Spring AI 1.0+. Distributed via JitPack.
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.datallmhub.agentflow4j</groupId>
<artifactId>agentflow4j-starter</artifactId>
<version>v0.6.0</version>
</dependency>repositories { maven { url 'https://jitpack.io' } }
dependencies { implementation 'com.github.datallmhub.agentflow4j:agentflow4j-starter:v0.6.0' }| Module | Purpose |
|---|---|
agentflow4j-starter |
Spring Boot auto-config, properties, Micrometer listener |
agentflow4j-core |
Minimal API (Agent, AgentContext, StateKey, AgentResult) |
agentflow4j-graph |
AgentGraph, RetryPolicy, CircuitBreakerPolicy, BudgetPolicy, checkpoint contract |
agentflow4j-squad |
CoordinatorAgent, ExecutorAgent, ReActAgent, ParallelAgent |
agentflow4j-checkpoint |
JdbcCheckpointStore, RedisCheckpointStore, Jackson codec |
agentflow4j-resilience4j |
CircuitBreakerPolicy adapter backed by Resilience4j |
agentflow4j-playground |
Drop-in web UI to chat with your Agent beans |
agentflow4j-cli-agents |
CliAgentNode — Claude Code / Codex / Gemini CLI as graph nodes |
agentflow4j-test |
MockAgent, TestGraph for LLM-free unit tests |
- Two API levels (Squad + Graph) — when to use which, with code
- Typed state —
StateKey<T>instead ofMap<String, Object> - Tool policy — allow/deny tool calls per agent, with argument-aware rules
- State policy — allow/deny writes to specific
StateKey<T>, with argument-aware rules - Approval gate — human-in-the-loop pause/resume on sensitive nodes
- Resilience & error handling — retries, circuit breaker, budget policy
- Observability — Micrometer metrics, tags, listeners
- Streaming —
Flux<AgentEvent>tokens, transitions, tool calls - Testing without an LLM —
MockAgent+TestGraph - Samples — runnable examples shipped with the repo
Tutorial: Stop your AI agent from burning $1000 overnight — governed execution end to end.
| Version | Status | Focus |
|---|---|---|
| 0.5 | shipped | Subgraphs, parallel fan-out, cancellation, typed output, retry/circuit-breaker/budget policies, JDBC/Redis checkpoint store, web playground |
| 0.6 | shipped | Governed execution: ToolPolicy, StatePolicy, ApprovalGate (allow/deny tools, guard state writes, human-in-the-loop pause/resume) |
| 1.0 | planned | API stabilization, documentation, community feedback |
| 1.1 | planned | Crew roles (CrewAI-inspired), auto-config for checkpoint backends |
| 2.0 | exploring | OpenTelemetry tracing, MCP integration, Agent-as-Tool |
It is not an official Spring project.
Contributions welcome — see CONTRIBUTING.md. Released under the Apache 2.0 License.
- LangGraph — graph-based orchestration
- CrewAI — role-based agent teams
- AWS Strands — agent patterns for Java
- Spring AI — the foundation we build on