edits

Author: KarlErickson

learn-pr/azure/build-enterprise-ai-agents-with-java-spring/includes/2-pgvector-azure-postgresql-setup.md

@@ -21,7 +21,7 @@ The `pgvector` extension adds an open-source vector similarity search to Postgre
 Before you can enable `pgvector` on your Azure Database for PostgreSQL flexible server instance, you need to add it to your allowlist as described in [Allow extensions](/azure/postgresql/extensions/how-to-allow-extensions). To determine whether you added it correctly, use the following command: `SHOW azure.extensions;`
 
 > [!IMPORTANT]
-> Although the PostgreSQL community often refers to this extension as `pgvector`, the name of the binary and the extension itself is `vector`. That is the name you must use in the allowlist and when you create it in PostgreSQL via the `CREATE EXTENSION` command.
+> The PostgreSQL community often refers to this extension as `pgvector`. However, the name of the binary and the extension itself is `vector`, which is the name you must use in the allowlist and when you create it in PostgreSQL via the `CREATE EXTENSION` command.
 
 After you add the extension to the allowlist, install the extension by using the following SQL command:
 
@@ -44,7 +44,7 @@ LIMIT 3;
 
 Spring AI includes an abstraction of `pgvector` named `VectorStore`. This implementation requires two other PostgreSQL extensions: `hstore` and `uuid-ossp`.
 
-On startup, Spring Boot installs the required extensions and creates the required `vector_store` table with an index if doesn't already exist.
+On startup, Spring Boot installs the required extensions and creates the required `vector_store` table with an index if it doesn't already exist.
 
 ## Unit summary
 

learn-pr/azure/build-enterprise-ai-agents-with-java-spring/includes/3-exercise-pgvector-azure-postgresql-setup.md

@@ -25,11 +25,10 @@ export PUBLIC_IP=$(curl -s ipinfo.io/ip)
 echo "Start IP: $PUBLIC_IP"
 ```
 
-> [!TIP]
-> This command should work in most Linux distributions and in Git Bash. If it doesn't work, you can alternatively get your public IP address using [https://whatismyipaddress.com/](https://whatismyipaddress.com/)
+This command should work in most Linux distributions and in Git Bash. If it doesn't work, you can alternatively get your public IP address by using [https://whatismyipaddress.com/](https://whatismyipaddress.com/)
 
 > [!NOTE]
-> Your IP address can change. If this happens, you must update the corresponding firewall rule accordingly.
+> Your IP address can change. If it changes, you must update the corresponding firewall rule accordingly.
 
 ### Create a resource group
 
@@ -105,7 +104,7 @@ az postgres flexible-server ad-admin create \
     --display-name azureuser
 ```
 
-### Update allowlist required extensions for pgvector
+### Allow the required extensions for pgvector
 
 Before you can enable the extensions required by `pgvector`, you need to allow them by using the following command:
 
@@ -161,4 +160,4 @@ After this rule is created, you can update it by using `az postgres flexible-ser
 
 ## Unit summary
 
-You now have a vector-enabled PostgreSQL database ready that provides vector similarity search capabilities
+You now have a vector-enabled PostgreSQL database ready that provides vector similarity search capabilities.

learn-pr/azure/build-enterprise-ai-agents-with-java-spring/includes/5-exercise-spring-ai-development.md

@@ -1,34 +1,8 @@
 In this unit, you build a retrieval-augmented generation (RAG) application using Spring AI, Azure OpenAI, and `VectorStore` from Spring AI.
 
-## Set up your development environment
-
-Before you start building an AI-powered application, set up your development environment and the required Azure resources.
-
-## Set up your local environment
-
-Use the following steps to set up your environment:
-
-1. Use the following command to confirm that the Java Development Kit (JDK) version 17 or greater is installed:
-
-   ```bash
-   java -version  # Verify the Java installation
-   ```
-
-1. Use the following command to confirm that Maven is installed:
-
-   ```bash
-   mvn -version  # Verify the Maven installation
-   ```
-
-1. Use the following command to sign in to Azure:
-
-   ```azurecli
-   az login
-   ```
-
 ## Set up environment variables
 
-For this exercise, you need some environment variables from prior exercises. If you're using the same Bash window, these variables should still exist. If the variables are no longer available, use the following commands to recreate them:
+For this exercise, you need some environment variables from prior exercises. If you're using the same Bash window, these variables should still exist. If the variables are no longer available, use the following commands to recreate them. Be sure to replace the `<...>` placeholders with your own values, and use the same values that you used previously.
 
 ```bash
 export RESOURCE_GROUP=<resource-group>
