Update Agents/Tools pages

Author: kdubois

documentation/modules/ROOT/pages/19_agents_tools.adoc

@@ -4,14 +4,15 @@
 
 The real deal to bring AI for your development process is when you can create a real interaction between services you build and/or use with the LLM.
 
-This section will use AI to trigger an email service from our local application.
+This section will use AI to trigger an email service from our local application. To do this, we'll use LangChain4j's concept of Agents and Tools.
 
+Agents operate by utilizing a language model to decipher a series of actions, unlike chains where actions are pre-programmed. Ie. agents leverage a language model as a cognitive engine to decide on the actions (tools) and their order.
 
-IMPORTANT: We keep assuming that you'll be working inside the project folder that was created before. In this case, `{project-ai-name}`.
+You can read more about this concept in the https://docs.quarkiverse.io/quarkus-langchain4j/dev/agent-and-tools.html[Quarkus LangChain4j Documentation]
 
 == Add the Mailer and Mailpit extensions
 
-Just open a new terminal window, and make sure you’re at the root of your `{project-ai-name}` project, then run:
+Open a new terminal window, and make sure you’re at the root of your `{project-ai-name}` project, then run:
 
 [tabs]
 ====
@@ -64,7 +65,9 @@ public class EmailService {
     @Tool("send the given content by email")
     public void sendAnEmail(String content) {
         Log.info("Sending an email: " + content);
-        mailer.send(Mail.withText("sendMeALetter@quarkus.io", "A poem for you", content).setFrom("origin@quarkus.io"));
+        mailer.send(Mail
+            .withText("sendMeALetter@quarkus.io", "A poem for you", content)
+            .setFrom("origin@quarkus.io"));
     }
 
 }
@@ -73,7 +76,11 @@ public class EmailService {
 
 == Create the AI service with prompt context
 
-Let's create an interface for our AI service, but with `SystemMessage` and `UserMessage` this time.
+Let's create an interface for our AI service, but with `SystemMessage` and `UserMessage` this time. 
+`SystemMessage` gives context to the AI Model. 
+In this case we tell it that it should craft a message as if it is written by a professional poet. 
+The `UserMessage` is the actual instruction/question we're sending to the AI model. As you can see in the example below, 
+you can format and parametrize the UserMessage, translating structured content to text and vice-versa.  
 
 Create a new `AssistantWithContext` Java interface in `src/main/java` in the `com.redhat.developers` package with the following contents:
 
@@ -107,7 +114,7 @@ Note that this assistant references the email service as a tool.
 
 == Create a email sending resource
 
-Now we create a resource that builds the whole interaction.
+Now we create a resource that builds the interaction and calls the service with the required parameters (topic & lines).
 
 Create a new `EmailMeAPoemResource` Java class in `src/main/java` in the `com.redhat.developers` package with the following contents:
 
@@ -138,24 +145,27 @@ public class EmailMeAPoemResource {
 
 == Adding email service properties to your configuration
 
-Add the following properties to your `application.properties` so that it looks like:
+Update the following properties in your `application.properties`
+
+IMPORTANT: The LangChain4j `demo` key currently does not support tools, so you will need to use a real OpenAI key for the email service to be called by the OpenAI model.
+You can create an account over at https://platform.openai.com/[OpenAI] if you'd like to see this in action.
+
+NOTE: If you do not want to create an OpenAI key, you can still test the below scenario, it just won't send an email.
 
 [#quarkuspdb-update-props]
 [.console-input]
 [source,config,subs="+macros,+attributes"]
 ----
-quarkus.langchain4j.openai.api-key=demo
+quarkus.langchain4j.openai.api-key=<YOUR OPENAI KEY>
 
 quarkus.langchain4j.openai.log-requests=true
 quarkus.langchain4j.openai.log-responses=true
 quarkus.langchain4j.openai.timeout=60s
 
-%dev.quarkus.mailer.host=localhost
-%dev.quarkus.mailer.port=1025
 %dev.quarkus.mailer.mock=false
 ----
 
-By setting those properties Quarkus will use DevServices to instantiate a local email service for you (development time only).
+Because we haven't configured the local email service, Quarkus will use DevServices to instantiate and configure a local email service for you (in Dev Mode only!).
 
 You can check it running:
 
@@ -197,12 +207,12 @@ An example of output (it can vary on each prompt execution):
 I have composed a poem about Quarkus. I have sent it to you via email. Let me know if you need anything else
 ----
 
-More than see this on your terminal, you can check the "real" email.
+If you have a valid OpenAI key configured, you can check the "real" email:
 
-First, open the DevUI and click on the Mailpit arrow.
+First, open the http://localhost:8080/q/dev-ui[DevUI, window=_blank] and click on the Mailpit arrow.
 
 image::devui-mailpit.png[]
 
-Now you can see the email it was sent:
+Now you can see the email that was sent:
 
 image::mailpit-email-sent.png[]