Add swarm stopping condition example

docs/mkdocs.yml

@@ -345,6 +345,7 @@ nav:
       - Sequential Workflow Example: "swarms/examples/sequential_example.md"
       - SwarmRouter Example: "swarms/examples/swarm_router.md"
       - ConcurrentWorkflow Example: "swarms/examples/concurrent_workflow.md"
+      - Stopping Condition Swarm: "swarms/examples/swarm_stopping_condition.md"
       - MixtureOfAgents Example: "swarms/examples/mixture_of_agents.md"
       - Unique Swarms: "swarms/examples/unique_swarms.md"
       - Agents as Tools: "swarms/examples/agents_as_tools.md"

docs/swarms/examples/swarm_stopping_condition.md

@@ -0,0 +1,48 @@
+# Swarm Stopping Condition Example
+
+This example demonstrates how to configure a swarm so that it halts execution once a custom stopping function evaluates to `True`.
+
+```python
+from swarms import Agent, check_done
+from swarms.structs.round_robin import RoundRobinSwarm
+
+class StoppableRoundRobinSwarm(RoundRobinSwarm):
+    def __init__(self, *args, stopping_function=None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.stopping_function = stopping_function
+
+    def run(self, task: str, *args, **kwargs):
+        result = task
+        n = len(self.agents)
+        for _ in range(self.max_loops):
+            for _ in range(n):
+                agent = self.agents[self.index]
+                result = self._execute_agent(agent, result, *args, **kwargs)
+                self.index = (self.index + 1) % n
+                if self.stopping_function and self.stopping_function(result):
+                    print("Stopping condition met.")
+                    return result
+        return result
+
+agent1 = Agent(
+    agent_name="Worker-1",
+    system_prompt="Return <DONE> when finished.",
+    stopping_func=check_done,
+)
+
+agent2 = Agent(
+    agent_name="Worker-2",
+    system_prompt="Return <DONE> when finished.",
+    stopping_func=check_done,
+)
+
+swarm = StoppableRoundRobinSwarm(
+    agents=[agent1, agent2],
+    max_loops=3,
+    stopping_function=check_done,
+)
+
+swarm.run("Collect and summarize data.")
+```
+
+For the full script see [swarm_stopping_condition.py](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/swarm_stopping_condition.py).

docs/swarms/structs/abstractswarm.md

@@ -399,6 +399,12 @@ worker_id = "worker_123"
 swarm.stop_worker(worker, worker_id)
 ```
 
+### Stopping Conditions
+
+Use a stopping function to halt a swarm when a specific output is detected. See
+[this example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/swarm_stopping_condition.py)
+for a runnable demonstration.
+
 ### `restart_worker(worker: "AbstractWorker")` <a name="restart_worker"></a>
 
 The `restart_worker()` method restarts a worker, resetting them to their initial state.

examples/multi_agent/swarm_stopping_condition.py

@@ -0,0 +1,49 @@
+"""Example of applying stopping conditions to a swarm."""
+
+from swarms import Agent, check_done
+from swarms.structs.round_robin import RoundRobinSwarm
+
+
+class StoppableRoundRobinSwarm(RoundRobinSwarm):
+    """Round-robin swarm that stops when a condition is met."""
+
+    def __init__(self, *args, stopping_function=None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.stopping_function = stopping_function
+
+    def run(self, task: str, *args, **kwargs):
+        result = task
+        n = len(self.agents)
+        for _ in range(self.max_loops):
+            for _ in range(n):
+                agent = self.agents[self.index]
+                result = self._execute_agent(agent, result, *args, **kwargs)
+                self.index = (self.index + 1) % n
+                if self.stopping_function and self.stopping_function(result):
+                    print("Stopping condition met.")
+                    return result
+        return result
+
+
+agent1 = Agent(
+    agent_name="Worker-1",
+    system_prompt="Return <DONE> when finished.",
+    stopping_func=check_done,
+    max_loops=5,
+)
+
+agent2 = Agent(
+    agent_name="Worker-2",
+    system_prompt="Return <DONE> when finished.",
+    stopping_func=check_done,
+    max_loops=5,
+)
+
+swarm = StoppableRoundRobinSwarm(
+    agents=[agent1, agent2],
+    max_loops=3,
+    stopping_function=check_done,
+)
+
+result = swarm.run("Collect and summarize data.")
+print(result)