Merge pull request #225 from ollama4j/fix-docs-build

Update Docs Build GHA

.github/workflows/build-on-pull-request.yml

@@ -8,6 +8,8 @@ on:
     paths:
       - 'src/**'
       - 'pom.xml'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -52,7 +54,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - name: Use Node.js
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: '20.x'
       - run: cd docs && npm ci

.github/workflows/codeql.yml

@@ -32,13 +32,13 @@ jobs:
           java-version: '21'
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        uses: github/codeql-action/init@v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v3
+        uses: github/codeql-action/autobuild@v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        uses: github/codeql-action/analyze@v4
 

.github/workflows/publish-docs.yml

@@ -40,7 +40,7 @@ jobs:
 
       - uses: actions/checkout@v5
       - name: Use Node.js
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: '20.x'
       - run: cd docs && npm ci
@@ -54,7 +54,7 @@ jobs:
           regex: false
 
       - name: Build with Maven
-        run: mvn --file pom.xml -U clean package && cp -r ./target/apidocs/. ./docs/build/apidocs
+        run: mvn --file pom.xml -U clean package -Dgpg.skip=true -DskipTests && cp -r ./target/apidocs/. ./docs/build/apidocs
 
       - name: Doxygen Action
         uses: mattnotmitt/doxygen-action@v1.12.0

docs/docs/agent.md

@@ -1,43 +1,50 @@
 ---
 sidebar_position: 4
 
-title: Agents
+title: Agents 🆕
 ---
 
 import CodeEmbed from '@site/src/components/CodeEmbed';
+import TypewriterTextarea from '@site/src/components/TypewriterTextarea';
 
 # Agents
 
-Build powerful, flexible agents—backed by LLMs and tools—in a few minutes.
+An **agent** is an intelligent assistant that understands user requests, communicates using LLMs, and performs actions by invoking appropriate tools (exposed as code).
 
-Ollama4j’s agent system lets you bring together the best of LLM reasoning and external tool-use using a simple, declarative YAML configuration. No framework bloat, no complicated setup—just describe your agent, plug in your logic, and go.
+With agents, you can:
+- Orchestrate multi-step reasoning and tool use (e.g., answering questions, looking up data, making reservations, sending emails, and more)
+- Automatically select and execute the right tools or actions based on user intent
+- Maintain conversation context to support dynamic, interactive problem solving
+- Adapt behavior, persona, or expertise by simply changing configuration—without changing your Java code
+
+Agents help by acting as an intelligent bridge between users, LLMs, and your application's capabilities. They can automate tasks, provide personalized assistance, and extend what LLMs can do by calling your Java methods or integrating with external systems.
+
+With Ollama4j, creating an agent is as simple as describing its purpose, available tools, behavior, and preferred language model—all defined in a single YAML file.
+
+**Why consider building agents using Ollama4j?**
+
+- **Seamless Customization:** Effortlessly fine-tune your agent's personality, expertise, or workflow by editing the YAML—no need to recompile or modify your Java code.
+- **Plug-and-Play Extensibility:** Add new tools or swap out existing logic classes without wrestling with framework internals or glue code.
+- **Rapid Iteration:** Experiment freely. Try different models, instructions, and toolsets to try new behaviors or orchestrations in minutes.
+- **Clear Separation of Concerns:** Keep your core business logic (Java) and conversational configuration (YAML) distinct, promoting clarity, maintainability, and collaboration.
 
 ---
 
-**Why use agents in Ollama4j?**
-
-- **Effortless Customization:** Instantly adjust your agent’s persona, reasoning strategies, or domain by tweaking YAML. No need to touch your compiled Java code.
-- **Easy Extensibility:** Want new capabilities? Just add or change tools and logic classes—no framework glue or plumbing required.
-- **Fast Experimentation:** Mix-and-match models, instructions, and tools—prototype sophisticated behaviors or orchestrators in minutes.
-- **Clean Separation:** Keep business logic (Java) and agent personality/configuration (YAML) separate for maintainability and clarity.
-
----
-
-## Define an Agent in YAML
+### Define an Agent in YAML
 
 Specify everything about your agent—what LLM it uses, its “personality,” and all callable tools—in a single YAML file.
 
