Build AI agents you can trust in production.
AgentFlow4J is a framework and runtime for governed, stateful multi-agent systems on the JVM.
Human approvals · Checkpoints · Budget controls · Tool policies · Durable execution
- Build multi-agent workflows with explicit orchestration
- Persist execution across failures and restarts
- Add human approval where it matters
- Control tool access and AI spend
- Run natively on the JVM and Spring ecosystem
// 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.
git clone https://github.com/datallmhub/agentflow4j.git
cd agentflow4j
mvn install -DskipTests -q
mvn -pl agentflow4j-samples exec:javaRuns SupportTriageDemo by default: a governed multi-agent workflow with ToolPolicy and ApprovalGate active. No API key required; falls back to deterministic stubs, or calls Mistral when MISTRAL_API_KEY is set.
See all samples to explore other demos.
▶ See it in action: live demo of a sample implementation, a governed multi-agent customer-support workflow.
| Capability | What it does | AgentFlow4J |
|---|---|---|
| Multi-agent orchestration | Build agent teams with routing and fan-out | AgentGraph, CoordinatorAgent, ParallelAgent |
| Governance | Control what agents can call, change, or spend | ToolPolicy, StatePolicy, BudgetPolicy, ApprovalGate |
| Durable execution | Survive restarts, resume from last checkpoint | JdbcCheckpointStore, RedisCheckpointStore |
| Human-in-the-loop | Pause before critical actions, resume on approval | ApprovalGate |
| Resilience | Classify failures, retry smart, route to fallback | RetryPolicy, FailureClassifier, BudgetAwareRouter |
| Observability | Metrics, run logs, streaming events | Micrometer, RunLog, Flux<AgentEvent> |
Two API levels: Squad API for dynamic routing with minimal setup, Graph API for explicit flows, loops and full control. See Two API levels.
See Getting started for Maven/Gradle setup and module reference.
- 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 |
Contributions welcome: see CONTRIBUTING.md. Released under the Apache 2.0 License. Not an official Spring project.