Build AI agents you can trust in production.
AF4J 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.hierarchical(BudgetLimits.run(0.50), estimator, meter))
.approvalGate(ApprovalGate.requireFor("analyse"))
.checkpointStore(new JdbcCheckpointStore(jdbcTemplate, txManager, codec))
.build();
AgentResult result = graph.invoke(AgentContext.of("Process this refund request"),
RunOptions.ofRunId("refund-4521"));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: graph.resume("refund-4521", ResumeOptions.ofApproval("analyse")) continues the run after the approval, or 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 | AF4J |
|---|---|---|
| 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 |
| Parallel branches | Run independent branches at once, join deterministically | fan-out on direct edges, maxConcurrency, StateConflictException |
| MCP tools | Govern the tools an MCP server exposes | ExecutorAgent.toolProviders(...) |
| Coding agent | Delegate a coding task, keep the governance | OpenHandsAgent |
| Observability | Metrics, run logs, lifecycle hooks, streaming events | Micrometer, RunLog, AgentListener, 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.
Since 1.0 the public API of agentflow4j-core, agentflow4j-graph, agentflow4j-checkpoint, agentflow4j-squad and agentflow4j-test is stable: a breaking change waits for 2.0. Types marked @Experimental are the exception, including the agentflow4j-openhands module, which tracks the OpenHands V1 API.
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 - Parallel branches: fan-out, join, state merge, and an approval that pauses one branch
- MCP tools: MCP tools under a
ToolPolicy, with the audit trail - OpenHands: delegate a coding task, asynchronously and idempotently
- 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
- Migration guides: 0.7 to 0.8, 0.8 to 0.9
Cookbook: AF4J Cookbook: eleven standalone, copy-paste recipes (RAG agent, ticket triage, web research, Slack bot, batch processing, cost-aware routing, governed MCP agent, self-correcting writer, LLM as a judge, parallel research squad, governed OpenHands workflow), 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) |
| 0.8 | shipped | API stabilization: RunOptions / ResumeOptions, governed streaming, lifecycle hooks, MCP tool providers |
| 0.9 | shipped | Parallel execution: fan-out and join, deterministic state merge, approval that pauses one branch, reruns that skip completed nodes |
| 0.10 | shipped | OpenHands: delegate a coding task from a node, asynchronously and idempotently |
| 1.0 | shipped | Stable API: core, graph, checkpoint, squad and test are frozen until 2.0 |
| 1.x | next | Lifecycle hook coverage, a streaming scheduler for parallel branches, more cookbook recipes |
| 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.