Skip to content

Commit bf32a93

Browse files
agentflow4jagentflow4j
committed
docs: add Getting Started guide + surface the cookbook
The docs jumped straight to "Two API levels" with no install-to-first-agent path, and the cookbook (five runnable Java recipes) was not linked anywhere. - New docs/getting-started.md: dependency (Maven/Gradle via JitPack), requirements, a no-LLM first agent, an LLM-backed ExecutorAgent, and a minimal two-node AgentGraph — then links onward to API levels, state and governance. API verified against the codebase. - Add "Getting started" at the top of the Get started nav. - Add a "Cookbook ↗" nav entry and link it from the home page's "Where to next". mkdocs build --strict passes (no broken links).
1 parent 002ec23 commit bf32a93

3 files changed

Lines changed: 152 additions & 0 deletions

File tree

‎docs/getting-started.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
description: "Get started with AgentFlow4J: 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."
3+
---
4+
5+
# Getting started
6+
7+
This page takes you from an empty Spring project to a running multi-agent graph. Three steps: add the dependency, write a first agent, then compose a graph.
8+
9+
> Just want to see it run without integrating anything? Clone the repo and run the bundled demo — see [Try it in 30 seconds](index.md#try-it-in-30-seconds).
10+
11+
## Requirements
12+
13+
- **Java 17+**
14+
- **Spring Boot 3.x** (the project is built and tested on 3.5.x)
15+
- **Spring AI 1.0+** — AgentFlow4J builds on Spring AI's `ChatClient` and provider starters
16+
17+
## 1. Add the dependency
18+
19+
AgentFlow4J is distributed via [JitPack](https://jitpack.io/#datallmhub/agentflow4j). Add the repository and the starter.
20+
21+
=== "Maven"
22+
23+
```xml
24+
<repositories>
25+
<repository>
26+
<id>jitpack.io</id>
27+
<url>https://jitpack.io</url>
28+
</repository>
29+
</repositories>
30+
31+
<dependency>
32+
<groupId>com.github.datallmhub.agentflow4j</groupId>
33+
<artifactId>agentflow4j-starter</artifactId>
34+
<version>v0.6.0</version>
35+
</dependency>
36+
```
37+
38+
=== "Gradle"
39+
40+
```groovy
41+
repositories { maven { url 'https://jitpack.io' } }
42+
43+
dependencies {
44+
implementation 'com.github.datallmhub.agentflow4j:agentflow4j-starter:v0.6.0'
45+
}
46+
```
47+
48+
The `agentflow4j-starter` pulls in the core, graph and squad modules plus the Spring Boot auto-configuration.
49+
50+
## 2. Your first agent (no LLM required)
51+
52+
An `Agent` is a single functional method: `AgentResult execute(AgentContext)`. The smallest possible agent is a lambda — runs instantly, no API key, ideal for wiring tests:
53+
54+
```java
55+
import io.github.datallmhub.agentflow4j.core.Agent;
56+
import io.github.datallmhub.agentflow4j.core.AgentContext;
57+
import io.github.datallmhub.agentflow4j.core.AgentResult;
58+
59+
// An Agent reads the context and returns a result.
60+
Agent greeter = ctx -> {
61+
String user = ctx.messages().get(ctx.messages().size() - 1).getText();
62+
return AgentResult.ofText("Hello! You said: " + user);
63+
};
64+
65+
AgentResult result = greeter.execute(AgentContext.of("hi there"));
66+
System.out.println(result.text()); // Hello! You said: hi there
67+
```
68+
69+
That's the whole contract every node in a graph implements. Everything else (LLM calls, routing, governance) builds on it.
70+
71+
## 3. Add an LLM
72+
73+
To back an agent with a real model, add a [Spring AI provider starter](llm-providers.md) and export its API key. Mistral has a free tier:
74+
75+
=== "Maven"
76+
77+
```xml
78+
<dependency>
79+
<groupId>org.springframework.ai</groupId>
80+
<artifactId>spring-ai-starter-model-mistral-ai</artifactId>
81+
</dependency>
82+
```
83+
84+
```yaml
85+
# application.yml
86+
spring:
87+
ai:
88+
mistralai:
89+
api-key: ${MISTRAL_API_KEY} # resolved from your shell, never committed
90+
chat:
91+
options:
92+
model: mistral-small-latest
93+
```
94+
95+
Spring AI auto-configures a `ChatClient`. Wrap it in an `ExecutorAgent`:
96+
97+
```java
98+
import io.github.datallmhub.agentflow4j.squad.ExecutorAgent;
99+
import org.springframework.ai.chat.client.ChatClient;
100+
101+
@Bean
102+
Agent assistant(ChatClient.Builder chatClientBuilder) {
103+
return ExecutorAgent.builder()
104+
.name("assistant")
105+
.chatClient(chatClientBuilder.build())
106+
.systemPrompt("You are a concise, helpful assistant.")
107+
.build();
108+
}
109+
```
110+
111+
Call it the same way:
112+
113+
```java
114+
AgentResult answer = assistant.execute(
115+
AgentContext.of("Explain backpressure in one sentence."));
116+
```
117+
118+
See [LLM providers](llm-providers.md) to switch to OpenAI, Anthropic, Gemini or local Ollama — it's a one-dependency change, the agent code stays the same.
119+
120+
## 4. Compose a graph
121+
122+
A single agent is rarely enough. An `AgentGraph` wires agents into a stateful flow with explicit edges:
123+
124+
```java
125+
import io.github.datallmhub.agentflow4j.graph.AgentGraph;
126+
127+
Agent classify = ctx -> AgentResult.ofText("billing");
128+
Agent reply = ctx -> AgentResult.ofText("Routing your billing question to finance.");
129+
130+
AgentGraph graph = AgentGraph.builder()
131+
.name("support")
132+
.addNode("classify", classify)
133+
.addNode("reply", reply)
134+
.addEdge("classify", "reply")
135+
.build();
136+
137+
AgentResult result = graph.invoke(AgentContext.of("My invoice looks wrong"));
138+
```
139+
140+
From here you can add typed state passed between nodes, conditional edges, retries, and governance gates — without writing orchestration glue.
141+
142+
## Next steps
143+
144+
- **[Cookbook](https://github.com/datallmhub/agentflow4j-cookbook)** — five runnable Java recipes (RAG, ticket triage, web research, Slack bot, batch processing), each a self-contained Maven module.
145+
- **[Two API levels](two-api-levels.md)** — when to use the high-level Squad API vs the low-level Graph API.
146+
- **[Typed state](state.md)** — share data between nodes with `StateKey<T>` instead of `Map<String, Object>`.
147+
- **[Governance](tool-policy.md)** — cap spend, restrict tools, protect state, and require human approval.
148+
- **[Resilience](resilience.md)** — retries, circuit breakers, and budget-aware cost gates.

‎docs/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ Runs `SupportTriageDemo` — a customer-support ticket flowing through a graph:
4242

4343
## Where to next
4444

45+
- **First time?** The [Getting started](getting-started.md) guide takes you from `mvn` dependency to a running graph.
46+
- **Want runnable examples?** The [Cookbook](https://github.com/datallmhub/agentflow4j-cookbook) has five self-contained Java recipes — RAG, ticket triage, web research, Slack bot, batch processing.
4547
- **New here?** Start with [Two API levels](two-api-levels.md) — the Squad vs Graph distinction.
4648
- **Worried about cost or unsafe actions?** Read the [governance trilogy](tool-policy.md): tool, state and approval gates.
4749
- **Building for production?** [Durable runs](recipes/durable-runs.md) shows how to survive a mid-workflow crash.

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ markdown_extensions:
7575
nav:
7676
- Home: index.md
7777
- Get started:
78+
- Getting started: getting-started.md
7879
- Two API levels: two-api-levels.md
7980
- LLM providers: llm-providers.md
8081
- Typed state: state.md
@@ -94,6 +95,7 @@ nav:
9495
- "Stop your agent burning $1000 overnight": tutorials/stop-your-agent-burning-money.md
9596
- Testing: testing.md
9697
- Samples: samples.md
98+
- Cookbook ↗: https://github.com/datallmhub/agentflow4j-cookbook
9799

98100
plugins:
99101
- search

0 commit comments

Comments
 (0)