Sleep, Suspense, and Scheduling
AI agents sometimes need to pause execution to schedule recurring or future actions, wait before retrying an operation (e.g. for rate limiting), or wait for external state to be available.
Workflow SDK's sleep function enables Agents to pause execution without consuming resources, and resume at a specified time, after a specified duration, or in response to an external event. Workflow operations that suspend will survive restarts, new deploys, and infrastructure changes, independent of whether the suspense takes seconds or months.
See the sleep() API Reference for the full list of supported duration formats and detailed API documentation, and see the hooks documentation for more information on how to resume in response to external events.
Adding a sleep tool
Sleep is a built-in function in Workflow SDK. To expose it as a tool, wrap it in a tool definition. Learn more about how to define tools in Patterns for Defining Tools.
Define the tool
Add a new "sleep" tool to the tools defined in workflows/chat/steps/tools.ts:
Call sleep() from within a workflow context, not from within a step. executeSleep does not have "use step" because it runs in the workflow context where sleep() is available.
This already makes the full sleep functionality available to the Agent!
Show the tool status in the UI
To round it off, extend the UI to display the tool call status. This can be done either by displaying the tool call information directly, or by emitting custom data parts to the stream (see Streaming Updates from Tools for more details). Since there aren't any fine-grained progress updates to show, we'll display the tool call information directly:
Now, try out the Flight Booking Agent again, and ask it to sleep for 10 seconds before checking any flight. You'll see the agent pause, and the UI reflect the tool call status.
Use cases
Aside from providing sleep() as a tool, there are other use cases for Agents that commonly call for suspension and resumption.
Rate limiting
When hitting API rate limits, use RetryableError with a delay:
Related documentation
sleep()API Reference - Full API documentation with all duration formats- Workflows and Steps - Understanding workflow context
- Errors and Retries - Using
RetryableErrorwith delays