[AP-2931] docs(agents): pausing and resuming runs (#12265)

Stainless-Generated-From: f71c45a5c0e01a1a6b50a10361e5940952a9fa63

Author: stlc-bot

scripts/mock

@@ -54,6 +54,7 @@ def create(
         task: str,
         agent_id: str | Omit = omit,
         browser_settings: run_create_params.BrowserSettings | Omit = omit,
+        pause_when: str | Omit = omit,
         result_schema: Dict[str, object] | Omit = omit,
         variables: Dict[str, run_create_params.Variables] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -78,6 +79,12 @@ def create(
           browser_settings: Browser configuration for the agent's session. When omitted, runner defaults
               apply.
 
+          pause_when: Optional description of when the agent should pause and wait for input from your
+              application (e.g. a verification code, an approval, or an answer from another
+              system). When set, the agent is given a `pause` tool; calling it transitions the
+              run to `PAUSED` (the agent's request is the trailing `pause` tool call in the
+              run's messages) until it is resumed via the resume endpoint.
+
           result_schema: An optional [JSON Schema](https://json-schema.org/specification) object. If
               provided, the agent will aim to return a `result` that conforms to this schema
               when the run completes. Overrides the referenced agent's default `resultSchema`
@@ -103,6 +110,7 @@ def create(
                     "task": task,
                     "agent_id": agent_id,
                     "browser_settings": browser_settings,
+                    "pause_when": pause_when,
                     "result_schema": result_schema,
                     "variables": variables,
                 },
@@ -157,7 +165,7 @@ def list(
         end_at: Union[str, datetime] | Omit = omit,
         limit: int | Omit = omit,
         start_at: Union[str, datetime] | Omit = omit,
-        status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"] | Omit = omit,
+        status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT", "PAUSED"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -192,6 +200,8 @@ def list(
               - `FAILED` - agent has failed the run
               - `STOPPED` - run was stopped by the user
               - `TIMED_OUT` - run exceeded maximum time
+              - `PAUSED` - run is paused awaiting input from the caller; the agent's request
+                is the trailing `pause` tool call in the run's messages
 
           extra_headers: Send extra headers
 
@@ -310,6 +320,7 @@ async def create(
         task: str,
         agent_id: str | Omit = omit,
         browser_settings: run_create_params.BrowserSettings | Omit = omit,
+        pause_when: str | Omit = omit,
         result_schema: Dict[str, object] | Omit = omit,
         variables: Dict[str, run_create_params.Variables] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -334,6 +345,12 @@ async def create(
           browser_settings: Browser configuration for the agent's session. When omitted, runner defaults
               apply.
 
+          pause_when: Optional description of when the agent should pause and wait for input from your
+              application (e.g. a verification code, an approval, or an answer from another
+              system). When set, the agent is given a `pause` tool; calling it transitions the
+              run to `PAUSED` (the agent's request is the trailing `pause` tool call in the
+              run's messages) until it is resumed via the resume endpoint.
+
           result_schema: An optional [JSON Schema](https://json-schema.org/specification) object. If
               provided, the agent will aim to return a `result` that conforms to this schema
               when the run completes. Overrides the referenced agent's default `resultSchema`
@@ -359,6 +376,7 @@ async def create(
                     "task": task,
                     "agent_id": agent_id,
                     "browser_settings": browser_settings,
+                    "pause_when": pause_when,
                     "result_schema": result_schema,
                     "variables": variables,
                 },
@@ -413,7 +431,7 @@ async def list(
         end_at: Union[str, datetime] | Omit = omit,
         limit: int | Omit = omit,
         start_at: Union[str, datetime] | Omit = omit,
-        status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"] | Omit = omit,
+        status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT", "PAUSED"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -448,6 +466,8 @@ async def list(
               - `FAILED` - agent has failed the run
               - `STOPPED` - run was stopped by the user
               - `TIMED_OUT` - run exceeded maximum time
+              - `PAUSED` - run is paused awaiting input from the caller; the agent's request
+                is the trailing `pause` tool call in the run's messages
 
           extra_headers: Send extra headers
 

src/browserbase/resources/agents/runs.py

@@ -37,6 +37,15 @@ class RunCreateParams(TypedDict, total=False):
     When omitted, runner defaults apply.
     """
 
+    pause_when: Annotated[str, PropertyInfo(alias="pauseWhen")]
+    """
+    Optional description of when the agent should pause and wait for input from your
+    application (e.g. a verification code, an approval, or an answer from another
+    system). When set, the agent is given a `pause` tool; calling it transitions the
+    run to `PAUSED` (the agent's request is the trailing `pause` tool call in the
+    run's messages) until it is resumed via the resume endpoint.
+    """
+
     result_schema: Annotated[Dict[str, object], PropertyInfo(alias="resultSchema")]
     """An optional [JSON Schema](https://json-schema.org/specification) object.
 

src/browserbase/types/agents/run_create_params.py

@@ -30,7 +30,7 @@ class RunCreateResponse(BaseModel):
     run_id: str = FieldInfo(alias="runId")
     """Unique identifier for the run."""
 
-    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"]
+    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT", "PAUSED"]
     """Current status of the run.
 
     - `PENDING` - agent will run soon
@@ -39,6 +39,8 @@ class RunCreateResponse(BaseModel):
     - `FAILED` - agent has failed the run
     - `STOPPED` - run was stopped by the user
     - `TIMED_OUT` - run exceeded maximum time
+    - `PAUSED` - run is paused awaiting input from the caller; the agent's request
+      is the trailing `pause` tool call in the run's messages
     """
 
     task: str

src/browserbase/types/agents/run_create_response.py

@@ -37,7 +37,7 @@ class RunListParams(TypedDict, total=False):
     RFC 3339, e.g. 2026-01-19T00:00:00Z.
     """
 
-    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"]
+    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT", "PAUSED"]
     """Current status of the run.
 
     - `PENDING` - agent will run soon
@@ -46,4 +46,6 @@ class RunListParams(TypedDict, total=False):
     - `FAILED` - agent has failed the run
     - `STOPPED` - run was stopped by the user
     - `TIMED_OUT` - run exceeded maximum time
+    - `PAUSED` - run is paused awaiting input from the caller; the agent's request
+      is the trailing `pause` tool call in the run's messages
     """

src/browserbase/types/agents/run_list_params.py

@@ -30,7 +30,7 @@ class Data(BaseModel):
     run_id: str = FieldInfo(alias="runId")
     """Unique identifier for the run."""
 
-    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"]
+    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT", "PAUSED"]
     """Current status of the run.
 
     - `PENDING` - agent will run soon
@@ -39,6 +39,8 @@ class Data(BaseModel):
     - `FAILED` - agent has failed the run
     - `STOPPED` - run was stopped by the user
     - `TIMED_OUT` - run exceeded maximum time
+    - `PAUSED` - run is paused awaiting input from the caller; the agent's request
+      is the trailing `pause` tool call in the run's messages
     """
 
     task: str

src/browserbase/types/agents/run_list_response.py

@@ -30,7 +30,7 @@ class RunRetrieveResponse(BaseModel):
     run_id: str = FieldInfo(alias="runId")
     """Unique identifier for the run."""
 
-    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"]
+    status: Literal["PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT", "PAUSED"]
     """Current status of the run.
 
     - `PENDING` - agent will run soon
@@ -39,6 +39,8 @@ class RunRetrieveResponse(BaseModel):
     - `FAILED` - agent has failed the run
     - `STOPPED` - run was stopped by the user
     - `TIMED_OUT` - run exceeded maximum time
+    - `PAUSED` - run is paused awaiting input from the caller; the agent's request
+      is the trailing `pause` tool call in the run's messages
     """
 
     task: str

src/browserbase/types/agents/run_retrieve_response.py

@@ -53,6 +53,7 @@ def test_method_create_with_all_params(self, client: Browserbase) -> None:
                 ],
                 "verified": True,
             },
+            pause_when="x",
             result_schema={"foo": "bar"},
             variables={
                 "foo": {
@@ -246,6 +247,7 @@ async def test_method_create_with_all_params(self, async_client: AsyncBrowserbas
                 ],
                 "verified": True,
             },
+            pause_when="x",
             result_schema={"foo": "bar"},
             variables={
                 "foo": {