Skip to content

Agent Zero AI framework

Add "wait" tool

linuztx8b16272bd7ac
diff --git a/prompts/agent.system.tool.wait.md b/prompts/agent.system.tool.wait.md
new file mode 100644
index 000000000..e8a30b096
--- /dev/null
+++ b/prompts/agent.system.tool.wait.md
@@ -0,0 +1,34 @@
+### wait
+pause execution for a set time or until a timestamp
+use args "seconds" "minutes" "hours" "days" for duration
+use "until" with ISO timestamp for a specific time
+usage:
+
+1 wait duration
+~~~json
+{
+ "thoughts": [
+ "I need to wait..."
+ ],
+ "headline": "...",
+ "tool_name": "wait",
+ "tool_args": {
+ "minutes": 1,
+ "seconds": 30
+ }
+}
+~~~
+
+2 wait timestamp
+~~~json
+{
+ "thoughts": [
+ "I will wait until..."
+ ],
+ "headline": "...",
+ "tool_name": "wait",
+ "tool_args": {
+ "until": "2025-10-20T10:00:00Z"
+ }
+}
+~~~
diff --git a/prompts/fw.wait_complete.md b/prompts/fw.wait_complete.md
new file mode 100644
index 000000000..3b6d6124d
--- /dev/null
+++ b/prompts/fw.wait_complete.md
@@ -0,0 +1 @@
+Wait complete. Reached {{target_time}}.
\ No newline at end of file
diff --git a/python/helpers/wait.py b/python/helpers/wait.py
new file mode 100644
index 000000000..83f288619
--- /dev/null
+++ b/python/helpers/wait.py
@@ -0,0 +1,68 @@
+import asyncio
+from datetime import datetime, timezone
+
+from python.helpers.print_style import PrintStyle
+
+
+def format_remaining_time(total_seconds: float) -> str:
+ if total_seconds < 0:
+ total_seconds = 0
+
+ days, remainder = divmod(total_seconds, 86400)
+ hours, remainder = divmod(remainder, 3600)
+ minutes, seconds = divmod(remainder, 60)
+
+ days = int(days)
+ hours = int(hours)
+ minutes = int(minutes)
+
+ parts = []
+ if days > 0:
+ parts.append(f"{days}d")
+ if hours > 0:
+ parts.append(f"{hours}h")
+ if minutes > 0:
+ parts.append(f"{minutes}m")
+
+ if days > 0 or hours > 0:
+ if seconds >= 1:
+ parts.append(f"{int(seconds)}s")
+ elif minutes > 0:
+ if seconds >= 0.1:
+ parts.append(f"{seconds:.1f}s")
+ else:
+ parts.append(f"{total_seconds:.1f}s")
+
+ if not parts:
+ return "0.0s remaining"
+
+ return " ".join(parts) + " remaining"
+
+
+async def managed_wait(agent, target_time, is_duration_wait, log, get_heading_callback):
+
+ while datetime.now(timezone.utc) < target_time:
+ before_intervention = datetime.now(timezone.utc)
+ await agent.handle_intervention()
+ after_intervention = datetime.now(timezone.utc)
+
+ if is_duration_wait:
+ pause_duration = after_intervention - before_intervention
+ if pause_duration.total_seconds() > 1.5: # Adjust for pauses longer than the sleep cycle
+ target_time += pause_duration
+ PrintStyle.info(
+ f"Wait extended by {pause_duration.total_seconds():.1f}s to {target_time.isoformat()}...",
+ )
+
+ current_time = datetime.now(timezone.utc)
+ if current_time >= target_time:
+ break
+
+ remaining_seconds = (target_time - current_time).total_seconds()
+ if log:
+ log.update(heading=get_heading_callback(format_remaining_time(remaining_seconds)))
+ sleep_duration = min(1.0, remaining_seconds)
+
+ await asyncio.sleep(sleep_duration)
+
+ return target_time
diff --git a/python/tools/wait.py b/python/tools/wait.py
new file mode 100644
index 000000000..f39cc0a9d
--- /dev/null
+++ b/python/tools/wait.py
@@ -0,0 +1,89 @@
+import asyncio
+from datetime import datetime, timedelta, timezone
+from python.helpers.tool import Tool, Response
+from python.helpers.print_style import PrintStyle
+from python.helpers.wait import managed_wait
+from python.helpers.localization import Localization
+
+class WaitTool(Tool):
+
+ async def execute(self, **kwargs) -> Response:
+ await self.agent.handle_intervention()
+
+ seconds = self.args.get("seconds", 0)
+ minutes = self.args.get("minutes", 0)
+ hours = self.args.get("hours", 0)
+ days = self.args.get("days", 0)
+ until_timestamp_str = self.args.get("until")
+
+ is_duration_wait = not bool(until_timestamp_str)
+
+ now = datetime.now(timezone.utc)
+ target_time = None
+
+ if until_timestamp_str:
+ try:
+ target_time = Localization.get().localtime_str_to_utc_dt(until_timestamp_str)
+ if not target_time:
+ raise ValueError(f"Invalid timestamp format: {until_timestamp_str}")
+ except ValueError as e:
+ return Response(
+ message=str(e),
+ break_loop=False,
+ )
+ else:
+ wait_duration = timedelta(
+ days=int(days),
+ hours=int(hours),
+ minutes=int(minutes),
+ seconds=int(seconds),
+ )
+ if wait_duration.total_seconds() <= 0:
+ return Response(
+ message="Wait duration must be positive.",
+ break_loop=False,
+ )
+ target_time = now + wait_duration
+
+ if target_time <= now:
+ return Response(
+ message=f"Target time {target_time.isoformat()} is in the past.",
+ break_loop=False,
+ )
+
+ PrintStyle.info(f"Waiting until {target_time.isoformat()}...")
+
+ target_time = await managed_wait(
+ agent=self.agent,
+ target_time=target_time,
+ is_duration_wait=is_duration_wait,
+ log=self.log,
+ get_heading_callback=self.get_heading
+ )
+
+ if self.log:
+ self.log.update(heading=self.get_heading("Done", done=True))
+
+ message = self.agent.read_prompt(
+ "fw.wait_complete.md",
+ target_time=target_time.isoformat()
+ )
+
+ return Response(
+ message=message,
+ break_loop=False,
+ )
+
+ def get_log_object(self):
+ return self.agent.context.log.log(
+ type="progress",
+ heading=self.get_heading(),
+ content="",
+ kvps=self.args,
+ )
+
+ def get_heading(self, text: str = "", done: bool = False):
+ done_icon = " icon://done_all" if done else ""
+ if not text:
+ text = f"Waiting..."
+ return f"icon://timer wait: {text}{done_icon}"