fix: add docs

Author: VLSMB

spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/LoopAgent.java

@@ -27,6 +27,31 @@
 import java.util.List;
 
 /**
+ * Loop Agent that supports multiple loop modes:
+ * <ul>
+ * <li><b>COUNT</b>: Execute a fixed number of loops</li>
+ * <li><b>CONDITION</b>: Continue looping based on a condition, similar to a do-while
+ * structure, but when the condition is true, terminate the loop</li>
+ * <li><b>JSON_ARRAY</b>: Parse a JSON array and iterate over its elements</li>
+ * <li><b>Other Loop Strategy</b>: Users can implement the LoopStrategy interface according to their needs.</li>
+ * </ul>
+ *
+ * <p>
+ * <b>Note:</b> The LoopAgent must have a subAgent, which is the agent that will be executed in each loop.
+ * </p>
+ *
+ * <p>
+ * Usage example:
+ * </p>
+ * <pre>{@code
+ * LoopAgent loopAgent = LoopAgent.builder()
+ *     .name("example-loop-agent")
+ *     .description("Example loop agent")
+ *     .loopStrategy(LoopMode.condition(messagePredicate))
+ *     .subAgent(subAgent)
+ *     .build();
+ * }</pre>
+ *
  * @author vlsmb
  * @since 2025/8/25
  */

spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/loop/ArrayLoopStrategy.java

@@ -1,36 +1,61 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.alibaba.cloud.ai.graph.agent.flow.agent.loop;
 
 import com.alibaba.cloud.ai.graph.OverAllState;
 import org.springframework.ai.chat.messages.Message;
 import org.springframework.ai.chat.messages.SystemMessage;
 import org.springframework.ai.chat.messages.UserMessage;
 import org.springframework.ai.util.json.JsonParser;
+import org.springframework.core.convert.converter.Converter;
 
 import java.util.List;
 import java.util.Map;
 
+/**
+ * JSON array loop strategy that retrieves a JSON array from the current message state,
+ * sends each array element as a message to the model, and returns the result.
+ * By default, the text of the last message is treated as a JSON array, but users can customize the converter.
+ *
+ * @author vlsmb
+ * @since 2025/11/1
+ */
 public class ArrayLoopStrategy implements LoopStrategy {
 
+    private final Converter<List<Message>, List<?>> converter;
+
+    public ArrayLoopStrategy(Converter<List<Message>, List<?>> converter) {
+        this.converter = converter;
+    }
+
+    public ArrayLoopStrategy() {
+        this(DEFAULT_MESSAGE_CONVERTER);
+    }
+
     @Override
     public Map<String, Object> loopInit(OverAllState state) {
         @SuppressWarnings("unchecked")
         List<Message> messages = (List<Message>) state.value(LoopStrategy.MESSAGE_KEY).orElse(List.of());
-        String lastMessage;
-        if(!messages.isEmpty()) {
-            lastMessage = messages.get(messages.size() - 1).getText();
-        } else {
-            lastMessage = null;
-        }
-        if(lastMessage == null) {
-            return Map.of(loopCountKey(), 0, loopFlagKey(), false, loopListKey(), List.of());
-        }
-        try {
-            List<?> list = JsonParser.fromJson(lastMessage, List.class);
+        List<?> list = converter.convert(messages);
+        if(list != null) {
             return Map.of(loopCountKey(), 0, loopFlagKey(), true, loopListKey(), list);
-        } catch (Exception e) {
-            return Map.of(loopCountKey(), 0, loopFlagKey(), false, loopListKey(), List.of(),
-            LoopStrategy.MESSAGE_KEY, new SystemMessage("Invalid json array format"));
         }
+        return Map.of(loopCountKey(), 0, loopFlagKey(), false, loopListKey(), List.of(),
+                LoopStrategy.MESSAGE_KEY, new SystemMessage("Invalid json array format"));
     }
 
     @Override
@@ -45,4 +70,22 @@ public Map<String, Object> loopDispatch(OverAllState state) {
             return Map.of(loopFlagKey(), false);
         }
     }
+
+    /**
+     * 默认的转换器，将最后一个消息的文本作为json数组
+     */
+    private static final Converter<List<Message>, List<?>> DEFAULT_MESSAGE_CONVERTER =
+            messages -> {
+                String lastMessage;
+                if(!messages.isEmpty()) {
+                    lastMessage = messages.get(messages.size() - 1).getText();
+                } else {
+                    lastMessage = null;
+                }
+                if(lastMessage == null) {
+                    return null;
+                }
+                return JsonParser.fromJson(lastMessage, List.class);
+            };
+
 }

spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/loop/ConditionLoopStrategy.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.alibaba.cloud.ai.graph.agent.flow.agent.loop;
 
 import com.alibaba.cloud.ai.graph.OverAllState;
@@ -8,6 +24,12 @@
 import java.util.Map;
 import java.util.function.Predicate;
 