-**Agent YAML keys:**
+**Agent configuration parameters:**
 
-| Field                   | Description                                                                                                           |
-|-------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| `name`                  | Name of your agent.                                                                                                   |
-| `host`                  | The base URL for your Ollama server (e.g., `http://localhost:11434`).                                                |
-| `model`                 | The LLM backing your agent (e.g., `llama2`, `mistral`, `mixtral`, etc).                                              |
-| `customPrompt`          | _(optional)_ System prompt—instructions or persona for your agent.                                                   |
-| `tools`                 | List of tools the agent can use. Each tool entry describes the name, function, and parameters.                        |
-| `toolFunctionFQCN`      | Fully qualified Java class name implementing the tool logic. Must be present on classpath.                            |
-| `requestTimeoutSeconds` | _(optional)_ How long (seconds) to wait for agent replies.                                                            |
+| Field                   | Description                                                                                    |
+|-------------------------|------------------------------------------------------------------------------------------------|
+| `name`                  | Name of your agent.                                                                            |
+| `host`                  | The base URL for your Ollama server (e.g., `http://localhost:11434`).                          |
+| `model`                 | The LLM backing your agent (e.g., `llama3`, `gemma`, `mistral`, etc).                          |
+| `customPrompt`          | _(optional)_ System prompt—instructions or persona for your agent.                             |
+| `tools`                 | List of tools the agent can use. Each tool entry describes the name, function, and parameters. |
+| `toolFunctionFQCN`      | Fully qualified Java class name implementing the tool logic. Must be present on classpath.     |
+| `requestTimeoutSeconds` | _(optional)_ How long (seconds) to wait for agent replies.                                     |
 
 YAML makes it effortless to configure and tweak your agent’s powers and behavior—no code changes needed!
 
@@ -47,14 +54,42 @@ YAML makes it effortless to configure and tweak your agent’s powers and behavi
 
 ---
 
-## Instantiating and Running Agents in Java
+### Implement Tool Functions
+
+Your agent calls out to Java classes (Tool Functions). Put these implementations on your classpath, register them in YAML.
+
+<CodeEmbed src="https://raw.githubusercontent.com/ollama4j/ollama4j-examples/refs/heads/main/src/main/java/io/github/ollama4j/examples/tools/toolfunctions/HotelBookingLookupToolFunction.java"/>
+
+<CodeEmbed src="https://raw.githubusercontent.com/ollama4j/ollama4j-examples/refs/heads/main/src/main/java/io/github/ollama4j/examples/tools/toolfunctions/HotelBookingToolFunction.java"/>
+
+---
+
+### Instantiating and Running Agents
 
 Once your agent is described in YAML, bringing it to life in Java takes only a couple of lines:
 
 <CodeEmbed src="https://raw.githubusercontent.com/ollama4j/ollama4j-examples/refs/heads/main/src/main/java/io/github/ollama4j/examples/AgentExample.java"/>
 
-- **No boilerplate.** Just load and start chatting or calling tools.
-- The API takes care of wiring up LLMs, tool invocation, and instruction handling.
+The API takes care of wiring up LLMs, tool invocation, and instruction handling.
 
-Ready to build your own AI-powered assistant? Just write your YAML, implement the tool logic in Java, and go!
+Here's a sample interaction:
 
+<TypewriterTextarea
+textContent='[You]: Book a hotel in Mysuru for two guests, from July 20 to July 22.
+Alright, I have booked the hotel! Room number 10 booked for 2 guests in Mysuru from July 20th to July 22nd. Here is your booking ID: HB-123'
+typingSpeed={30}
+pauseBetweenSentences={1200}
+height='110px'
+width='100%'
+/>
+
+Here's another one:
+
+<TypewriterTextarea
+textContent='[You]: Give me details of booking ID - HB-123.
+I found a booking for HB-123. Looks like the hotel is booked for 2 guests. Enjoy your stay!'
+typingSpeed={30}
+pauseBetweenSentences={1200}
+height='90px'
+width='100%'
+/>

docs/docs/metrics.md

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 6
 
