fix(rag): RAG-retrieved use USER role, AGENTIC RAG mode add missing retrieveConfig (#949)

## AgentScope-Java Version

1.0.11

## Description

* RAG-retrieved use USER role, Fixes: #941 
* AGENTIC RAG mode add missing retrieveConfig, Fixes: #932 

## Checklist

Please check the following items before code is ready to be reviewed.

- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review

Author: guanxuc

agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java

@@ -1439,7 +1439,7 @@ private void configureRAG(Toolkit agentToolkit) {
                 case AGENTIC -> {
                     // Register knowledge retrieval tools
                     KnowledgeRetrievalTools tools =
-                            new KnowledgeRetrievalTools(aggregatedKnowledge);
+                            new KnowledgeRetrievalTools(aggregatedKnowledge, retrieveConfig);
                     agentToolkit.registerTool(tools);
                 }
                 case NONE -> {

agentscope-core/src/main/java/io/agentscope/core/rag/GenericRAGHook.java

@@ -41,7 +41,7 @@
  * <ol>
  *   <li>Extracts the query from user messages</li>
  *   <li>Retrieves relevant documents from the knowledge base</li>
- *   <li>Injects the retrieved knowledge as a system message</li>
+ *   <li>Injects the retrieved knowledge as a user message</li>
  *   <li>Modifies the input messages to include the knowledge context</li>
  * </ol>
  *
@@ -82,7 +82,7 @@ public class GenericRAGHook implements Hook {
      * @throws IllegalArgumentException if knowledgeBase is null
      */
     public GenericRAGHook(Knowledge knowledge) {
-        this(knowledge, RetrieveConfig.builder().limit(5).scoreThreshold(0.5).build());
+        this(knowledge, RetrieveConfig.builder().build());
     }
 
     /**
@@ -198,8 +198,8 @@ private Msg createEnhancedMessages(List<Document> retrievedDocs) {
         String knowledgeContent = buildKnowledgeContent(retrievedDocs);
 
         return Msg.builder()
-                .name("system")
-                .role(MsgRole.SYSTEM)
+                .name("user")
+                .role(MsgRole.USER)
                 .content(TextBlock.builder().text(knowledgeContent).build())
                 .build();
     }

agentscope-core/src/main/java/io/agentscope/core/rag/KnowledgeRetrievalTools.java

@@ -37,7 +37,7 @@
  * <p>Example usage:
  * <pre>{@code
  * KnowledgeBase knowledgeBase = new SimpleKnowledge(embeddingModel, vectorStore);
- * KnowledgeRetrievalTools tools = new KnowledgeRetrievalTools(knowledgeBase);
+ * KnowledgeRetrievalTools tools = new KnowledgeRetrievalTools(knowledgeBase, RetrieveConfig.builder().build());
  *
  * Toolkit toolkit = new Toolkit();
  * toolkit.registerObject(tools);
@@ -53,17 +53,40 @@ public class KnowledgeRetrievalTools {
 
     private final Knowledge knowledge;
 
+    private final RetrieveConfig defaultConfig;
+
     /**
-     * Creates a new KnowledgeRetrievalTools instance.
+     * Creates a new KnowledgeRetrievalTools instance with default configuration.
+     *
+     * <p>Default configuration:
+     * <ul>
+     *   <li>Limit: 5 documents</li>
+     *   <li>Score threshold: 0.5</li>
+     * </ul>
      *
      * @param knowledge the knowledge base to retrieve from
      * @throws IllegalArgumentException if knowledgeBase is null
      */
     public KnowledgeRetrievalTools(Knowledge knowledge) {
+        this(knowledge, RetrieveConfig.builder().build());
+    }
+
+    /**
+     * Creates a new KnowledgeRetrievalTools instance.
+     *
+     * @param knowledge     the knowledge base to retrieve from
+     * @param defaultConfig the default retrieval configuration
+     * @throws IllegalArgumentException if knowledgeBase is null
+     */
+    public KnowledgeRetrievalTools(Knowledge knowledge, RetrieveConfig defaultConfig) {
         if (knowledge == null) {
             throw new IllegalArgumentException("Knowledge base cannot be null");
         }
+        if (defaultConfig == null) {
+            throw new IllegalArgumentException("Retrieve config cannot be null");
+        }
         this.knowledge = knowledge;
+        this.defaultConfig = defaultConfig;
     }
 
     /**
@@ -121,9 +144,9 @@ public String retrieveKnowledge(
 
         // Build retrieval config with conversation history
         RetrieveConfig config =
-                RetrieveConfig.builder()
+                this.defaultConfig
+                        .mutate()
                         .limit(limit)
-                        .scoreThreshold(0.5)
                         .conversationHistory(conversationHistory)
                         .build();
 
@@ -172,4 +195,13 @@ private String formatDocumentsForTool(List<Document> documents) {
     public Knowledge getKnowledgeBase() {
         return knowledge;
     }
+
+    /**
+     * Gets the default retrieval configuration.
+     *
+     * @return the default config
+     */
+    public RetrieveConfig getDefaultConfig() {
+        return defaultConfig;
+    }
 }

agentscope-core/src/main/java/io/agentscope/core/rag/model/RetrieveConfig.java

@@ -78,6 +78,19 @@ public List<Msg> getConversationHistory() {
         return conversationHistory;
     }
 
+    /**
+     * Mutate the current instance to a new builder.
+     *
+     * @return a new builder with the same values of this instance
+     */
+    public Builder mutate() {
+        return new Builder()
+                .limit(this.limit)
+                .scoreThreshold(this.scoreThreshold)
+                .vectorName(this.vectorName)
+                .conversationHistory(this.conversationHistory);
+    }
+
     /**
      * Creates a new builder instance.
      *

agentscope-core/src/test/java/io/agentscope/core/rag/model/RetrieveConfigTest.java

@@ -18,6 +18,8 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
+import io.agentscope.core.message.Msg;
+import java.util.List;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
@@ -101,4 +103,17 @@ void testBuilderChaining() {
         assertEquals(0.8, config.getScoreThreshold());
         assertEquals("test-vector", config.getVectorName());
     }
+
+    @Test
+    @DisplayName("Should mutate RetrieveConfig with same values")
+    void testMutate() {
+        RetrieveConfig originConfig = RetrieveConfig.builder().build();
+        List<Msg> conversationHistory = List.of(Msg.builder().textContent("test content").build());
+        RetrieveConfig mutateConfig =
+                originConfig.mutate().conversationHistory(conversationHistory).build();
+        assertEquals(conversationHistory, mutateConfig.getConversationHistory());
+        assertEquals(originConfig.getLimit(), mutateConfig.getLimit());
+        assertEquals(originConfig.getScoreThreshold(), mutateConfig.getScoreThreshold());
+        assertEquals(originConfig.getVectorName(), mutateConfig.getVectorName());
+    }
 }

agentscope-extensions/agentscope-extensions-rag-simple/src/test/java/io/agentscope/core/rag/KnowledgeRetrievalToolsTest.java

@@ -22,11 +22,13 @@
 
 import io.agentscope.core.embedding.EmbeddingModel;
 import io.agentscope.core.message.ContentBlock;
+import io.agentscope.core.message.Msg;
 import io.agentscope.core.message.TextBlock;
 import io.agentscope.core.message.ToolResultBlock;
 import io.agentscope.core.rag.knowledge.SimpleKnowledge;
 import io.agentscope.core.rag.model.Document;
 import io.agentscope.core.rag.model.DocumentMetadata;
+import io.agentscope.core.rag.model.RetrieveConfig;
 import io.agentscope.core.rag.store.InMemoryStore;
 import io.agentscope.core.tool.AgentTool;
 import io.agentscope.core.tool.ToolCallParam;
@@ -51,6 +53,7 @@ class KnowledgeRetrievalToolsTest {
     private static final int DIMENSIONS = 3;
 
     private Knowledge knowledge;
+    private RetrieveConfig retrieveConfig;
     private KnowledgeRetrievalTools tools;
     private Toolkit toolkit;
 
@@ -63,16 +66,29 @@ void setUp() {
                         .embeddingModel(embeddingModel)
                         .embeddingStore(vectorStore)
                         .build();
-        tools = new KnowledgeRetrievalTools(knowledge);
+        retrieveConfig = RetrieveConfig.builder().build();
+        tools = new KnowledgeRetrievalTools(knowledge, retrieveConfig);
         toolkit = new Toolkit();
     }
 
     @Test
     @DisplayName("Should create KnowledgeRetrievalTools with valid knowledge base")
     void testCreate() {
+        KnowledgeRetrievalTools newTools = new KnowledgeRetrievalTools(knowledge, retrieveConfig);
+        assertNotNull(newTools);
+        assertEquals(knowledge, newTools.getKnowledgeBase());
+        assertEquals(retrieveConfig, newTools.getDefaultConfig());
+    }
+
+    @Test
+    @DisplayName("Should create KnowledgeRetrievalTools with default config")
+    void testCreateWithDefaultConfig() {
         KnowledgeRetrievalTools newTools = new KnowledgeRetrievalTools(knowledge);
         assertNotNull(newTools);
         assertEquals(knowledge, newTools.getKnowledgeBase());
+        assertNotNull(newTools.getDefaultConfig());
+        assertEquals(5, newTools.getDefaultConfig().getLimit());
+        assertEquals(0.5, newTools.getDefaultConfig().getScoreThreshold());
     }
 
     @Test
@@ -81,6 +97,35 @@ void testCreateNullKnowledgeBase() {
         assertThrows(IllegalArgumentException.class, () -> new KnowledgeRetrievalTools(null));
     }
 
+    @Test
+    @DisplayName("Should throw exception for null retrieve config")
+    void testCreateNullConfig() {
+        assertThrows(
+                IllegalArgumentException.class, () -> new KnowledgeRetrievalTools(knowledge, null));
+    }
+
+    @Test
+    @DisplayName("Should create KnowledgeRetrievalTools with custom retrieve config")
+    void testCreateCustomRetrieveConfig() {
+        List<Msg> conversationHistory = List.of(Msg.builder().textContent("Hello").build());
+        RetrieveConfig customRetrieveConfig =
+                RetrieveConfig.builder()
+                        .limit(3)
+                        .scoreThreshold(0.9)
+                        .vectorName("test_vector")
+                        .conversationHistory(conversationHistory)
+                        .build();
+        KnowledgeRetrievalTools newTools =
+                new KnowledgeRetrievalTools(knowledge, customRetrieveConfig);
+        assertNotNull(newTools);
+        assertEquals(knowledge, newTools.getKnowledgeBase());
+        assertEquals(customRetrieveConfig, newTools.getDefaultConfig());
+        assertEquals(3, newTools.getDefaultConfig().getLimit());
+        assertEquals(0.9, newTools.getDefaultConfig().getScoreThreshold());
+        assertEquals("test_vector", newTools.getDefaultConfig().getVectorName());
+        assertEquals(conversationHistory, newTools.getDefaultConfig().getConversationHistory());
+    }
+
     @Test
     @DisplayName("Should register tool with Toolkit")
     void testToolRegistration() {

agentscope-extensions/agentscope-extensions-rag-simple/src/test/java/io/agentscope/core/rag/hook/GenericRAGHookTest.java

@@ -16,6 +16,7 @@
 package io.agentscope.core.rag.hook;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -101,6 +102,8 @@ void testCreateWithDefaults() {
         assertNotNull(newHook);
         assertEquals(knowledge, newHook.getKnowledgeBase());
         assertNotNull(newHook.getDefaultConfig());
+        assertEquals(5, newHook.getDefaultConfig().getLimit());
+        assertEquals(0.5, newHook.getDefaultConfig().getScoreThreshold());
     }
 
     @Test
@@ -149,16 +152,20 @@ void testHandlePreCallEvent() {
         StepVerifier.create(hook.onEvent(event))
                 .assertNext(
                         result -> {
-                            assertTrue(result instanceof PreCallEvent);
-                            PreCallEvent preCallEvent = (PreCallEvent) result;
-                            List<Msg> enhancedMessages = preCallEvent.getInputMessages();
+                            assertInstanceOf(PreCallEvent.class, result);
+                            List<Msg> enhancedMessages = result.getInputMessages();
 
                             // Should have knowledge message + original message
                             assertTrue(enhancedMessages.size() >= 2);
-                            // First message should be system message with knowledge
-                            Msg firstMsg = enhancedMessages.get(1);
-                            assertEquals(MsgRole.SYSTEM, firstMsg.getRole());
-                            assertTrue(firstMsg.getTextContent().contains("knowledge base"));
+                            // First message should be user message with question
+                            assertEquals(MsgRole.USER, enhancedMessages.get(0).getRole());
+                            // Second message should be user message with knowledge retrieval
+                            assertEquals(MsgRole.USER, enhancedMessages.get(1).getRole());
+                            assertTrue(
+                                    enhancedMessages
+                                            .get(1)
+                                            .getTextContent()
+                                            .contains("knowledge base"));
                         })
                 .verifyComplete();
     }