docs: document wait until and interrupt timeouts

Author: radu-mocanu

docs/human_in_the_loop.md

@@ -468,6 +468,57 @@ For a practical implementation, refer to the [email-triage-agent sample](https:/
 
 ---
 
+## Time triggers
+
+### WaitUntil
+
+Suspends the agent until an Orchestrator timer fires. The SDK stores the resume timestamp as part of the resume condition, and Orchestrator resumes the suspended job when that time is reached.
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `resume_time` | `datetime` | Absolute time when Orchestrator should resume the suspended job. Use a timezone-aware `datetime`; it is normalized to UTC before the trigger is created. |
+
+```python
+from langgraph.types import interrupt
+from uipath.platform.common import WaitUntil
+from datetime import datetime, timedelta, timezone
+
+resume_payload = interrupt(
+    WaitUntil(
+        resume_time=datetime.now(timezone.utc) + timedelta(minutes=5),
+    )
+)
+```
+
+This is intended for deployed jobs where Orchestrator owns the scheduler. In a local run there is no scheduler to fire the time trigger, so resume the interrupt explicitly when testing locally.
+
+---
+
+## Interrupt timeouts
+
+Typed interrupt models can also be given a timeout. The SDK creates both the requested resume trigger and a timer resume trigger; whichever fires first resumes the agent. Timeout resume values use reserved UiPath metadata so they cannot collide with user payload fields.
+
+```python
+from langgraph.types import interrupt
+from uipath.platform.common import InvokeProcess
+from uipath.platform.resume_triggers import assert_no_timeout, is_timeout
+
+result = interrupt(
+    InvokeProcess(
+        name="long-running-agent",
+        input_arguments={"message": "start"},
+        timeout=10,
+    )
+)
+
+if is_timeout(result):
+    result = retry_or_fallback()
+
+result = assert_no_timeout(result)
+```
+
+---
+
 ## Resuming with a plain value (API trigger)
 
 All the models above are typed interrupts that tie the agent's wait state to a specific UiPath operation. When you call `interrupt(...)` with a value that is **not** one of those models, most commonly a plain string but any JSON-serializable value works, the SDK creates an **API resume trigger**. The agent suspends and waits to be resumed by an explicit external API call rather than by polling a UiPath operation.

samples/README.md

@@ -15,6 +15,12 @@ This sample shows how to automate Outlook inbox organization with AI-powered rul
 ## [HITL inbox server](hitl-inbox-server)
 This sample demonstrates a FastAPI server for managing human-in-the-loop workflows with job submissions and inbox message approvals.
 
+## [Wait until agent](wait-until-agent)
+This sample demonstrates a LangGraph agent that suspends with `WaitUntil` and resumes when Orchestrator fires a timer resume trigger.
+
+## [Invoke process timeout agent](invoke-process-timeout-agent)
+This sample demonstrates `InvokeProcess(..., timeout=...)` and handling timeout resume values with the timeout helpers.
+
 ## [Multi agent supervisor, researcher, coder](multi-agent-supervisor-researcher-coder)
 This sample showcases a multi-agent system, involving a supervisor, a researcher, and a coder working in coordination to tackle complex tasks.
 

samples/invoke-process-timeout-agent/README.md

@@ -0,0 +1,8 @@
+# Invoke Process Timeout Agent
+
+This sample demonstrates timeout handling for typed interrupts.
+
+The parent graph invokes the child graph with `InvokeProcess(..., timeout=10)`. The child graph sleeps longer than the timeout, so Orchestrator resumes the parent through the timer trigger first. The parent checks the resume value with `is_timeout` and uses `assert_no_timeout` for the non-timeout path.
+
+Publish both graphs from this project before running the parent graph.
+

samples/invoke-process-timeout-agent/graph.py

@@ -0,0 +1,64 @@
+import asyncio
+from typing import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.types import interrupt
+from uipath.platform.common import InvokeProcess
+from uipath.platform.resume_triggers import assert_no_timeout, get_timeout, is_timeout
+
+CHILD_PROCESS_NAME = "timeout-child-agent"
+
+
+class ParentState(TypedDict, total=False):
+    message: str
+    status: str
+    child_result: str
+    timeout: dict[str, object]
+
+
+class ChildState(TypedDict, total=False):
+    message: str
+    result: str
+
+
+def parent_node(state: ParentState) -> ParentState:
+    child_result = interrupt(
+        InvokeProcess(
+            name=CHILD_PROCESS_NAME,
+            input_arguments={"message": state.get("message", "start child work")},
+            timeout=10,
+        )
+    )
+
+    if is_timeout(child_result):
+        timeout = get_timeout(child_result)
+        return {
+            "status": "timed out",
+            "timeout": timeout or {},
+        }
+
+    child_result = assert_no_timeout(child_result)
+    return {
+        "status": "completed",
+        "child_result": str(child_result),
+    }
+
+
+async def child_node(state: ChildState) -> ChildState:
+    await asyncio.sleep(300)
+    return {
+        "result": f"child completed: {state.get('message', '')}",
+    }
+
+
+parent_builder = StateGraph(ParentState)
+parent_builder.add_node("parent", parent_node)
+parent_builder.add_edge(START, "parent")
+parent_builder.add_edge("parent", END)
+parent_graph = parent_builder.compile()
+
+child_builder = StateGraph(ChildState)
+child_builder.add_node("child", child_node)
+child_builder.add_edge(START, "child")
+child_builder.add_edge("child", END)
+child_graph = child_builder.compile()

samples/invoke-process-timeout-agent/langgraph.json

@@ -0,0 +1,8 @@
+{
+  "dependencies": ["."],
+  "graphs": {
+    "timeout-parent-agent": "./graph.py:parent_graph",
+    "timeout-child-agent": "./graph.py:child_graph"
+  },
+  "env": ".env"
+}

samples/invoke-process-timeout-agent/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "invoke-process-timeout-agent"
+version = "0.0.1"
+description = "LangGraph sample showing InvokeProcess timeout handling"
+authors = [{ name = "John Doe", email = "john.doe@myemail.com" }]
+requires-python = ">=3.11"
+dependencies = [
+    "uipath",
+    "uipath-langchain",
+]
+
+[dependency-groups]
+dev = [
+    "uipath-dev",
+]

samples/invoke-process-timeout-agent/uipath.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://cloud.uipath.com/draft/2024-12/uipath",
+  "runtimeOptions": {
+    "isConversational": false
+  },
+  "packOptions": {
+    "fileExtensionsIncluded": [],
+    "filesIncluded": [],
+    "filesExcluded": [],
+    "directoriesExcluded": [],
+    "includeUvLock": true
+  },
+  "functions": {}
+}