-title: Metrics
+title: Metrics 🆕
 ---
 
 import CodeEmbed from '@site/src/components/CodeEmbed';

docs/package.json

@@ -15,10 +15,11 @@
     },
     "dependencies": {
         "@docsearch/js": "^4.1.0",
-        "@docusaurus/core": "^3.9.0",
-        "@docusaurus/plugin-google-gtag": "^3.9.1",
-        "@docusaurus/preset-classic": "^3.9.1",
-        "@docusaurus/theme-mermaid": "^3.9.1",
+        "@docusaurus/core": "^3.9.2",
+        "@docusaurus/plugin-google-gtag": "^3.9.2",
+        "@docusaurus/preset-classic": "^3.9.2",
+        "@docusaurus/theme-mermaid": "^3.9.2",
+        "@docusaurus/plugin-content-docs": "^3.9.2",
         "@iconify/react": "^6.0.2",
         "@mdx-js/react": "^3.1.1",
         "clsx": "^2.1.1",
@@ -30,8 +31,8 @@
         "react-image-gallery": "^1.4.0"
     },
     "devDependencies": {
-        "@docusaurus/module-type-aliases": "^3.9.1",
-        "@docusaurus/types": "^3.4.0"
+        "@docusaurus/module-type-aliases": "^3.9.2",
+        "@docusaurus/types": "^3.9.2"
     },
     "browserslist": {
         "production": [

pom.xml

@@ -19,7 +19,7 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven-surefire-plugin.version>3.5.4</maven-surefire-plugin.version>
         <maven-failsafe-plugin.version>3.5.4</maven-failsafe-plugin.version>
-        <lombok.version>1.18.40</lombok.version>
+        <lombok.version>1.18.42</lombok.version>
     </properties>
 
     <developers>
@@ -80,6 +80,7 @@
                 <configuration>
                     <!-- to disable the "missing" warnings. Remove the doclint to enable warnings-->
                     <doclint>all,-missing</doclint>
+                    <failOnError>false</failOnError>
                 </configuration>
                 <executions>
                     <execution>
@@ -272,7 +273,7 @@
         <dependency>
             <groupId>ch.qos.logback</groupId>
             <artifactId>logback-classic</artifactId>
-            <version>1.5.18</version>
+            <version>1.5.20</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -283,7 +284,7 @@
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-api</artifactId>
-            <version>5.13.4</version>
+            <version>6.0.0</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -346,7 +347,7 @@
                     <plugin>
                         <groupId>org.sonatype.central</groupId>
                         <artifactId>central-publishing-maven-plugin</artifactId>
-                        <version>0.8.0</version>
+                        <version>0.9.0</version>
                         <extensions>true</extensions>
                         <configuration>
                             <publishingServerId>mvn-repo-id</publishingServerId>
@@ -372,7 +373,7 @@
                     <plugin>
                         <groupId>org.jacoco</groupId>
                         <artifactId>jacoco-maven-plugin</artifactId>
-                        <version>0.8.13</version>
+                        <version>0.8.14</version>
                         <executions>
                             <execution>
                                 <goals>
@@ -483,7 +484,7 @@
                     <plugin>
                         <groupId>org.jacoco</groupId>
                         <artifactId>jacoco-maven-plugin</artifactId>
-                        <version>0.8.13</version>
+                        <version>0.8.14</version>
                         <executions>
                             <execution>
                                 <goals>

src/main/java/io/github/ollama4j/agent/Agent.java

@@ -38,44 +38,32 @@ import lombok.*;
  * </ul>
  */
 public class Agent {
-    /**
-     * The agent's display name
-     */
+    /** The agent's display name */
     private final String name;
 
-    /**
-     * List of supported tools for this agent
-     */
+    /** List of supported tools for this agent */
     private final List<Tools.Tool> tools;
 
-    /**
-     * Ollama client instance for communication with the API
-     */
+    /** Ollama client instance for communication with the API */
     private final Ollama ollamaClient;
 
-    /**
-     * The model name used for chat completions
-     */
+    /** The model name used for chat completions */
     private final String model;
 
-    /**
-     * Persists chat message history across rounds
-     */
+    /** Persists chat message history across rounds */
     private final List<OllamaChatMessage> chatHistory;
 
-    /**
-     * Optional custom system prompt for the agent
-     */
+    /** Optional custom system prompt for the agent */
     private final String customPrompt;
 
     /**
      * Constructs a new Agent.
      *
-     * @param name         The agent's given name.
+     * @param name The agent's given name.
      * @param ollamaClient The Ollama API client instance to use.
-     * @param model        The model name to use for chat completion.
+     * @param model The model name to use for chat completion.
      * @param customPrompt A custom prompt to prepend to all conversations (may be null).
-     * @param tools        List of available tools for function calling.
+     * @param tools List of available tools for function calling.
      */
     public Agent(
             String name,
@@ -149,6 +137,7 @@ public class Agent {
             }
             Ollama ollama = new Ollama(agentSpec.getHost());
             ollama.setRequestTimeoutSeconds(120);
+            ollama.pullModel(agentSpec.getModel());
             return new Agent(
                     agentSpec.getName(),
                     ollama,
@@ -161,21 +150,17 @@ public class Agent {
     }
 
     /**
-     * Facilitates a single round of chat for the agent:
+     * Conducts a conversational interaction with the agent.
      *
-     * <ul>
-     *   <li>Builds/promotes the system prompt on the first turn if necessary
-     *   <li>Adds the user's input to chat history
-     *   <li>Submits the chat turn to the Ollama model (with tool/function support)
-     *   <li>Updates internal chat history in accordance with the Ollama chat result
-     * </ul>
-     *
-     * @param userInput The user's message or question for the agent.
-     * @return The model's response as a string.
-     * @throws OllamaException If there is a problem with the Ollama API.
+     * @param userInput the user's question, instruction, or message for the agent.
+     * @param chatTokenHandler an optional handler for receiving streaming token updates from the model as it generates a reply.
+     *                         Can be {@code null} if streaming output is not needed.
+     * @return Updated chat history, as a list of {@link OllamaChatMessage} objects representing the complete conversation so far.
+     *         This includes system, user, assistant, and any tool/function calls/results.
+     * @throws OllamaException if an error occurs communicating with the Ollama API or running tools.
      */
-    public String interact(String userInput, OllamaChatStreamObserver chatTokenHandler)
-            throws OllamaException {
+    public List<OllamaChatMessage> interact(
+            String userInput, OllamaChatStreamObserver chatTokenHandler) throws OllamaException {
         // Build a concise and readable description of available tools
         String availableToolsDescription =
                 tools.isEmpty()
@@ -217,11 +202,10 @@ public class Agent {
                         .build();
         OllamaChatResult response = ollamaClient.chat(request, chatTokenHandler);
 
-        // Update chat history for continuity
         chatHistory.clear();
         chatHistory.addAll(response.getChatHistory());
 
-        return response.getResponseModel().getMessage().getResponse();
+        return response.getChatHistory();
     }
 
     /**
@@ -279,35 +263,23 @@ public class Agent {
     @Getter
     @EqualsAndHashCode(callSuper = false)
     private static class AgentToolSpec extends Tools.ToolSpec {
-        /**
-         * Fully qualified class name of the tool's {@link ToolFunction} implementation
-         */
+        /** Fully qualified class name of the tool's {@link ToolFunction} implementation */
         private String toolFunctionFQCN = null;
 
-        /**
-         * Instance of the {@link ToolFunction} to invoke
-         */
+        /** Instance of the {@link ToolFunction} to invoke */
         private ToolFunction toolFunctionInstance = null;
     }
 
-    /**
-     * Bean for describing a tool function parameter for use in agent YAML definitions.
-     */
+    /** Bean for describing a tool function parameter for use in agent YAML definitions. */
     @Data
     public class AgentToolParameter {
-        /**
-         * The parameter's type (e.g., string, number, etc.)
-         */
+        /** The parameter's type (e.g., string, number, etc.) */
         private String type;
 
-        /**
-         * Description of the parameter
-         */
+        /** Description of the parameter */
         private String description;
 
-        /**
-         * Whether this parameter is required
-         */
+        /** Whether this parameter is required */
         private boolean required;
 
         /**