+/**
+ * Conditional loop strategy that retries until the Predicate is satisfied or the maximum count is reached.
+ *
+ * @author vlsmb
+ * @since 2025/11/1
+ */
 public class ConditionLoopStrategy implements LoopStrategy {
 
     private final Predicate<List<Message>> messagePredicate;

spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/loop/CountLoopStrategy.java

@@ -1,9 +1,31 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.alibaba.cloud.ai.graph.agent.flow.agent.loop;
 
 import com.alibaba.cloud.ai.graph.OverAllState;
 
 import java.util.Map;
 
+/**
+ * Fixed count loop strategy
+ *
+ * @author vlsmb
+ * @since 2025/11/1
+ */
 public class CountLoopStrategy implements LoopStrategy {
 
     private final int maxCount;

spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/loop/LoopMode.java

@@ -17,10 +17,17 @@
 package com.alibaba.cloud.ai.graph.agent.flow.agent.loop;
 
 import org.springframework.ai.chat.messages.Message;
+import org.springframework.core.convert.converter.Converter;
 
 import java.util.List;
 import java.util.function.Predicate;
 
+/**
+ * Built-in loop strategies for LoopAgent
+ *
+ * @author vlsmb
+ * @since 2025/11/1
+ */
 public final class LoopMode {
     private LoopMode() {
         throw new UnsupportedOperationException();
@@ -34,6 +41,10 @@ public static ArrayLoopStrategy array() {
         return new ArrayLoopStrategy();
     }
 
+    public static ArrayLoopStrategy array(Converter<List<Message>, List<?>> converter) {
+        return new ArrayLoopStrategy(converter);
+    }
+
     public static ConditionLoopStrategy condition(Predicate<List<Message>> messagePredicate) {
         return new ConditionLoopStrategy(messagePredicate);
     }

spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/loop/LoopStrategy.java

@@ -22,9 +22,10 @@
 import java.util.Map;
 
 /**
- * LoopAgent的循环策略，用来控制LoopAgent的行为。
- * 这部分相当于定义了LoopAgent对应StateGraph的loopInitNode和loopDispatchNode。
- * 在使用的时候可以直接使用LoopMode提供的内置策略，如果需要自定义循环逻辑，可以实现本接口。
+ * <p>Loop strategy for LoopAgent, used to control the behavior of LoopAgent.</p>
+ * <p>This part is equivalent to defining the loopInitNode and loopDispatchNode for the StateGraph corresponding to LoopAgent.</p>
+ * <p>Built-in strategies provided by LoopMode can be used directly when in use. If custom loop logic is required, this interface can be implemented.</p>
+ *
  * @author vlsmb
  * @since 2025/11/1
  */

spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/LoopGraphBuildingStrategy.java

@@ -38,6 +38,15 @@
 import static com.alibaba.cloud.ai.graph.action.AsyncEdgeAction.edge_async;
 import static com.alibaba.cloud.ai.graph.action.AsyncNodeAction.node_async;
 
+/**
+ * Converts a LoopAgent into its corresponding StateGraph.
+ * <p>
+ * Structure of the loop graph: START -> LoopInitLoop -> LoopDispatchNode (condition met -> SubAgentNode -> LoopDispatchNode; condition not met -> END)
+ * </p>
+ *
+ * @author vlsmb
+ * @since 2025/8/25
+ */
 public class LoopGraphBuildingStrategy implements FlowGraphBuildingStrategy {
 
     @Override
@@ -51,7 +60,8 @@ public StateGraph buildGraph(FlowGraphBuilder.FlowGraphConfig config) throws Gra
         // Add starting edge
         graph.addEdge(START, rootAgent.name());
 
-        // 根据loopStrategy构造循环图
+
+        // Build loop graph based on loopStrategy
         LoopStrategy loopStrategy = (LoopStrategy) config.getCustomProperty(LoopAgent.LOOP_STRATEGY);
         graph.addNode(loopStrategy.loopInitNodeName(), node_async(loopStrategy::loopInit));
         graph.addEdge(rootAgent.name(), loopStrategy.loopInitNodeName());

spring-ai-alibaba-agent-framework/src/test/java/com/alibaba/cloud/ai/graph/agent/flow/LoopAgentTest.java

@@ -113,9 +113,9 @@ void testCountMode() throws Exception {
                 .name("loop_agent")
                 .description("循环执行一个任务，直到满足条件。")
                 .subAgent(this.blogAgent)
-                .loopStrategy(LoopMode.count(3))
+                .loopStrategy(LoopMode.count(2))
                 .build();
-        OverAllState state = loopAgent.invoke("写一篇关于杭州西湖的散文文章。").orElseThrow();
+        OverAllState state = loopAgent.invoke("帮我写一个Python Socket编程的demo，并优化代码").orElseThrow();
         logger.info("Result: {}", state.data());
         Optional<Object> optional = state.value("messages");
         assert optional.isPresent();
@@ -159,7 +159,7 @@ void testConditionMode() throws Exception {
     void testArrayMode() throws Exception {
         LoopAgent loopAgent = LoopAgent.builder()
                 .name("loop_agent")
-                .description("循环执行一个任务，直到满足条件。")
+                .description("循环执行任务。")
                 .subAgent(this.sqlAgent)
                 .loopStrategy(LoopMode.array())
                 .build();