From 5c4b7094f0082c9a141e85a532e3c5da126f4039 Mon Sep 17 00:00:00 2001 From: agentflow4j Date: Mon, 28 Sep 2026 21:52:47 +0200 Subject: [PATCH 1/2] docs: write the framework name as AF4J in the README --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2a415eb..3bdded6 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -# af4j +# AF4J **Build AI agents you can trust in production.** -af4j is a framework and runtime for governed, stateful multi-agent systems on the JVM. +AF4J is a framework and runtime for governed, stateful multi-agent systems on the JVM. Human approvals · Checkpoints · Budget controls · Tool policies · Durable execution --- -## Why af4j? +## Why AF4J? - Build multi-agent workflows with explicit orchestration - Persist execution across failures and restarts @@ -19,7 +19,7 @@ Human approvals · Checkpoints · Budget controls · Tool policies · Durable ex ---

-af4j: Build · Govern · Run +AF4J: Build · Govern · Run

[![build](https://github.com/datallmhub/agentflow4j/actions/workflows/build.yml/badge.svg)](https://github.com/datallmhub/agentflow4j/actions) @@ -77,7 +77,7 @@ See [all samples](docs/samples.md) to explore other demos. ## Core capabilities -| Capability | What it does | af4j | +| 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` | @@ -122,7 +122,7 @@ See [Getting started](docs/getting-started.md) for Maven/Gradle setup and module - [Samples](docs/samples.md): runnable examples shipped with the repo - Migration guides: [0.7 to 0.8](docs/migration-0.8.md), [0.8 to 0.9](docs/migration-0.9.md) -**Cookbook:** [af4j Cookbook](https://github.com/datallmhub/agentflow4j-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. +**Cookbook:** [AF4J Cookbook](https://github.com/datallmhub/agentflow4j-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](docs/tutorials/stop-your-agent-burning-money.md): governed execution end to end. From 341270b491dbca4b7be2682a13e2620ef5929e2d Mon Sep 17 00:00:00 2001 From: agentflow4j Date: Mon, 28 Sep 2026 21:53:33 +0200 Subject: [PATCH 2/2] docs: write the framework name as AF4J across the docs and the site --- .github/ISSUE_TEMPLATE/bug_report.md | 4 ++-- .github/ISSUE_TEMPLATE/feature_request.md | 2 +- .github/releases/v0.10.0.md | 2 +- .github/releases/v1.0.0.md | 4 ++-- docs/concepts.md | 8 ++++---- docs/getting-started.md | 6 +++--- docs/index.md | 12 ++++++------ docs/llm-providers.md | 10 +++++----- docs/llms.txt | 6 +++--- docs/mcp.md | 4 ++-- docs/openhands.md | 2 +- docs/recipes/durable-runs.md | 2 +- docs/resilience.md | 2 +- docs/run-log.md | 2 +- docs/state-policy.md | 2 +- docs/state.md | 2 +- docs/tool-policy.md | 2 +- .../checkpoint-resume-agent-spring-boot.md | 14 +++++++------- docs/tutorials/free-mistral-quickstart.md | 16 ++++++++-------- .../human-in-the-loop-java-ai-agents.md | 6 +++--- .../llm-cost-control-java-budget-policy.md | 6 +++--- .../multi-agent-workflow-java-spring-ai.md | 4 ++-- docs/tutorials/stop-your-agent-burning-money.md | 4 ++-- docs/two-api-levels.md | 4 ++-- mkdocs.yml | 2 +- 25 files changed, 64 insertions(+), 64 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index bb8eb83..7128b60 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,6 +1,6 @@ --- name: Bug report -about: Report a reproducible bug in af4j +about: Report a reproducible bug in AF4J title: "[Bug]: " labels: bug assignees: "" @@ -12,7 +12,7 @@ Describe the bug clearly and concisely. ## Version -- af4j version: +- AF4J version: - Java version: - Maven version: - Spring Boot version: diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 7cc6c9b..be39a9b 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -10,7 +10,7 @@ assignees: "" Why is this feature needed? -What problem does it solve for users of af4j? +What problem does it solve for users of AF4J? ## Proposal diff --git a/.github/releases/v0.10.0.md b/.github/releases/v0.10.0.md index 6580af7..223c548 100644 --- a/.github/releases/v0.10.0.md +++ b/.github/releases/v0.10.0.md @@ -1,6 +1,6 @@ ## OpenHands -v0.10.0 adds `agentflow4j-openhands`: a graph node that delegates a coding task to [OpenHands](https://docs.openhands.dev) and reports back like any other agent. af4j does not reimplement the coding agent, it governs it, so the coding run gets the approval gate, the budget, the checkpoint and the audit trail of every other node. +v0.10.0 adds `agentflow4j-openhands`: a graph node that delegates a coding task to [OpenHands](https://docs.openhands.dev) and reports back like any other agent. AF4J does not reimplement the coding agent, it governs it, so the coding run gets the approval gate, the budget, the checkpoint and the audit trail of every other node. This release is additive: nothing to migrate. diff --git a/.github/releases/v1.0.0.md b/.github/releases/v1.0.0.md index faaf003..45fe79b 100644 --- a/.github/releases/v1.0.0.md +++ b/.github/releases/v1.0.0.md @@ -1,10 +1,10 @@ ## 1.0 -af4j 1.0 is the first release with a stable API. It is the runtime the last four releases were building towards: a graph engine for multi-agent workflows on the JVM where governance is part of execution, not something bolted on top. +AF4J 1.0 is the first release with a stable API. It is the runtime the last four releases were building towards: a graph engine for multi-agent workflows on the JVM where governance is part of execution, not something bolted on top. Coming from 0.10.0, nothing changes: this release freezes the API rather than reshaping it. -### What af4j gives you +### What AF4J gives you - **Governed execution.** `ToolPolicy` on every tool call, `StatePolicy` on every state write, `ApprovalGate` before any node, `BudgetPolicy` capping a run, a node or a call. The same rules hold whether you `invoke` or `invokeStream`. - **Durable runs.** Checkpoints in memory, JDBC or Redis; `resume(runId, ResumeOptions)` continues a paused or crashed run, and a rerun after a rejected approval skips the nodes that already ran instead of repeating their side effects. - **Parallel branches.** Independent branches run concurrently with bounded concurrency, state merges deterministically, and an approval pauses only the branch it gates. diff --git a/docs/concepts.md b/docs/concepts.md index 60a5d5f..ec83c91 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,10 +1,10 @@ --- -description: "af4j core concepts: agents, teams, rules and execution — how the four building blocks map to the Java API." +description: "AF4J core concepts: agents, teams, rules and execution — how the four building blocks map to the Java API." --- # Core concepts -af4j is built around four ideas. Understanding them is enough to read any recipe or tutorial in the docs. +AF4J is built around four ideas. Understanding them is enough to read any recipe or tutorial in the docs. --- @@ -33,7 +33,7 @@ ExecutorAgent analyst = ExecutorAgent.builder() ## Teams -A **team** is a group of agents that collaborate on a task. af4j provides two ways to organise them. +A **team** is a group of agents that collaborate on a task. AF4J provides two ways to organise them. **Squad API** — dynamic routing, minimal setup. A `CoordinatorAgent` receives the task and decides which `ExecutorAgent` handles it: @@ -86,7 +86,7 @@ See [Tool policy](tool-policy.md), [State policy](state-policy.md), [Budget poli ## Execution -**Execution** is how af4j makes runs reliable. Three mechanisms work together: +**Execution** is how AF4J makes runs reliable. Three mechanisms work together: **Retry** — failed nodes are retried with backoff. The `FailureClassifier` distinguishes transient errors from permanent failures and over-budget conditions, so retries don't burn money: diff --git a/docs/getting-started.md b/docs/getting-started.md index 3c04af4..bbd60ab 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,5 +1,5 @@ --- -description: "Get started with af4j: add the dependency to your Spring app, write your first agent, then compose a multi-agent graph. Java 17+, Spring Boot 3.x, Spring AI." +description: "Get started with AF4J: add the dependency to your Spring app, write your first agent, then compose a multi-agent graph. Java 17+, Spring Boot 3.x, Spring AI." --- # Getting started @@ -12,11 +12,11 @@ This page takes you from an empty Spring project to a running multi-agent graph. - **Java 17+** - **Spring Boot 3.x** (the project is built and tested on 3.5.x) -- **Spring AI 1.0+** — af4j builds on Spring AI's `ChatClient` and provider starters +- **Spring AI 1.0+** — AF4J builds on Spring AI's `ChatClient` and provider starters ## 1. Add the dependency -af4j is distributed via [JitPack](https://jitpack.io/#datallmhub/agentflow4j). Add the repository and the starter. +AF4J is distributed via [JitPack](https://jitpack.io/#datallmhub/agentflow4j). Add the repository and the starter. === "Maven" diff --git a/docs/index.md b/docs/index.md index eefca5a..1731d35 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,12 @@ --- -description: "af4j is a framework and runtime for governed, stateful multi-agent systems on the JVM. Human approvals, checkpoints, budget controls, tool policies and durable execution built for Spring." +description: "AF4J is a framework and runtime for governed, stateful multi-agent systems on the JVM. Human approvals, checkpoints, budget controls, tool policies and durable execution built for Spring." --- -# af4j +# AF4J **Build AI agents you can trust in production.** -af4j is a framework and runtime for governed, stateful multi-agent systems on the JVM. +AF4J is a framework and runtime for governed, stateful multi-agent systems on the JVM. Human approvals · Checkpoints · Budget controls · Tool policies · Durable execution @@ -16,7 +16,7 @@ Human approvals · Checkpoints · Budget controls · Tool policies · Durable ex --- -## Why af4j? +## Why AF4J? - Build multi-agent workflows with explicit orchestration - Persist execution across failures and restarts @@ -28,7 +28,7 @@ Human approvals · Checkpoints · Budget controls · Tool policies · Durable ex ## Core capabilities -| Capability | What it does | af4j | +| 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` | @@ -63,4 +63,4 @@ Runs `SupportTriageDemo`: a governed multi-agent workflow with `ToolPolicy` and --- !!! note "Scope" - af4j is an independent open-source project. It is **not** an official Spring project. + AF4J is an independent open-source project. It is **not** an official Spring project. diff --git a/docs/llm-providers.md b/docs/llm-providers.md index de21a67..26aeeb2 100644 --- a/docs/llm-providers.md +++ b/docs/llm-providers.md @@ -1,16 +1,16 @@ --- -description: "Swap LLM provider in af4j with two lines of config: Mistral, OpenAI (GPT), Anthropic Claude, Google Vertex Gemini or a local Ollama. Spring AI handles the auto-configuration; agent code stays unchanged." +description: "Swap LLM provider in AF4J with two lines of config: Mistral, OpenAI (GPT), Anthropic Claude, Google Vertex Gemini or a local Ollama. Spring AI handles the auto-configuration; agent code stays unchanged." --- # LLM providers — swap freely -af4j builds on top of Spring AI. Anything Spring AI auto-configures as a `ChatModel` works as the brain of an `ExecutorAgent` — Mistral, OpenAI, Anthropic Claude, Google Gemini, a local Ollama, your own. Switching is just **two changes**: the starter dependency, and the API key property. +AF4J builds on top of Spring AI. Anything Spring AI auto-configures as a `ChatModel` works as the brain of an `ExecutorAgent` — Mistral, OpenAI, Anthropic Claude, Google Gemini, a local Ollama, your own. Switching is just **two changes**: the starter dependency, and the API key property. The playground's `llm` bean is provider-agnostic. It receives whatever `ChatModel` Spring AI built; you decide which one. ## Getting an API key -Every paid provider follows the same flow: sign in to their console, create a key, export it as an environment variable. af4j **never reads the key from a file** — it stays in your shell, out of the repo. +Every paid provider follows the same flow: sign in to their console, create a key, export it as an environment variable. AF4J **never reads the key from a file** — it stays in your shell, out of the repo. | Provider | Console URL | Environment variable | |---|---|---| @@ -148,7 +148,7 @@ Run `ollama serve` locally and `ollama pull llama3.1` first. No key, no rate lim ## Nothing else changes -Once the `ChatModel` bean is in the context, every part of af4j keeps working unchanged: +Once the `ChatModel` bean is in the context, every part of AF4J keeps working unchanged: - `ExecutorAgent.builder().chatClient(ChatClient.builder(chatModel).build())` — same code, any provider - `CoordinatorAgent` routing via `RoutingStrategy.llmDriven(chatClient)` — same code @@ -159,4 +159,4 @@ This is the point of building on Spring AI: the provider is a swap, not a rewrit ## Multi-provider in one app -You can mix providers in the same graph — e.g., a cheap model for triage, a strong model for synthesis. Inject two distinct `ChatModel` beans (use Spring's `@Qualifier`) and pass each to the relevant `ExecutorAgent`. Spring AI's docs cover the multi-bean setup; from af4j's perspective each agent simply takes a `ChatClient`. +You can mix providers in the same graph — e.g., a cheap model for triage, a strong model for synthesis. Inject two distinct `ChatModel` beans (use Spring's `@Qualifier`) and pass each to the relevant `ExecutorAgent`. Spring AI's docs cover the multi-bean setup; from AF4J's perspective each agent simply takes a `ChatClient`. diff --git a/docs/llms.txt b/docs/llms.txt index 99ffe3b..8d5f2c8 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -1,8 +1,8 @@ -# af4j +# AF4J -> af4j is a Java/Spring open-source runtime for stateful, multi-agent LLM workflows. It sits on top of Spring AI and provides graph-based execution, durable runs (JDBC/Redis checkpoints, crash-resume), and four built-in governance gates — tool access, state writes, cost budget, and human approval. Java-first, Spring-native, code-first DSL, no sidecar and no YAML policy files. +> AF4J is a Java/Spring open-source runtime for stateful, multi-agent LLM workflows. It sits on top of Spring AI and provides graph-based execution, durable runs (JDBC/Redis checkpoints, crash-resume), and four built-in governance gates — tool access, state writes, cost budget, and human approval. Java-first, Spring-native, code-first DSL, no sidecar and no YAML policy files. -The project's value proposition: where most agent frameworks treat agents as fully trusted, af4j treats them as **untrusted by default** and lets you compose governance into the runtime alongside orchestration, in idiomatic Java. +The project's value proposition: where most agent frameworks treat agents as fully trusted, AF4J treats them as **untrusted by default** and lets you compose governance into the runtime alongside orchestration, in idiomatic Java. Audience: Java/Spring developers building production multi-agent systems that need observability, durable execution, and runtime governance. diff --git a/docs/mcp.md b/docs/mcp.md index 30fbdaa..7cc8c46 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -1,6 +1,6 @@ # MCP tools -af4j does not implement MCP. It governs the tools that Spring AI's MCP client already exposes: hand them to an `ExecutorAgent` and they go through the same `ToolPolicy`, tool-call audit and lifecycle hooks as any other tool. +AF4J does not implement MCP. It governs the tools that Spring AI's MCP client already exposes: hand them to an `ExecutorAgent` and they go through the same `ToolPolicy`, tool-call audit and lifecycle hooks as any other tool. ## Wiring @@ -27,7 +27,7 @@ Spring AI prefixes each MCP tool with the client name: tool `refund_order` serve ## Do not register MCP tools on the ChatClient !!! warning - Tools registered on the `ChatClient` itself, for example with `ChatClient.builder(model).defaultToolCallbacks(mcpTools)`, are invisible to af4j: they bypass the `ToolPolicy`, are not recorded as `ToolCallRecord`s and do not reach `onToolCall`. Register them on the `ExecutorAgent` with `toolProviders(...)` instead. + Tools registered on the `ChatClient` itself, for example with `ChatClient.builder(model).defaultToolCallbacks(mcpTools)`, are invisible to AF4J: they bypass the `ToolPolicy`, are not recorded as `ToolCallRecord`s and do not reach `onToolCall`. Register them on the `ExecutorAgent` with `toolProviders(...)` instead. ## What you get diff --git a/docs/openhands.md b/docs/openhands.md index 6ff05cc..9585b2a 100644 --- a/docs/openhands.md +++ b/docs/openhands.md @@ -1,6 +1,6 @@ # OpenHands -`OpenHandsAgent` delegates a coding task to [OpenHands](https://docs.openhands.dev) from a graph node. af4j does not reimplement the agent: it governs it, so the coding run gets an approval gate, a budget, a checkpoint and an audit trail like any other node. +`OpenHandsAgent` delegates a coding task to [OpenHands](https://docs.openhands.dev) from a graph node. AF4J does not reimplement the agent: it governs it, so the coding run gets an approval gate, a budget, a checkpoint and an audit trail like any other node. ```xml diff --git a/docs/recipes/durable-runs.md b/docs/recipes/durable-runs.md index 8b1feee..4778d0b 100644 --- a/docs/recipes/durable-runs.md +++ b/docs/recipes/durable-runs.md @@ -2,7 +2,7 @@ The most common question about agent runtimes: *"what happens if a step fails in the middle?"* -af4j checkpoints after **every node**. If a step fails, the process crashes, or you deliberately pause for a human, you `resume(runId)` and execution continues **from the node that didn't finish** — the steps that already succeeded do not re-run (and their LLM calls aren't paid for again). +AF4J checkpoints after **every node**. If a step fails, the process crashes, or you deliberately pause for a human, you `resume(runId)` and execution continues **from the node that didn't finish** — the steps that already succeeded do not re-run (and their LLM calls aren't paid for again). ## The store diff --git a/docs/resilience.md b/docs/resilience.md index 23f55e7..c78d734 100644 --- a/docs/resilience.md +++ b/docs/resilience.md @@ -1,5 +1,5 @@ --- -description: "Production error handling for Java multi-agent workflows in af4j: retry with backoff, circuit breakers per node, budget policy capping cost per run/node/call, and human-in-the-loop checkpoints." +description: "Production error handling for Java multi-agent workflows in AF4J: retry with backoff, circuit breakers per node, budget policy capping cost per run/node/call, and human-in-the-loop checkpoints." --- # Resilience & Error Handling diff --git a/docs/run-log.md b/docs/run-log.md index 19f86dc..592ec54 100644 --- a/docs/run-log.md +++ b/docs/run-log.md @@ -1,5 +1,5 @@ --- -description: "Structured, replayable execution timeline per run for af4j — node enter/exit timings, transitions, retries, and governance events (BUDGET_EXCEEDED, STATE_DENIED, APPROVAL_REQUIRED)." +description: "Structured, replayable execution timeline per run for AF4J — node enter/exit timings, transitions, retries, and governance events (BUDGET_EXCEEDED, STATE_DENIED, APPROVAL_REQUIRED)." --- # Run log — structured execution timeline diff --git a/docs/state-policy.md b/docs/state-policy.md index 9c0689d..b8b9b6d 100644 --- a/docs/state-policy.md +++ b/docs/state-policy.md @@ -1,5 +1,5 @@ --- -description: "Guard writes to specific StateKey across an af4j multi-agent workflow. Prevent an LLM from flipping sensitive flags like payment.confirmed on its own — denials surface through the graph's error policy." +description: "Guard writes to specific StateKey across an AF4J multi-agent workflow. Prevent an LLM from flipping sensitive flags like payment.confirmed on its own — denials surface through the graph's error policy." --- # State Policy diff --git a/docs/state.md b/docs/state.md index 3d358d1..25e5a27 100644 --- a/docs/state.md +++ b/docs/state.md @@ -1,6 +1,6 @@ # Typed state -Most agent frameworks store shared state as `Map` — fast to write, painful to debug. af4j uses `StateKey` for compile-time typed access. +Most agent frameworks store shared state as `Map` — fast to write, painful to debug. AF4J uses `StateKey` for compile-time typed access. ## Declaring keys diff --git a/docs/tool-policy.md b/docs/tool-policy.md index 5daa9be..4bb133a 100644 --- a/docs/tool-policy.md +++ b/docs/tool-policy.md @@ -1,5 +1,5 @@ --- -description: "Restrict which tools an AI agent may call in Java/Spring with af4j. Allow-lists, deny-lists and argument-aware rules — block shell.execute before the call leaves the agent's process." +description: "Restrict which tools an AI agent may call in Java/Spring with AF4J. Allow-lists, deny-lists and argument-aware rules — block shell.execute before the call leaves the agent's process." --- # Tool Policy diff --git a/docs/tutorials/checkpoint-resume-agent-spring-boot.md b/docs/tutorials/checkpoint-resume-agent-spring-boot.md index 5418cdf..3b5c684 100644 --- a/docs/tutorials/checkpoint-resume-agent-spring-boot.md +++ b/docs/tutorials/checkpoint-resume-agent-spring-boot.md @@ -1,24 +1,24 @@ --- -description: "Tutorial: checkpoint and resume AI agent workflows in Spring Boot with af4j. Survive restarts, recover from failures, and resume paused runs — without re-running completed nodes." +description: "Tutorial: checkpoint and resume AI agent workflows in Spring Boot with AF4J. Survive restarts, recover from failures, and resume paused runs — without re-running completed nodes." --- # Checkpoint and resume AI agent workflows in Spring Boot A multi-step agent workflow that takes minutes to run is fragile by default. A server restart, an out-of-memory error, or a deployment mid-run wipes everything — the next invocation starts from scratch, re-running every node, re-spending every token, re-calling every tool. -This tutorial shows how to add **durable execution** to your agent workflows with [af4j](https://github.com/datallmhub/agentflow4j)'s checkpoint system: persist graph state after every node, survive any failure, and resume exactly where execution left off. +This tutorial shows how to add **durable execution** to your agent workflows with [AF4J](https://github.com/datallmhub/agentflow4j)'s checkpoint system: persist graph state after every node, survive any failure, and resume exactly where execution left off. --- ## How checkpointing works -After each node completes successfully, af4j serialises the full `AgentContext` — all typed state keys and their values — to a `CheckpointStore`. The checkpoint includes: +After each node completes successfully, AF4J serialises the full `AgentContext` — all typed state keys and their values — to a `CheckpointStore`. The checkpoint includes: - The run ID (stable across restarts) - The name of the last completed node - The full context at that point -When a run is resumed, af4j loads the checkpoint, identifies the next node to execute, and continues from there. Completed nodes are skipped entirely — no repeated LLM calls, no duplicate tool invocations, no double-spending. +When a run is resumed, AF4J loads the checkpoint, identifies the next node to execute, and continues from there. Completed nodes are skipped entirely — no repeated LLM calls, no duplicate tool invocations, no double-spending. --- @@ -43,7 +43,7 @@ When a run is resumed, af4j loads the checkpoint, identifies the next node to ex ## Step 1 — Choose a checkpoint store -af4j ships three implementations: +AF4J ships three implementations: | Store | When to use | |---|---| @@ -171,7 +171,7 @@ The checkpoint stores the full typed context. Every value written by a completed // All context written by researcher is available to drafter ``` -Nodes that were in progress when the crash happened re-run from the beginning of that node — af4j checkpoints at node boundaries, not within a node. This is safe: a node's output mapper only runs after the LLM call succeeds, so a partial node write never reaches the checkpoint. +Nodes that were in progress when the crash happened re-run from the beginning of that node — AF4J checkpoints at node boundaries, not within a node. This is safe: a node's output mapper only runs after the LLM call succeeds, so a partial node write never reaches the checkpoint. --- @@ -235,7 +235,7 @@ void graph_resumes_after_first_node_completes() { ## Complete picture -Checkpointing composes with the other af4j governance primitives: +Checkpointing composes with the other AF4J governance primitives: ```java AgentGraph graph = AgentGraph.builder() diff --git a/docs/tutorials/free-mistral-quickstart.md b/docs/tutorials/free-mistral-quickstart.md index 29e860c..64aceb9 100644 --- a/docs/tutorials/free-mistral-quickstart.md +++ b/docs/tutorials/free-mistral-quickstart.md @@ -1,10 +1,10 @@ --- -description: "Run LLM agents in Java for free: create a Mistral account, grab a free API key, and wire it into an af4j agent on Spring Boot — step by step, no credit card maze, no Python." +description: "Run LLM agents in Java for free: create a Mistral account, grab a free API key, and wire it into an AF4J agent on Spring Boot — step by step, no credit card maze, no Python." --- # Run your first Java AI agent for free (with Mistral) -Most "build an AI agent" tutorials assume Python and a paid OpenAI key. This one is **Java/Spring** and **free**: you'll create a [Mistral](https://mistral.ai/) account, get a free API key, and run a real LLM-backed agent with [af4j](https://github.com/datallmhub/agentflow4j) — start to finish in about ten minutes. +Most "build an AI agent" tutorials assume Python and a paid OpenAI key. This one is **Java/Spring** and **free**: you'll create a [Mistral](https://mistral.ai/) account, get a free API key, and run a real LLM-backed agent with [AF4J](https://github.com/datallmhub/agentflow4j) — start to finish in about ten minutes. Mistral offers a **free tier on `mistral-small`** — enough to build and test agents without spending anything. @@ -23,7 +23,7 @@ Mistral offers a **free tier on `mistral-small`** — enough to build and test a 3. Keep it somewhere safe — you only see it once. !!! warning "Treat the key like a password" - Never paste it into a commit, screenshot, or chat tool. af4j reads it from an **environment variable**, never from a file in your repo. If a key leaks, rotate it in the console immediately. + Never paste it into a commit, screenshot, or chat tool. AF4J reads it from an **environment variable**, never from a file in your repo. If a key leaks, rotate it in the console immediately. Export it in your shell: @@ -31,9 +31,9 @@ Export it in your shell: export MISTRAL_API_KEY="sk-...your-key..." ``` -## Step 3 — Add af4j + the Mistral starter +## Step 3 — Add AF4J + the Mistral starter -In a Spring Boot project, add the af4j starter (via [JitPack](https://jitpack.io/#datallmhub/agentflow4j)) and Spring AI's Mistral starter: +In a Spring Boot project, add the AF4J starter (via [JitPack](https://jitpack.io/#datallmhub/agentflow4j)) and Spring AI's Mistral starter: === "Maven" @@ -45,7 +45,7 @@ In a Spring Boot project, add the af4j starter (via [JitPack](https://jitpack.io - + com.github.datallmhub.agentflow4j agentflow4j-starter @@ -85,7 +85,7 @@ spring: temperature: 0.3 ``` -Spring AI now auto-configures a `ChatClient` backed by Mistral. af4j uses that `ChatClient` as the brain of any agent. +Spring AI now auto-configures a `ChatClient` backed by Mistral. AF4J uses that `ChatClient` as the brain of any agent. ## Step 5 — Write and run an agent @@ -128,4 +128,4 @@ You now have a working LLM agent in Java. To turn it into a real multi-agent wor --- !!! tip "Staying on the free tier" - `mistral-small-latest` is covered by Mistral's free tier and is plenty for building and testing agents. When you move to heavier models or production traffic, af4j's [budget policy](../resilience.md#6-budget-policy-cost-gate) caps what an agent can spend — so a runaway loop can't surprise you on the invoice. + `mistral-small-latest` is covered by Mistral's free tier and is plenty for building and testing agents. When you move to heavier models or production traffic, AF4J's [budget policy](../resilience.md#6-budget-policy-cost-gate) caps what an agent can spend — so a runaway loop can't surprise you on the invoice. diff --git a/docs/tutorials/human-in-the-loop-java-ai-agents.md b/docs/tutorials/human-in-the-loop-java-ai-agents.md index 2dfaeae..4747938 100644 --- a/docs/tutorials/human-in-the-loop-java-ai-agents.md +++ b/docs/tutorials/human-in-the-loop-java-ai-agents.md @@ -1,12 +1,12 @@ --- -description: "Tutorial: implement human-in-the-loop approval in Java AI agents with af4j. Pause execution, notify a human, resume from a checkpoint, end to end." +description: "Tutorial: implement human-in-the-loop approval in Java AI agents with AF4J. Pause execution, notify a human, resume from a checkpoint, end to end." --- # Implementing human-in-the-loop approval in Java AI agents Autonomous agents make mistakes. They misclassify inputs, call the wrong tools, or take irreversible actions (refunds, emails, database writes) based on a hallucinated context. For high-stakes workflows, the answer is not to make the agent smarter. It is to require a human to approve before the action executes. -This tutorial shows how to implement **human-in-the-loop approval** in Java with [af4j](https://github.com/datallmhub/agentflow4j): pause an agent graph before a sensitive node, notify a human, and resume execution from a checkpoint after approval, without losing the work already done. +This tutorial shows how to implement **human-in-the-loop approval** in Java with [AF4J](https://github.com/datallmhub/agentflow4j): pause an agent graph before a sensitive node, notify a human, and resume execution from a checkpoint after approval, without losing the work already done. --- @@ -28,7 +28,7 @@ This breaks immediately in production: - The agent code is now coupled to your notification system - There is no audit trail of what was approved, and when -af4j solves this with `ApprovalGate`, a gate evaluated before a node executes. When approval is required, the graph pauses, persists a checkpoint, and returns an interrupted result. The server is free. The state is safe. A human approves asynchronously. The graph resumes exactly where it left off. +AF4J solves this with `ApprovalGate`, a gate evaluated before a node executes. When approval is required, the graph pauses, persists a checkpoint, and returns an interrupted result. The server is free. The state is safe. A human approves asynchronously. The graph resumes exactly where it left off. --- diff --git a/docs/tutorials/llm-cost-control-java-budget-policy.md b/docs/tutorials/llm-cost-control-java-budget-policy.md index 3552493..4ce67d8 100644 --- a/docs/tutorials/llm-cost-control-java-budget-policy.md +++ b/docs/tutorials/llm-cost-control-java-budget-policy.md @@ -1,12 +1,12 @@ --- -description: "Tutorial: LLM cost control for Java agents with af4j BudgetPolicy. Set per-run, per-node, and per-call limits — stop runaway spend before it hits your bill." +description: "Tutorial: LLM cost control for Java agents with AF4J BudgetPolicy. Set per-run, per-node, and per-call limits — stop runaway spend before it hits your bill." --- # LLM cost control for Java agents — BudgetPolicy in practice An LLM agent that loops, retries, or fans out to multiple nodes can burn through your API budget in minutes. A ReAct agent that gets stuck in a reasoning loop, a graph that retries on every transient error without a cost ceiling, or a batch job that processes 10× more documents than expected — all of these become expensive surprises on your billing dashboard. -This tutorial shows how to use `BudgetPolicy` in [af4j](https://github.com/datallmhub/agentflow4j) to put hard limits on what every agent run can spend — per run, per node, or per individual LLM call. +This tutorial shows how to use `BudgetPolicy` in [AF4J](https://github.com/datallmhub/agentflow4j) to put hard limits on what every agent run can spend — per run, per node, or per individual LLM call. --- @@ -141,7 +141,7 @@ CostEstimator mistralCostEstimator() { ## Handling a budget exception -When a limit is exceeded, af4j throws `BudgetExceededException`. Handle it in your service layer: +When a limit is exceeded, AF4J throws `BudgetExceededException`. Handle it in your service layer: ```java @Service diff --git a/docs/tutorials/multi-agent-workflow-java-spring-ai.md b/docs/tutorials/multi-agent-workflow-java-spring-ai.md index 5be0c3f..264e4a1 100644 --- a/docs/tutorials/multi-agent-workflow-java-spring-ai.md +++ b/docs/tutorials/multi-agent-workflow-java-spring-ai.md @@ -1,12 +1,12 @@ --- -description: "Step-by-step tutorial: build a multi-agent workflow in Java with Spring AI and af4j. Agents, routing, typed state, governance gates — end to end." +description: "Step-by-step tutorial: build a multi-agent workflow in Java with Spring AI and AF4J. Agents, routing, typed state, governance gates — end to end." --- # How to build a multi-agent workflow in Java with Spring AI Most Spring AI tutorials stop at a single `ChatClient` call. That's fine for a chatbot, but real production systems need more: multiple agents collaborating, durable state surviving restarts, routing decisions based on context, and governance to prevent runaway costs or unsafe actions. -This tutorial builds a **document review workflow** from scratch — three agents, a governed graph, typed state, and a human approval gate — using [af4j](https://github.com/datallmhub/agentflow4j) on top of Spring AI. +This tutorial builds a **document review workflow** from scratch — three agents, a governed graph, typed state, and a human approval gate — using [AF4J](https://github.com/datallmhub/agentflow4j) on top of Spring AI. --- diff --git a/docs/tutorials/stop-your-agent-burning-money.md b/docs/tutorials/stop-your-agent-burning-money.md index 139fa52..da34b94 100644 --- a/docs/tutorials/stop-your-agent-burning-money.md +++ b/docs/tutorials/stop-your-agent-burning-money.md @@ -1,5 +1,5 @@ --- -description: "Tutorial: stop your AI agent from burning $1000 overnight on a paid API or running shell.execute. End-to-end walkthrough of af4j's four governance gates — budget, tool, state, approval — in Java/Spring." +description: "Tutorial: stop your AI agent from burning $1000 overnight on a paid API or running shell.execute. End-to-end walkthrough of AF4J's four governance gates — budget, tool, state, approval — in Java/Spring." --- # Stop your AI agent from burning $1000 overnight @@ -8,7 +8,7 @@ Most Java agent frameworks treat the agent as fully trusted: it can call any too Here's a real failure mode that motivated this tutorial: a five-agent system ran for 90 days. One night, a single agent retried a paid API **23 times** against a transient error, at $0.05/call, before anyone noticed. Small money — but the retry policy was *blind to cost*. Multiply by a bigger price tag or a `shell.execute` tool and it stops being funny. -This tutorial shows how to make an agent **governed by default** with [af4j](https://github.com/datallmhub/agentflow4j): cap its spend, block dangerous tools, protect sensitive state, and require a human signature before high-stakes actions — without writing orchestration glue. +This tutorial shows how to make an agent **governed by default** with [AF4J](https://github.com/datallmhub/agentflow4j): cap its spend, block dangerous tools, protect sensitive state, and require a human signature before high-stakes actions — without writing orchestration glue. We'll build a customer-support agent that can issue refunds, then lock it down step by step. diff --git a/docs/two-api-levels.md b/docs/two-api-levels.md index b3d6bb1..a7e24cb 100644 --- a/docs/two-api-levels.md +++ b/docs/two-api-levels.md @@ -1,10 +1,10 @@ --- -description: "af4j's two API levels: dynamic Squad routing for quick multi-agent setups, or explicit Graph orchestration for loops, branches and conditional edges in Spring AI." +description: "AF4J's two API levels: dynamic Squad routing for quick multi-agent setups, or explicit Graph orchestration for loops, branches and conditional edges in Spring AI." --- # Two API levels -af4j exposes two layers. Pick the one that matches how much control you need. +AF4J exposes two layers. Pick the one that matches how much control you need. ## Level 1 — Squad API (recommended for most apps) diff --git a/mkdocs.yml b/mkdocs.yml index da94501..c80d891 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: af4j +site_name: AF4J site_description: Build multi-agent AI workflows in Java. Run them in production with security, governance, resilience, and FinOps — built into every execution, JVM-native, Spring-powered. site_url: https://datallmhub.github.io/agentflow4j/ site_author: agentflow4j