• 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.

AI-assisted

Prerequisites

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"
}

Command line

Prerequisites

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"
}

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.