Hello world agent

This sample uses an agent and LLM to generate greetings in different languages. It illustrates how the agent maintains contextual history in a session memory.

This sample is explained in Author your first agentic service.

To understand the Akka concepts that are the basis for this example, see Development Process in the documentation.

This project contains the skeleton to create an Akka service. To understand more about these components, see Developing services.

---

Secure Repository Token

Building requires a secure repository token, which is set up as part of Akka CLI's akka code init command.

If you still need to configure your system with the token there are two additional ways:

1. Use the Akka CLI's akka code token command and follow the instructions.
2. Set up the token manually as described here.

---

Use Maven to build your project:

mvn compile

When running an Akka service locally.

This sample is using OpenAI. Other AI models can be configured, see Agent model provider.

Set your OpenAI API key as an environment variable:

• On Linux or macOS:

  export OPENAI_API_KEY=your-openai-api-key

• On Windows (command prompt):

  set OPENAI_API_KEY=your-openai-api-key

Or change the application.conf file to use a different model provider.

To start your service locally, run:

mvn compile exec:java

This command will start your Akka service. With your Akka service running, the endpoint is available at:

curl -i -XPOST --location "http://localhost:9000/hello" \
    --header "Content-Type: application/json" \
    --data '{"user": "alice", "text": "Hello, I am Alice"}'

You can use the Akka Console to create a project and see the status of your service.

Build container image:

mvn clean install -DskipTests

Install the akka CLI as documented in Install Akka CLI.

Set up secret containing OpenAI API key:

akka secret create generic openai-api --literal key=$OPENAI_API_KEY

Deploy the service using the image tag from above mvn install and the secret:

akka service deploy helloworld-agent helloworld-agent:tag-name --push \
  --secret-env OPENAI_API_KEY=openai-api/key

Refer to Deploy and manage services for more information.