From 24cf04314df10c4d6d5f280477feaa5a86f4f600 Mon Sep 17 00:00:00 2001
From: Pavan Kumar <66913595+ascender1729@users.noreply.github.com>
Date: Wed, 18 Jun 2025 21:38:28 +0530
Subject: [PATCH] Add swarm stopping condition example

---
 docs/mkdocs.yml                               |  1 +
 .../examples/swarm_stopping_condition.md      | 48 ++++++++++++++++++
 docs/swarms/structs/abstractswarm.md          |  6 +++
 .../multi_agent/swarm_stopping_condition.py   | 49 +++++++++++++++++++
 4 files changed, 104 insertions(+)
 create mode 100644 docs/swarms/examples/swarm_stopping_condition.md
 create mode 100644 examples/multi_agent/swarm_stopping_condition.py

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 164a74ae..e9045d5d 100644
--- a/docs/mkdocs.yml
+++ b/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"
diff --git a/docs/swarms/examples/swarm_stopping_condition.md b/docs/swarms/examples/swarm_stopping_condition.md
new file mode 100644
index 00000000..55d823f0
--- /dev/null
+++ b/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).
diff --git a/docs/swarms/structs/abstractswarm.md b/docs/swarms/structs/abstractswarm.md
index 82ebf44e..d83ab6e3 100644
--- a/docs/swarms/structs/abstractswarm.md
+++ b/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.
diff --git a/examples/multi_agent/swarm_stopping_condition.py b/examples/multi_agent/swarm_stopping_condition.py
new file mode 100644
index 00000000..85d91fbb
--- /dev/null
+++ b/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)