- 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
- Akka CLI
- Java 21, we recommend Eclipse Adoptium
- Apache Maven version 3.9 or later
- curl command-line tool
- Git
- OpenAI API key, or one from other models we support
- IntelliJ or another preferred IDE
- Qodo IntelliJ extension, or another AI coding assistant
Open a terminal window and run:
akka code init
Choose the Hello world agent
sample and follow the rest of the prompts to complete the setup.
Open the generated project in IntelliJ, as well as the Qodo chat prompt.
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
Run the project:
cd hello-world-agent
# MacOS or Linux
export OPENAI_API_KEY='key here'
# Windows
set OPENAI_API_KEY='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! There is a tutorial in our docs that will create this example from scratch.
Run the Akka local console
After your agentic service is running, you can inspect it using the Akka CLI.
akka local console
At http://localhost:9889/ you can view logs, current state, and even drill into the details of your service endpoint flows.
Review your hello path by expanding helloworld-agent
and clicking on the HelloWorldEndpoint
to expose its Request builder.
Send request
after choosing the hello
route and pasting the following JSON as the body:
{
"user": "alice",
"text": "I'm having fun"
}

Success!
You've set up your AI-assisted development environment. Continue your journey with Akka AI.
Command line
Prerequisites
- Akka CLI
- Java 21, we recommend Eclipse Adoptium
- Apache Maven version 3.9 or later
- curl command-line tool
- Git
- OpenAI API key, or one from other models we support
Open a terminal window and run:
akka code init
Choose the Hello world agent
sample and follow the rest of the prompts to complete the setup.
Run the project:
cd hello-world-agent
# MacOS or Linux
export OPENAI_API_KEY='key here'
# Windows
set 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:
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:
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! There is a tutorial in our docs that will create this example from scratch.
Run the Akka local console
After your agentic service is running, you can inspect it using the Akka CLI.
akka local console
At http://localhost:9889/ you can view logs, current state, and even drill into the details of your service endpoint flows.
Review your hello path by expanding helloworld-agent
and clicking on the HelloWorldEndpoint
to expose its Request builder.
Send request
after choosing the hello
route and pasting the following JSON as the body:
{
"user": "alice",
"text": "I'm having fun"
}

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