samples/wait-until-agent/README.md

@@ -0,0 +1,6 @@
+# Wait Until Agent
+
+This sample demonstrates a LangGraph agent that suspends with `WaitUntil` and resumes when Orchestrator fires the timer resume trigger.
+
+The resume time is an absolute timezone-aware `datetime`. The SDK normalizes it to UTC before creating the timer trigger.
+

samples/wait-until-agent/graph.py

@@ -0,0 +1,31 @@
+from datetime import datetime, timedelta, timezone
+from typing import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.types import interrupt
+from uipath.platform.common import WaitUntil
+
+
+class State(TypedDict, total=False):
+    message: str
+    resumed_at: str
+    resume_payload: str
+
+
+def wait_until_node(state: State) -> State:
+    resume_time = datetime.now(timezone.utc) + timedelta(minutes=5)
+    resume_payload = interrupt(WaitUntil(resume_time=resume_time))
+
+    return {
+        "message": state.get("message", "wait completed"),
+        "resumed_at": datetime.now(timezone.utc).isoformat(),
+        "resume_payload": str(resume_payload),
+    }
+
+
+builder = StateGraph(State)
+builder.add_node("wait_until", wait_until_node)
+builder.add_edge(START, "wait_until")
+builder.add_edge("wait_until", END)
+
+graph = builder.compile()

samples/wait-until-agent/langgraph.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": ["."],
+  "graphs": {
+    "wait-until-agent": "./graph.py:graph"
+  },
+  "env": ".env"
+}