- Choose your path
How do you want to start?
Command line
Clone, build and run an agentic AI project from within your local terminal.
AI-assisted
Prompt your AI assistant (Cursor, Qodo, Copilot, Devin, Windsurf) to scaffold and test Akka services and their components.
Or, start with the Akka Libraries to engineer a distributed system with fine-grained control over currency, messaging, clustering, and resilience.
Use of our samples are governed by our privacy policy.
AI-assisted
Prerequisites
- Java 21, we recommend Eclipse Adoptium
- Apache Maven version 3.9 or later
- curl command-line tool
- Git
- OpenAI API key
- Qodo.ai
In this example we are using Qodo.ai.
After meeting the prerequisites, clone and run the Akka SDK project:
git clone https://github.com/akka-samples/helloworld-agent.git
cd helloworld-agent
Download this file and unzip it into helloworld-agent/akka-context/
. This provides the AI with Akka SDK specific knowledge.
Install the Qodo IntelliJ extension.
Open the project in IntelliJ, as well as the Qodo chat prompt.
Paste our coding guidelines into the prompt and hit return to accept them.
Paste the following into the Qodo prompt and accept the recommended code changes:
Add a new agent that asks the LLM to recommend a food dish from the country
of origin of the last language used to say hello.
Use the country name rather than the language to identify the food dish in the response
Change the hello method in the endpoint to call the food recommendation agent after
calling the hello world agent but before responding to the user
Add the food recommendation to the response and reply to the user
Setup yourOpenAI key and run:
export OPENAI_API_KEY='replace with your key here'
mvn clean compile exec:java
In a new terminal, say hello with the following curl command:
curl -i -XPOST --location "http://localhost:9000/hello" \
--header "Content-Type: application/json" \
--data '{"user": "alice", "text": "Hello, I am Alice"}'
You should see an AI-generated greeting similar to the one below:
Hello, Alice! ๐ I'm so excited to meet you! Learning new greetings is a fantastic way to make
friends around the world. Let's sprinkle some global cheer together!
So, how are you doing today? I'm all ears!
Previous greetings: None yet!
The last greeting language used was English, which is predominantly spoken in many countries,
including the United States.
A traditional dish from the United States is **Macaroni and Cheese**. This comfort food is
representative of American cuisine due to its simplicity, accessibility, and iconic status
as a staple in many households, often evoking nostalgia and warmth.
Let's try another greeting the AI again to see what happens:
curl -i -XPOST --location "http://localhost:9000/hello" \
--header "Content-Type: application/json" \
--data '{"user": "alice", "text": "I live in New York"}
The LLM AI-generated response should look similar to the one below:
Bonjour, Alice! (French) ๐ How's the Big Apple treating you today? New York is such a
vibrant place full of energy, art, and delicious food! Have you found any hidden gems in the
city that you absolutely love?
Previous greetings:
1. Hello (English)
The last greeting language used was French, which is prominently spoken in France.
A traditional dish from France is **Coq au Vin**. This classic dish, consisting of chicken
braised with wine, lardons, mushrooms, and garlic, embodies the essence of French cuisine,
showcasing the country's rich culinary traditions and the art of slow cooking that enhances
flavors over time.
Great! You have just set up and run your first agentic service for Akka with AI assist! For more information about this example, see our Author your first agentic service in the Akka documentation. For more information on AI assist see our Using an AI coding assistant in the Akka documentation.
Run the Akka local console
After your agentic service is running, you can inspect it using the Akka CLI.
Install the CLI by following the Akka CLI documentation.
Once installed, inspect your service with:
Run the Akka local console:
akka local console
View the current state and event log of your service at http://localhost:9889/

Success!
You've set up your AI-assisted development environment. Continue your journey with Akka AI.
Command line
Prerequisites
- Java 21, we recommend Eclipse Adoptium
- Apache Maven version 3.9 or later
- curl command-line tool
- Git
- OpenAI API key
After meeting the prerequisites, clone and run the Akka SDK project:
git clone https://github.com/akka-samples/helloworld-agent.git
cd helloworld-agent
export OPENAI_API_KEY='key here'
mvn compile exec:java
In a new terminal, say hello with the following curl command:
curl -i -XPOST --location "http://localhost:9000/hello" \
--header "Content-Type: application/json" \
--data '{"user": "alice", "text": "Hello, I am Alice"}'
You should see an AI-generated greeting similar to the one below:
Hello, Alice! I'm absolutely thrilled to meet you! ๐ How are you today? Let's make this chat
one for the books!
Previous greetings: None yet!
Let's try greeting the AI again to see what happens:
curl -i -XPOST --location "http://localhost:9000/hello" \
--header "Content-Type: application/json" \
--data '{"user": "alice", "text": "I live in New York"}'
The LLM AI-generated response should look similar to the one below:
Bonjour, Alice! (French) ๐ It's wonderful to connect! New York must be such a vibrant place to
live! With all those skyscrapers, it's like a city that never sleeps on a rollercoaster ride
of excitement! What's your favorite thing about living there?
Previous greetings: Hello (English)
Great! You have just set up and run your first agentic service for Akka! For more information about this example, see our author your first agentic service in the Akka documentation.
Run the Akka local console
After your agentic service is running, you can inspect it using the Akka CLI.
Install the CLI by following the Akka CLI documentation.
Once installed, inspect your service with:
Run the Akka local console:
akka local console
View the current state and event log of your service at http://localhost:9889/

Success!
You've set up your environment. Continue your agentic journey with Akka.
Choose your language?
Java example
Download the sample code and unzip it.
cd akka-sample-sharding
mvn -pl killrweather compile exec:java
This will start an akka cluster with three nodes running in a single jvm.
Interact with the app in a different terminal window:
curl -XPOST http://localhost:12553/weather/62 \
-H "Content-Type: application/json" \
--data '{
"eventTime": 1579106781,
"dataType": "temperature",
"value": 10.3
}'
curl "http://localhost:12553/weather/62?type=temperature&function=average"
To learn more about this quickstart, please take a look at the sample repository.
Scala example
Download the sample code and unzip it.
cd akka-sample-sharding
sbt killrweather/run
This will start an akka cluster with three nodes running in a single jvm.
Interact with the app in a different terminal window:
curl -XPOST http://localhost:12553/weather/62 \
-H "Content-Type: application/json" \
--data '{
"eventTime": 1579106781,
"dataType": "temperature",
"value": 10.3
}'
curl "http://localhost:12553/weather/62?type=temperature&function=average"
To learn more about this quickstart, please take a look at the sample repository.
Success!
You've set up your environment. Continue your agentic journey with Akka.

O'Reilly technical guide

Go deeper with Akkademy

Akka Libraries documentation
Success!
You've set up your environment. Continue your agentic journey with Akka.

O'Reilly technical guide

Go deeper with Akkademy
