Repository navigation
docs: clarify project structure and components - #759
Conversation
| │ │ ├── api/ # External MCP, HTTP, gRPC endpoints | ||
| │ │ ├── application/ # Akka components: Agents, Entities, Views, Consumers, Timers, Workflows | ||
| │ │ ├── domain/ # Business logic | ||
| │ │ └── tool/ # MCP or functional tools |
There was a problem hiding this comment.
tool package? I think tools should be in the application package. Inside the application, you can organize stuff however you want.
There was a problem hiding this comment.
Also: MCP tools are either in a service, defined in the endpoint for others to consume, or just a declaration in the agent, which already lives in application.
| - The `domain` directory holds plain Java classes that describe business rules and domain models. These are not tied to Akka or the runtime. Many use `record` to reduce boilerplate. You can test this logic without starting Akka or the runtime. This keeps the code focused and easier to maintain. | ||
|
|
||
| image:ROOT:agent.png[Agent,width=100,float=left]An _Agent_ interacts with an AI model to perform a specific task. It is typically backed by a large language model (LLM). It maintains contextual history in a session memory, which may be shared between multiple agents that are collaborating on the same goal. It may provide function tools and call them as requested by the model. | ||
| - The `tool` directory contains functional tools that can be invoked by Agents or MCP endpoints. These may also be defined within Agent classes if preferred. |
There was a problem hiding this comment.
Let's bring this under the application package description.
Reorganize information to emphasize directory structure rather than abstract layers.
Move Akka component descriptions to conceptual introduction areas of docs.
Closes: lightbend/kalix#13763
c304911 to
dd6d2dd
Compare
| │ ├── java/acme/planningagent/ | ||
| │ │ ├── api/ # External MCP, HTTP, gRPC endpoints | ||
| │ │ ├── application/ # Akka components: Agents, Entities, Views, Consumers, Timers, Workflows | ||
| │ │ │ └── tool/ # MCP or functional tools |
There was a problem hiding this comment.
There is still nothing MCP that would go in here?
There was a problem hiding this comment.
After thinking about this more, I decided to remove the tool subdirectory. None of our samples have it, this simplifies the structure and reduces confusion.
There was a problem hiding this comment.
Sounds good to skip that
| │ ├── java/acme/planningagent/ | ||
| │ │ ├── api/ # External MCP, HTTP, gRPC endpoints | ||
| │ │ ├── application/ # Akka components: Agents, Entities, Views, Consumers, Timers, Workflows | ||
| │ │ │ └── tool/ # MCP or functional tools |
There was a problem hiding this comment.
Is there a reason to highlight tools that much? I would just say that it's a part of the application. How the application package is organized is up to the user.
Align guidance with samples, simplify structure and avoid confusion.
autodidaddict
left a comment
There was a problem hiding this comment.
LGTM with a few suggested changes
|
|
||
| == Components | ||
|
|
||
| You use xref:reference:glossary.adoc#component[Akka _Components_] to build your application. These Components are crucial for ensuring responsiveness. Here is a brief overview of each. Except endpoints, Akka components will live in your `application` package. |
There was a problem hiding this comment.
saw the "Here is a brief" and "Akka components" sentences so the paragraph ends with "here is a brief"
|
|
||
| image:ROOT:key-value-entity.png[Key Value Entities,width=100,float=left] _Key Value Entities_ are, as the name implies, an object that is stored and retrieved based on a key - an identifier of some sort. The value is the entire state of the object. Every write to a Key Value Entity persists the entire state of the object. Key Value Entities are similar in some ways to database records. They write and effectively lock the whole row. They still use an underlying event-based architecture so other components can subscribe to the stream of their updates. For more information see xref:java:key-value-entities.adoc[Key Value Entities]. | ||
|
|
||
| ==== Event Sourced Entities |
There was a problem hiding this comment.
It might make sense to introduce event sourced entities first, since key value entities require some knowledge of them.
|
|
||
| === Views | ||
|
|
||
| image:ROOT:view.png[Views,width=100,float=left] _Views_ provide a way to materialize read only state from multiple entities based on a query. You can create views from Key Value Entities, Event Sourced Entities, and by subscribing to a topic. For more information see xref:java:views.adoc[Views]. |
There was a problem hiding this comment.
We should also mention that views can be created from workflow state change and from broker messages.
| The structure above also reflects a conceptual separation of responsibilities. These responsibilities can be thought of as layers. Business logic is central, with supporting code around it to enable runtime behavior and external interaction. | ||
|
|
||
| == Layer overview | ||
| To maintain modularity: |
There was a problem hiding this comment.
We might also want to provide a link to the coding guidelines here, e.g. "For more details on best practices for more than just modules, check out the code guidelines"
|
lgtm ... a number of the SPOVs have been creating tool/ or mcp/ directories to make it easier for demos and new users to understand how the project structure will look. There are so many tool endpoints that are being created, it offered a nice 'at-a-glance' location for those items. |
* docs(concepts): clarify component interoperability (#689) * docs(concepts): clarify component interoperability Closes: lightbend/kalix#13639 * clarify component call behavior * Update docs/src/modules/concepts/pages/concepts.adoc * Refine explanation of handling of concurrency and blocking. * docs: Feedback on the getting started part descriptions (#708) * docs: Api key as secret environment variable (#710) * docs: external service orchestration sample (#702) java docs Update samples/transfer-workflow-orchestration/README.md Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be> improving smaple docs, improving compenstation sample PR comments * chore: Fix some typos in akka-code-init (#713) Fix some typos in akka-code-init * docs: Document down-region (#711) * docs: akka CLI docs (#715) * docs: understanding index page (#714) * Update LICENSE (#718) * docs: correct CLI version (#719) * chore: Agent single command handler in guidelines (#723) * docs: Add IntelliJ IA assistant instructions (#724) * chore: Update llms.txt (#722) * chore: Add getting started guide as tutorial * fix broken links * update summary text * docs: Akka 2.10.7 in release notes (#727) * bump: SDK version 3.4.1 (#728) * chore: bump SDK versions to 3.4.1 (#731) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * fix: TestModelProvider should match in opposite order (#730) * to be able to change the responses, replacing a previous response * feat: eventing testkit should accept component class instead of component id (#729) * chore: Add missing .bundleignore (#733) * build: Update to new runner and use whitelist URL (#721) * docs: Include akka code init in getting started (#725) * chore: Adding more tests to multi-agent sample (#732) * chore: Add PreferencesEntityTest * chore: Add ActivityViewTest * chore: Add ActivityEndpointIntegrationTest with end-to-end interactions * docs: glossary format (#736) * docs(landing-page): use agentic system concepts (#738) Replace component-centric labels with agentic capabilities. Closes: lightbend/kalix#13760 * docs: update component composability diagram (#739) Closes: lightbend/kalix#13687 * docs(operations): self-managed vs automated (#734) Introduce feature comparison table for self-managed and automated operations. Move service packaging content to shared partial and update its accompanying diagram. Closes: lightbend/kalix#13759 * docs: Improve JavaDoc of EventSourcedEntity (#741) * docs: Improve JavaDoc of EventSourcedEntity * immutable state * lowercase id * move replication * updated code snippet * fmt * review feedback Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com> --------- Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com> * docs: Improve JavaDoc of Agent (#742) * docs: Improve JavaDoc of Agent * human edits, and removing some code snippets * lowercase id * AI model * fmt * chore: akka code init dir (#743) * docs: Improve JavaDoc of KeyValueEntity (#735) * docs: Improve JavaDoc of KeyValueEntity * human edit * immutable state * lowercase id * fmt * move immutable * move replication * Apply suggestions from code review Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com> --------- Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com> * docs: Improve JavaDoc of McpEndpoint (#744) * docs: Improve JavaDoc of McpEndpoint * only tool in code snippet * fmt * chore: Update shopping cart according to coding guidelines (#740) * chore: release notes for 3.4.1 (#746) * docs: Improve JavaDoc of HttpEndpoint (#745) * docs: Improve JavaDoc of HttpEndpoint * fmt * chore: add missing javadoc to patch annotation (#747) * chore: bump SDK versions to 3.4.2 (#751) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * chore: Format long lines (#750) * Update LICENSE for 3.4.2 (#749) * Update LICENSE for 3.4.2 * Update LICENSE Co-authored-by: Johan Andrén <johan.andren@lightbend.com> --------- Co-authored-by: Johan Andrén <johan.andren@lightbend.com> * chore: Update markdown in ask-akka-agent (#752) * chore: Wait for google pubsub topic to be created before testing it (#754) * chore: remove github-actions from mvn pom (#756) * Update LICENSE for 3.4.3 (#758) * chore: bump SDK versions to 3.4.3 (#761) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * docs: rearrange agentic platform products diagram (#760) Closes: lightbend/kalix#13686 * docs: clarify project structure and components (#759) * docs: clarify project structure and components Reorganize information to emphasize directory structure rather than abstract layers. Move Akka component descriptions to conceptual introduction areas of docs. Closes: lightbend/kalix#13763 * clarify location and purpose of tool directory * Remove tool directory from guidance. Align guidance with samples, simplify structure and avoid confusion. * Update docs/src/modules/concepts/pages/architecture-model.adoc * Clarify component placement and annotations * put ESEs first, ahead of KVEs * expand on view definition with new sources * link to coding guidelines * fix link * fix: use fake key when running integration tests (#762) * fix: define TestModelProvider as final (#763) * fix: define TestModelProvider as final * Apply suggestions from code review Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com> --------- Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com> * update theme UI, code snippets, white text darkmode, bullet alignments, bold styles (#770) * chore(docs): tidy up agentic AI anatomy diagram (#768) Minor cleanup of Consistent fonts, stroke weights, whitespace, visual balance. Closes: lightbend/kalix#13688 * refining the additional samples page (#767) * refining the additional samples page * word duplication fix * style * moving akka chess up, modifying init JSON * Update docs/src/modules/getting-started/pages/samples.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> --------- Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Adding inter-agent comms doc (#773) * Adding inter-agent comms doc * vale fix * missed a change * adding link to understanding index page * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * review changes * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Update docs/src/modules/concepts/pages/inter-agent-comms.adoc --------- Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * Auto PR - Akka Runtime version 1.5.3 (#766) * bump: Akka Runtime to 1.5.3 * bump akka version --------- Co-authored-by: Renato Cavalcanti <renato@cavalcanti.io> * chore: java formatting plugin for samples (#775) * chore: java formatting plugin * use indent 0 everywhere * check formatting in CI * Document Java formatting in a README * samples formatting with prettier-maven-plugin * formatting tweaks * fixed asciidocs tags * fix formatting in ExampleEndpoint.java * fixed ActivityViewTest * fixed CustomersByCity --------- Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> * chore: add akka resolver to settings.xml (#781) * chore: add akka resolver to settings.xml * passing settings when formatting * move settings.xml to .github * using Akka-Default * chore(docs): tidy up deploy anywhere diagram (#771) Closes: lightbend/kalix#13690 * chore: update labeller action (#782) * chore(docs): tidy up data diagram (#774) Closes: lightbend/kalix#13689 * docs: reorganize and rename getting started (#772) Rename "Getting Started" to "Tutorials". Position RAG agent and shopping cart tutorials under tutorial nav menu. Closes: lightbend/kalix#13786 * docs(concepts): update deployment model section (#776) Clarify service packaging and deployment models. Introduce new diagrams for clustering and Akka Automated Operations. Restructure content around development, self-managed, and AAO deployment modes. Closes: lightbend/kalix#13790 * docs(concepts): update Saga patterns guidance (#783) * docs(concepts): update Saga patterns guidance Closes: lightbend/kalix#13793 * Add guidance on how system complexity scales * Revert "chore: update labeller action (#782)" (#787) This reverts commit 8b81180. * list-ids replaces list-entity-ids (#794) * fix: some more snippets width reduction (#790) * fix: some more snippets width reduction * applied formatting * fix: model provider config for samples (#764) * fix: model proving config for samples fixing message fixing ask akka sample improving the hello world final improvements removing fix for service setup * java fmt * fixing typo * docs: update tutorial labels and nav structure (#792) Closes: lightbend/kalix#13804 Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be> * docs: trim intro in author your first service (#793) Closes: lightbend/kalix#13805 * chore: add prettier-ignore for format control (#795) * chore: add prettier-ignore for format control * remove prettier-ignore from generate site * formatting * fix(docs): incorrect GitHub casing (#796) * cleaning up adopt and avoid table (#798) * docs(concepts): reduce component icon size (#799) Closes: lightbend/kalix#13809 * docs(concepts): clarify distributed systems page (#800) Closes: lightbend/kalix#13816 * making the AI model provider config page more dev friendly (#803) * making the AI model provider config page more dev friendly * vale * adding openai to vocab * docs(ask-akka): add alternative to run mongodb locally (#806) * docs(ask-akka): add alternative to run mongodb locally * clarify intro * fmt + minor fixes --------- Co-authored-by: Andrzej Ludwikowski <andrzej.ludwikowski@lightbend.com> * chore: langchain deps bump (#807) * fix: wiring service class when it doesn't extend `ServiceSetup` (#785) * fix: wiring service class when it doesn't extend `ServiceSetup` * reverting labeler * reverting labeler * reverting labeler * labels * labels * labels * labels * labels * testing * testing * testing * reverting * validating ServiceSetup implementation * chore(docs): standardize ACL page headings (#808) * chore(docs): move component interoperability (#810) Relocate component interoperability section to follow agentic runtime explanation. Closes: lightbend/kalix#13823 * docs(concepts): consolidate component overview (#811) Closes: lightbend/kalix#13824 * chore: enable multi-agent IT in CI (#812) * chore: license bump (#814) * chore: bump SDK versions to 3.4.4 (#815) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * latest ui bundle, fixes alignment of elements in table cells (#819) * fix: langchain version bump (#821) * chore: license bump 3.4.5 (#823) * fix: mvn publish with repo config (#824) * chore: licence bump (#825) * chore: bump SDK versions to 3.4.6 (#826) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * chore: debugging for bundle.sh (#817) * chore: some debugging for bundle.s * debugging with grep * fixing script with sed * fixing debugging * Be explicit on timer uniqueness * chore: running IT for helloworld-agent sample (#816) * docs: add memory and event sourcing to state model (#818) * docs: add memory and event sourcing to state model Explain how Akka uses event sourcing for memory management. Add diagrams, workflow examples, and agent memory behavior. Closes: lightbend/kalix#13803 * capitalize Event Sourcing * adding small page on async (#830) * adding small page on async * typo * docs(concepts): sync vs async component invocation (#836) Closes: lightbend/kalix#13867 * docs: remove Automated Operations features list (#832) Remove Akka Automated Operations features list page and associated references to it. Closes: lightbend/kalix#13864 * docs(concepts): background execution overview (#834) Closes: lightbend/kalix#13866 * docs: fix self-managed operations table row casing (#833) * docs(concepts): format component table as bullets (#838) * docs(concepts): format component table as bullets Closes: lightbend/kalix#13879 * Update docs/src/modules/concepts/pages/concepts.adoc * docs: clarify deployment model details (#839) Closes: lightbend/kalix#13886 * feat: introducing serializable UserException (#765) * feat: introducing serializable UserException docs improvements after review missing docs for UserException Update docs/src/modules/java/pages/errors-and-failures.adoc Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be> removing errors as response * fmt and test fix * Update akka-javasdk/src/main/scala/akka/javasdk/impl/serialization/JsonSerializer.scala Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be> * Update akka-javasdk/src/test/scala/akka/javasdk/impl/serialization/JsonSerializationSpec.scala Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be> * improving code and docs * rename to CommandException * fmt --------- Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be> * docs: improving service desc docs (#845) * build: fix java formatting * apply java formatting * fix(docs): shopping-cart sample setup instructions (#835) Replace outdated Akka CLI download steps with reusable project creation partial. Ensure consistency across samples and align with initial getting started flow. Closes: #837 * chore: Mandatory OpenAI key (#854) * chore: namespace in service.yml (#855) * build: automate organize imports with scalafix (#856) * build: automate organize imports with scalafix * apply scalafix organize imports * fix: done deserialization (#858) * Auto PR - Akka Runtime version 1.5.6 (#846) * bump: Akka Runtime to 1.5.6 * bump: akka 2.10.8 * fix exception message in tests * fix tests * formatting --------- Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com> Co-authored-by: Renato Cavalcanti <renato@cavalcanti.io> * bump: runtime 1.5.6-9d3afc8fa * organize imports, formatting, and compilation * adding missing headers * formatting with prettier-formatter * fix compensation transfer sample --------- Co-authored-by: Brent Eritou <brent.eritou@lightbend.com> Co-authored-by: Patrik Nordwall <patrik.nordwall@gmail.com> Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com> Co-authored-by: olofwalker <23613882+olofwalker@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com> Co-authored-by: Johan Andrén <johan.andren@lightbend.com> Co-authored-by: Justin Pihony <justin.pihony@gmail.com> Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com> Co-authored-by: Richard Summerhayes <rasummer@users.noreply.github.com> Co-authored-by: Kevin Hoffman <autodidaddict@users.noreply.github.com> Co-authored-by: Kalix Bot <81730826+kalix-bot@users.noreply.github.com> Co-authored-by: Eduardo Pinto <eduardo.pinto@lightbend.com> Co-authored-by: Andrzej Ludwikowski <andrzej.ludwikowski@lightbend.com>
Reorganize information to emphasize directory structure rather than abstract layers.
Move Akka component descriptions to conceptual introduction areas of docs.
Closes: lightbend/kalix#13763