Build, govern and operate AI agents without introducing a second runtime.
Spring AI provides model access. AgentFlow4J lets you build, govern and run multi-agent systems — human approvals, checkpoints, budget controls and tool policies, built for Spring.
git clone https://github.com/datallmhub/agentflow4j.git
cd agentflow4j
mvn install -DskipTests -q
mvn -pl agentflow4j-samples exec:javaRuns SupportTriageDemo by default — a business example built with AgentFlow4J: a support ticket flowing through a governed graph (triage → specialist → policy gate → reply), with ToolPolicy and ApprovalGate active. This is one sample use case to illustrate the framework, not the framework itself. No API key required; falls back to deterministic stubs, or calls Mistral when MISTRAL_API_KEY is set.
Other demos to explore:
| Demo | What it shows |
|---|---|
SupportTriageDemo |
Multi-agent graph with ToolPolicy + ApprovalGate |
BudgetAwareRoutingDemo |
BudgetPolicy switching agents at runtime |
ResearchSquad |
ParallelAgent fan-out + result aggregation |
AdvancedGraphDemo |
Loops, conditions, typed state |
MinimalPipeline |
Smallest possible AgentGraph — two nodes, one edge |
# Run any demo directly
mvn -pl agentflow4j-samples exec:java -Dexec.mainClass=io.github.datallmhub.agentflow4j.samples.BudgetAwareRoutingDemoOne real workflow built with AgentFlow4J — a customer-support triage app. This is one sample use case, not the framework itself; you compose your own agents and graphs the same way.
▶ Live demo: https://huggingface.co/spaces/datallmhub/multi-agent-customer-ops
// Define your agents
ExecutorAgent analyst = ExecutorAgent.builder()
.chatClient(chatClient)
.systemPrompt("Analyse this request.")
.toolPolicy(ToolPolicy.allowList("search", "fetch"))
.build();
// Compose a governed graph
AgentGraph graph = AgentGraph.builder()
.addNode("analyse", analyst)
.budgetPolicy(BudgetPolicy.perRun(0.50, estimator, meter))
.approvalGate(ApprovalGate.requireFor("analyse"))
.checkpointStore(new JdbcCheckpointStore(dataSource))
.build();
AgentResult result = graph.run(AgentContext.of("Process this refund request"));ToolPolicy restricts which tools the agent can call. BudgetPolicy caps spend at $0.50 per run. ApprovalGate pauses execution until a human approves. CheckpointStore persists graph state — the run resumes from the last completed node after a restart.
⭐ If this saves you time, consider starring the repo.
AgentFlow4J is built around four ideas:
| Concept | What it means | AgentFlow4J |
|---|---|---|
| Agents | Autonomous units that perform tasks | ExecutorAgent, ReActAgent, ParallelAgent |
| Teams | Agents working together, coordinated | CoordinatorAgent, AgentGraph |
| Rules | What agents can do, spend, or change | ApprovalGate, BudgetPolicy, ToolPolicy, StatePolicy |
| Execution | How runs survive failures and restarts | RetryPolicy, CheckpointStore, RunLog, Micrometer |
Spring AI gives you the primitives to call a model. AgentFlow4J gives you the runtime to orchestrate agents safely.
| Spring AI | AgentFlow4J |
|---|---|
| Talk to AI models | Coordinate multiple agents |
| Prompts & tools | Agent teams with routing |
| Tool calling | Governance — who can call what |
ChatClient |
AgentGraph execution |
| RAG | Checkpointing & resume |
| Model providers | Retry, resilience, audit trail |
Spring AI provides AI capabilities. AgentFlow4J provides agent execution.
LangGraph, ADK, CrewAI and AutoGen bring their own runtimes. AgentFlow4J runs on the Spring stack your team already owns, already secures, and already operates.
Use it if your workflow spans multiple agents, failures matter, costs need capping, or a human must approve before an action executes.
Skip it if you make a single ChatClient call.
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:
ExecutorAgent paymentAgent = ExecutorAgent.builder()
.chatClient(chatClient)
.tools(webSearch, shellTool)
.toolPolicy(ToolPolicy.allowList("web.search").and(ToolPolicy.denyList("shell.execute")))
.build();
AgentGraph.builder()
.addNode("assistant", assistant)
.addNode("payment.transfer", paymentAgent)
.statePolicy(StatePolicy.denyWriteKeys("payment.confirmed"))
.budgetPolicy(BudgetPolicy.hierarchical(BudgetLimits.run(2.00), estimator, meter))
.approvalGate(ApprovalGate.requireFor("payment.transfer"))
.checkpointStore(store)
.build();ToolPolicy allows web.search and blocks shell.execute on the agent. StatePolicy prevents any agent from writing payment.confirmed directly. BudgetPolicy caps the total run at $2.00. ApprovalGate pauses before payment.transfer executes — a human must approve. Each gate is opt-in with a zero-overhead default.
See Tool policy, State policy, Approval gate, 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.7.0</version>
</dependency>repositories { maven { url 'https://jitpack.io' } }
dependencies { implementation 'com.github.datallmhub.agentflow4j:agentflow4j-starter:v0.7.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
- LLM providers — swap between Mistral, OpenAI, Claude, Gemini, Ollama with two lines of config
- 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
- Recipe: approval via Slack — async, non-blocking, ~30 lines
- Resilience & error handling — retries, circuit breaker, budget policy
- Recipe: durable runs — crash mid-workflow, resume from the last checkpoint
- Observability — Micrometer metrics, tags, listeners
- Run log — structured, replayable execution timeline per run
- Streaming —
Flux<AgentEvent>tokens, transitions, tool calls - Testing without an LLM —
MockAgent+TestGraph - Samples — runnable examples shipped with the repo
Cookbook: AgentFlow4J Cookbook — standalone, copy-paste recipes (RAG agent, support-ticket triage, web research, Slack bot, batch document processing), each a self-contained Maven module that runs locally against Ollama.
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 |
| 0.7 | shipped | Adaptive execution: reason-aware retry (FailureClassifier), cost-aware routing (BudgetAwareRouter) |
| 1.0 | in progress | API stabilization pass · lifecycle hooks (onCheckpoint, onToolCall, onFailure) · MCP compatibility · OpenHands integration adapter · Parallel-DAG execution |
| 2.0 | exploring | Temporal-like interruption, compensation/saga, OpenTelemetry tracing |
It is not an official Spring project.
Contributions welcome — see CONTRIBUTING.md. Released under the Apache 2.0 License.