Skip to content

docs: spec-driven hello agent tutorial - #1429

Merged
ennru merged 8 commits into
mainfrom
docs/sdd-hello-agent
Mar 19, 2026
Merged

ennru merged 8 commits into
mainfrom
docs/sdd-hello-agent

Conversation

@autodidaddict

Copy link
Copy Markdown
Contributor

No description provided.

@github-actions github-actions Bot added the documentation documentation related label Mar 18, 2026

@octonato octonato left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM after addressing Enno's comment


This sample is going to default to using OpenAI as the model provider.

IMPORTANT: Before proceeding, you **MUST** set the `OPENAI_API_KEY` environment variable and make it available to child processes (on Mac/Linux, that means using `export`) before running `akka specify` or starting your coding assistant in the terminal.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are env variables automatically inherited by child processes on Windows? If not, we need instructions for what to do there.

|**/akka.specify** main feature - _The greeter agent generates greetings in different languages using an LLM. The consumer of the agent supplies a name and some greeting text in their native language. The agent will then respond with a friendly greeting in English. Each subsequent message sent by a given user will result in a greeting in a randomly chosen language that hasn't yet been used in that agent session._
|===

After submitting that prompt, you will be asked for permission to run a number of MCP tools. These relate to setting up a new git branch and creating the first specification file (you're likely to be asked for permission to overwrite the spec file). If you typed the prompt exactly as above, then you will have a new branch called `001-main-feature`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will continuously ask for permissions for various MPC, and to edit files, should we have some recommendations for wildcard claude code allow permissions? If not, add something here that each of those requests must be allowed throughout the tutorial.

We shouldn't have to leave the Claude session for any reason.

== Next steps
Next we move on to a more involved tutorial that uses multiple components to create a multi-agent trip planning system. We also encourage you to take a look at the various samples and tutorials and see if you can work backwards from the implementation to come up with the specification and then go through a spec-driven flow.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we maybe hold off on this section until we have a SDD version of the multi-agent trip planning tutorial for SDD as well?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we weren't planning on creating an SDD version of everything. For now, just this one sample was what we were planning.

autodidaddict and others added 6 commits March 18, 2026 14:19
…ce.adoc

Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com>
Co-authored-by: Johan Andrén <johan.andren@lightbend.com>
Co-authored-by: Johan Andrén <johan.andren@lightbend.com>
Co-authored-by: Johan Andrén <johan.andren@lightbend.com>

@ennru ennru left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

@ennru ennru changed the title providing a spec-driven alternative to the hello agent tutorial docs: spec-driven hello agent tutorial Mar 19, 2026
@ennru
ennru merged commit 0aa4fdb into main Mar 19, 2026
10 checks passed
@ennru
ennru deleted the docs/sdd-hello-agent branch March 19, 2026 06:20
To start a new project using Spec-Driven Development, we use the `akka specify init` command. You have two options here:

* Type `akka specify init helloworld-agent` to create a new directory called `helloworld-agent`
* Manually create your own directory, `cd` into that directory, and run `akka specify init --here`

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--here is wrong, fixed in #1437

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants