Skip to content

Commit b956aea

Browse files
agentflow4jagentflow4j
committed
docs: add "Run your first Java agent for free with Mistral" tutorial
A beginner, SEO-friendly tutorial that doubles as a discovery channel: create a Mistral account, grab a free-tier API key, wire it into a Spring Boot app with the AgentFlow4J + Spring AI Mistral starters, and run a real ExecutorAgent — start to finish, no Python, no paid key. Targets searches like "free LLM agent Java" / "Mistral Spring AI tutorial" and surfaces AgentFlow4J as the orchestration layer. API verified against the codebase; mkdocs build --strict passes.
1 parent 002ec23 commit b956aea

2 files changed

Lines changed: 132 additions & 0 deletions

File tree

‎docs/tutorials/free-mistral-quickstart.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
description: "Run LLM agents in Java for free: create a Mistral account, grab a free API key, and wire it into an AgentFlow4J agent on Spring Boot — step by step, no credit card maze, no Python."
3+
---
4+
5+
# Run your first Java AI agent for free (with Mistral)
6+
7+
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 [AgentFlow4J](https://github.com/datallmhub/agentflow4j) — start to finish in about ten minutes.
8+
9+
Mistral offers a **free tier on `mistral-small`** — enough to build and test agents without spending anything.
10+
11+
---
12+
13+
## Step 1 — Create a Mistral account
14+
15+
1. Go to **<https://console.mistral.ai/>**
16+
2. Sign up (email, Google, or GitHub).
17+
3. You land on **La Plateforme**, Mistral's developer console.
18+
19+
## Step 2 — Get a free API key
20+
21+
1. In the console, open **API Keys** → <https://console.mistral.ai/api-keys/>
22+
2. Click **Create new key**, give it a name (e.g. `agentflow4j-dev`), and copy it. It looks like `sk-...`.
23+
3. Keep it somewhere safe — you only see it once.
24+
25+
!!! warning "Treat the key like a password"
26+
Never paste it into a commit, screenshot, or chat tool. AgentFlow4J reads it from an **environment variable**, never from a file in your repo. If a key leaks, rotate it in the console immediately.
27+
28+
Export it in your shell:
29+
30+
```bash
31+
export MISTRAL_API_KEY="sk-...your-key..."
32+
```
33+
34+
## Step 3 — Add AgentFlow4J + the Mistral starter
35+
36+
In a Spring Boot project, add the AgentFlow4J starter (via [JitPack](https://jitpack.io/#datallmhub/agentflow4j)) and Spring AI's Mistral starter:
37+
38+
=== "Maven"
39+
40+
```xml
41+
<repositories>
42+
<repository>
43+
<id>jitpack.io</id>
44+
<url>https://jitpack.io</url>
45+
</repository>
46+
</repositories>
47+
48+
<!-- AgentFlow4J -->
49+
<dependency>
50+
<groupId>com.github.datallmhub.agentflow4j</groupId>
51+
<artifactId>agentflow4j-starter</artifactId>
52+
<version>v0.6.0</version>
53+
</dependency>
54+
55+
<!-- Spring AI — Mistral -->
56+
<dependency>
57+
<groupId>org.springframework.ai</groupId>
58+
<artifactId>spring-ai-starter-model-mistral-ai</artifactId>
59+
</dependency>
60+
```
61+
62+
=== "Gradle"
63+
64+
```groovy
65+
repositories { maven { url 'https://jitpack.io' } }
66+
67+
dependencies {
68+
implementation 'com.github.datallmhub.agentflow4j:agentflow4j-starter:v0.6.0'
69+
implementation 'org.springframework.ai:spring-ai-starter-model-mistral-ai'
70+
}
71+
```
72+
73+
## Step 4 — Point Spring AI at Mistral
74+
75+
In `src/main/resources/application.yml`:
76+
77+
```yaml
78+
spring:
79+
ai:
80+
mistralai:
81+
api-key: ${MISTRAL_API_KEY} # resolved from your shell at startup
82+
chat:
83+
options:
84+
model: mistral-small-latest # the free-tier model
85+
temperature: 0.3
86+
```
87+
88+
Spring AI now auto-configures a `ChatClient` backed by Mistral. AgentFlow4J uses that `ChatClient` as the brain of any agent.
89+
90+
## Step 5 — Write and run an agent
91+
92+
```java
93+
import io.github.datallmhub.agentflow4j.core.Agent;
94+
import io.github.datallmhub.agentflow4j.core.AgentContext;
95+
import io.github.datallmhub.agentflow4j.core.AgentResult;
96+
import io.github.datallmhub.agentflow4j.squad.ExecutorAgent;
97+
import org.springframework.ai.chat.client.ChatClient;
98+
import org.springframework.boot.CommandLineRunner;
99+
import org.springframework.context.annotation.Bean;
100+
101+
@Bean
102+
CommandLineRunner demo(ChatClient.Builder chatClientBuilder) {
103+
Agent assistant = ExecutorAgent.builder()
104+
.name("assistant")
105+
.chatClient(chatClientBuilder.build())
106+
.systemPrompt("You are a concise, helpful assistant. Answer in one sentence.")
107+
.build();
108+
109+
return args -> {
110+
AgentResult result = assistant.execute(
111+
AgentContext.of("What is backpressure in reactive streams?"));
112+
System.out.println("\nMistral says: " + result.text() + "\n");
113+
};
114+
}
115+
```
116+
117+
Run your app (`mvn spring-boot:run`) with `MISTRAL_API_KEY` set, and you'll see a real answer from Mistral — your first governed-ready Java agent, for free.
118+
119+
## Where to go next
120+
121+
You now have a working LLM agent in Java. To turn it into a real multi-agent workflow:
122+
123+
- **[Two API levels](../two-api-levels.md)** — Squad vs Graph, and how to compose agents into a stateful flow.
124+
- **[Cookbook](https://github.com/datallmhub/agentflow4j-cookbook)** — five runnable recipes (RAG, ticket triage, web research, Slack bot, batch processing).
125+
- **[Switch providers](../llm-providers.md)** — move from Mistral to OpenAI, Anthropic, Gemini or local Ollama by changing one dependency.
126+
- **[Stop your agent burning $1000 overnight](stop-your-agent-burning-money.md)** — once you're past the free tier, cap spend with budget, tool and approval gates.
127+
128+
---
129+
130+
!!! tip "Staying on the free tier"
131+
`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, AgentFlow4J'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.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ nav:
9191
- Approval via Slack: recipes/approval-via-slack.md
9292
- Durable runs: recipes/durable-runs.md
9393
- Tutorials:
94+
- "Run your first agent for free (Mistral)": tutorials/free-mistral-quickstart.md
9495
- "Stop your agent burning $1000 overnight": tutorials/stop-your-agent-burning-money.md
9596
- Testing: testing.md
9697
- Samples: samples.md

0 commit comments

Comments
 (0)