@@ -122,11 +96,11 @@ The generated Spring Boot starter project includes the following configurations
 - Spring Boot Version: 3.4.3
 - Java Version: 17
 - Dependencies:
-  - `web`: Adds support for building web applications, including RESTful services using Spring Model View Controller (MVC).
-  - `jdbc`: Provides Java Database Connectivity (JDBC) support for database access.
-  - `azure-support`: Adds support for integrating with Azure services.
-  - `spring-ai-azure-openai`: Adds support for integrating with Azure OpenAI services.
-  - `spring-ai-vectordb-pgvector`: Adds support for using `pgvector`, a PostgreSQL extension for vector embeddings.
+  - `web`: adds support for building web applications, including RESTful services using Spring Model View Controller (MVC).
+  - `jdbc`: provides Java Database Connectivity (JDBC) support for database access.
+  - `azure-support`: adds support for integrating with Azure services.
+  - `spring-ai-azure-openai`: adds support for integrating with Azure OpenAI services.
+  - `spring-ai-vectordb-pgvector`: adds support for using `pgvector`, a PostgreSQL extension for vector embeddings.
 
 Unzip the downloaded file using the command:
 
@@ -196,7 +170,7 @@ src/
 └── pom.xml
 ```
 
-### Spring AI configuration
+### Configure Spring AI
 
 Before you can run the application successfully, you need to add the following required configuration:
 

learn-pr/azure/build-enterprise-ai-agents-with-java-spring/includes/6-agent-ai-development.md

@@ -1,55 +1,55 @@
-In this unit, you learn about AI Agents, which are autonomous entities capable of making decisions and performing tasks based on their environment and objectives. Also, you explore various agentic patterns - including the Evaluator Optimizer pattern - to improve the performance and decision-making capabilities of AI systems by evaluating and refining outputs.
+In this unit, you learn about AI agents, which are autonomous entities capable of making decisions and performing tasks based on their environment and objectives. Also, you explore various *agentic patterns* - including the Evaluator Optimizer pattern - to improve the performance and decision-making capabilities of AI systems by evaluating and refining outputs.
 
 ## What is an AI Agent?
 
 An AI agent is a software entity designed to perform tasks autonomously or semi-autonomously by receiving input, processing information, and taking actions to achieve specific goals.
 
-Agents can send and receive messages, generating responses using a combination of models, tools, human inputs, or other customizable components.
+Agents can send and receive messages, generating responses using a combination of models, tools, human inputs, and other customizable components.
 
 ## What problems do AI agents solve?
 
-AI agents offer several advantages for application development by enabling the creation of modular components that collaborate to reduce manual intervention in complex tasks. Key benefits include:
+AI agents offer several advantages for application development by enabling the creation of modular components that collaborate to reduce manual intervention in complex tasks. These advantage include the following key benefits:
 
-- Modular Components: Define specialized agents for tasks like data scraping, API interaction, or natural language processing. This modularity makes it easier to adapt the application as requirements evolve.
+- Modular components: define specialized agents for tasks like data scraping, API interaction, and natural language processing. This modularity makes it easier to adapt the application as requirements evolve.
 
-- Collaboration: Multiple agents can work together - one might handle data collection, another performs analysis, while yet another makes decisions - creating distributed intelligence.
+- Collaboration: multiple agents can work together. One might handle data collection, another might perform analysis, while yet another might make decisions, creating distributed intelligence.
 
-- Human-Agent Collaboration: Agents can work alongside humans to augment decision-making, for example, by preparing analyses that humans review and refine.
+- Human-agent collaboration: agents can work alongside humans to augment decision-making - for example, by preparing analyses that humans review and refine.
 
-- Process Orchestration: Agents can coordinate tasks across systems, tools, and APIs, automating end-to-end processes such as cloud orchestration, deployments, or creative workflows.
+- Process orchestration: agents can coordinate tasks across systems, tools, and APIs, automating end-to-end processes such as cloud orchestration, deployments, and creative workflows.
 
 ## Agent workflows and patterns
 
-Modern AI applications can be designed using a variety of agentic patterns. The Spring AI blog post on Agentic Patterns outlines several key workflows:
+Modern AI applications can be designed using various agentic patterns. The Spring AI blog post on Agentic Patterns outlines several key workflows:
 
-- Chain workflow: Breaks complex tasks into a series of sequential steps. Each step processes the output of the previous one, allowing for gradual transformation and refinement of data.
+- Chain workflow: breaks complex tasks into a series of sequential steps. Each step processes the output of the previous one, enabling gradual transformation and refinement of data.
 
-- Parallelization workflow: Executes multiple LLM calls concurrently using techniques like thread pools and futures. This pattern is ideal for processing large volumes of independent items or obtaining diverse perspectives through majority voting.
+- Parallelization workflow: executes multiple large language model (LLM) calls concurrently using techniques like thread pools and futures. This pattern is ideal for processing large volumes of independent items or obtaining diverse perspectives through majority voting.
 
-- Routing workflow: Directs inputs to specialized handlers based on content. By classifying the input and routing it to a corresponding prompt, the system ensures that each type of task is handled optimally.
+- Routing workflow: directs inputs to specialized handlers based on content. By classifying the input and routing it to a corresponding prompt, the system ensures that each type of task is handled optimally.
 
-- Orchestrator-Workers workflow: Uses a central orchestrator to decompose a complex task into subtasks that are handled by specialized worker agents. This pattern supports distributed problem solving while maintaining overall process control.
+- Orchestrator-Workers workflow: uses a central orchestrator to decompose a complex task into subtasks that are handled by specialized worker agents. This pattern supports distributed problem solving while maintaining overall process control.
 
-- Evaluator Optimizer workflow: Focused on iterative refinement, this dual-model approach uses a generator (writer) to produce an initial output and an evaluator (editor) to review and suggest improvements. The process repeats until the output meets defined quality standards.
+- Evaluator Optimizer workflow: focused on iterative refinement, this dual-model approach uses a generator (writer) to produce an initial output and an evaluator (editor) to review and suggest improvements. The process repeats until the output meets defined quality standards.
 
 ## Advanced content generation with the Evaluator Optimizer Agent pattern
 
 Building on the core RAG functionality, advanced AI applications benefit from iterative refinement for generating high-quality content. The Evaluator Optimizer Agent pattern employs a dual-model process:
 
-- Generator (Writer): Produces an initial draft, such as a blog post.
-- Evaluator (Editor): Reviews the draft, providing detailed feedback and identifying areas for improvement.
+- Generator (Writer): produces an initial draft, such as a blog post.
+- Evaluator (Editor): reviews the draft, providing detailed feedback and identifying areas for improvement.
 
 ### How it works
 
 The following steps describe how this pattern works:
 
-1. Initial generation: The writer creates a draft based on the given topic.
+1. Initial generation: the writer creates a draft based on the given topic.
 
-1. Evaluation: The evaluator reviews the draft against criteria such as clarity, engagement, and structure.
+1. Evaluation: the evaluator reviews the draft against criteria such as clarity, engagement, and structure.
 
-1. Iterative refinement: If improvements are needed, feedback is incorporated and the writer generates a revised draft.
+1. Iterative refinement: if improvements are needed, feedback is incorporated and the writer generates a revised draft.
 
-1. Loop until approved: The process repeats until the content meets the desired quality standards or a maximum number of iterations is reached.
+1. Loop until approved: the process repeats until the content meets the desired quality standards or a maximum number of iterations is reached.
 
 ### Example application: blog post generation
 

learn-pr/azure/build-enterprise-ai-agents-with-java-spring/includes/7-exercise-agent-ai-development.md

@@ -659,7 +659,7 @@ This command will return a JSON response containing both the blog content and me
 
 With the implementation as shown above, you should consistently see at least 2 iterations (and often 3) in the feedback loop. The first iteration is guaranteed by the instruction to the Editor agent to always provide improvement feedback on the first round. This ensures you can observe the complete Evaluator Optimizer Agent pattern in action. Without this forced iteration, you might occasionally see the Editor agent approve the first draft immediately, which doesn't demonstrate the full pattern.
 
-The JSON response provides valuable insights into the generation process, allowing you to track:
+The JSON response provides valuable insights into the generation process, enabling you to track:
 
 - How many iterations were needed (3 in this example)
 - Whether the post was approved by the Editor agent (false in this example, meaning it reached max iterations)

learn-pr/azure/build-enterprise-ai-agents-with-java-spring/includes/8-aca-deployment.md

@@ -2,7 +2,7 @@ In this module, you learn how to deploy your Spring Retrieval Augmented Generati
 
 ## Azure Container Apps concepts
 
-Azure Container Apps is a serverless platform that allows you to maintain less infrastructure and save costs while running containerized applications.
+Azure Container Apps is a serverless platform that enables you to maintain less infrastructure and save costs while running containerized applications.
 
 ### Environments
 
@@ -22,7 +22,7 @@ Replicas are instances of your container app that run concurrently to handle inc
 
 #### Revisions
 
-Revisions are immutable snapshots of your container app's configuration and code at a specific point in time. Each deployment creates a new revision, allowing you to roll back to previous versions if needed. Revisions enable safe updates and version control for your containerized applications. You can configure traffic splitting between revisions to gradually roll out new features or perform A/B testing.
+Revisions are immutable snapshots of your container app's configuration and code at a specific point in time. Each deployment creates a new revision, enabling you to roll back to previous versions if needed. Revisions enable safe updates and version control for your containerized applications. You can configure traffic splitting between revisions to gradually roll out new features or perform A/B testing.
 
 ### Deployment types
 
@@ -53,13 +53,13 @@ Azure Container Apps supports the following ingress options to control how your
 
 Azure Container Apps provides flexible scaling options to ensure that your application can handle varying loads efficiently. The following list describes the primary scaling options:
 
-- Manual scaling. You can manually set the number of replicas for your container app. This option gives you full control over the scaling process, allowing you to adjust the number of instances based on your specific needs.
+- Manual scaling. You can manually set the number of replicas for your container app. This option gives you full control over the scaling process, enabling you to adjust the number of instances based on your specific needs.
 
-- Automatic scaling. Azure Container Apps support automatic scaling based on various metrics. You can configure autoscaling rules to automatically adjust the number of replicas based on CPU usage, memory usage, or custom metrics including `JVM` - Java Virtual Machine - metrics using Kubernetes Event-driven Autoscaling (KEDA). This capability ensures your application can handle increased traffic without manual intervention.
+- Automatic scaling. Azure Container Apps support automatic scaling based on various metrics. You can configure autoscaling rules to automatically adjust the number of replicas based on CPU usage, memory usage, or custom metrics, including `JVM` - Java Virtual Machine - metrics, using Kubernetes Event-driven Autoscaling (KEDA). This capability ensures your application can handle increased traffic without manual intervention.
 
 - Scale to zero. For serverless applications, you can configure your container app to scale down to zero instances when there's no traffic. This helps save costs by only using resources when needed.
 
-To configure scaling, you can use the Azure CLI, Azure portal, or ARM templates. Here's an example of how to set up autoscaling using the Azure CLI:
+To configure scaling, you can use the Azure CLI, the Azure portal, or ARM templates. The following example shows you how to set up autoscaling by using the Azure CLI:
 
 ```azurecli
 az containerapp update \

learn-pr/azure/build-enterprise-ai-agents-with-java-spring/index.yml

@@ -8,9 +8,8 @@ metadata:
   ms.author: karler
   ms.reviewer: jbalderas, gok
   ms.topic: module
-  ms.custom: team=cloud_advocates
+  ms.custom: team=cloud_advocates, devx-track-java
   ms.service: azure-container-apps
-  ms.custom: devx-track-java
   ms.collection: ce-skilling-ai-copilot
 title: Build enterprise AI agents with Java and Spring
 summary: Build and deploy a Java application and AI agents using Spring AI, Azure OpenAI, and Azure Container Apps with PostgreSQL vector storage.
@@ -31,12 +30,12 @@ products:
   - azure-container-apps
   - azure-database-postgresql
 prerequisites: |
-  - An Azure subscription.
+  - An Azure subscription. [Create one for free.](https://azure.microsoft.com/free/)
   - Basic familiarity with Java and Spring Boot.
   - Experience with Git and Maven.
-  - Java 17 or later installed.
+  - [Java 17 or later](/java/openjdk/download#openjdk-17).
   - The psql client.
-  - Maven.
+  - [Maven](https://maven.apache.org/download.cgi).
 subjects:
   - machine-learning
   - custom-app-development