AgentFlow4J

Build governed, stateful multi-agent workflows in Java — orchestration, persistence, and runtime observability.

No orchestration boilerplate. No hidden execution. Just define your agents and run.

---

🚀 Try it in 30 seconds (no API key)

git clone https://github.com/datallmhub/agentflow4j.git
cd agentflow4j
mvn install -DskipTests -q
mvn -pl agentflow4j-samples exec:java

Runs 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.

---

🎬 Example in action

One 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

---

⚡ In 60 seconds

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.

---

🧠 Why AgentFlow4J?

Spring AI gives you LLM primitives (ChatClient, tools). AgentFlow4J gives you a structured runtime for multi-step systems. Going from single prompts to multi-agent workflows makes execution stateful, failure-prone, and hard to inspect. AgentFlow4J provides the execution graph, durable state, and governance gates to run those workflows safely — all in idiomatic Java, no sidecar, no YAML.

Spring AI	AgentFlow4J runtime
Primitives (ChatClient, tools)	Structured execution (AgentGraph, CoordinatorAgent)
Manual orchestration glue	Graph-based execution & dynamic routing
No durable state	Typed shared state (StateKey<T>) + checkpoints
Retry logic in user code	Built-in retry & circuit-breaker policies
No resume	Interrupt & resume from the last valid checkpoint
Agents fully trusted	Governed execution — tool, state-write and budget gates

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.

---

🛡 Governed by default

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.

---

🧩 Two levels of control

• Squad API — dynamic routing, minimal setup. A CoordinatorAgent dispatches to ExecutorAgents.
• Graph API — explicit flows, loops, conditions, full control.

Both are covered in the docs.

---

🛠 Installation

Requirements: Java 17+, Spring Boot 3.x, Spring AI 1.0+. Distributed via JitPack.

Maven

<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>

Gradle

repositories { maven { url 'https://jitpack.io' } }
dependencies { implementation 'com.github.datallmhub.agentflow4j:agentflow4j-starter:v0.7.0' }

Modules

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

---

📚 Documentation

• 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 of Map<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.

---

📈 Roadmap

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

---

📝 Note on scope

It is not an official Spring project.

---

🤝 Contributing & License

Contributions welcome — see CONTRIBUTING.md. Released under the Apache 2.0 License.