STG-1784 Fix SSE docs examples

.changeset/sharp-garlics-stare.md

@@ -0,0 +1,6 @@
+---
+"@browserbasehq/stagehand-server-v3": patch
+"@browserbasehq/stagehand-docs": patch
+---
+
+Clarify SSE streaming docs examples

packages/docs/v3/sdk/python.mdx

@@ -81,7 +81,7 @@ uv run python examples/local_example.py
 
 ## Streaming logging example
 
-See [`examples/logging_example.py`](https://github.com/browserbase/stagehand-python/blob/main/examples/logging_example.py) for a remote-only flow that streams `StreamEvent`s with `verbose=2`, `stream_response=True`, and `x_stream_response="true"` so you can watch the SDK’s logs as they arrive.
+See [`examples/logging_example.py`](https://github.com/browserbase/stagehand-python/blob/main/examples/logging_example.py) for a remote-only flow that streams `StreamEvent`s with `verbose=2` and `stream_response=True` so you can watch the SDK’s logs as they arrive.
 
 ```bash
 uv run python examples/logging_example.py
@@ -297,10 +297,7 @@ asyncio.run(main())
 
 We provide support for streaming responses using Server-Sent Events (SSE).
 
-To enable SSE streaming, you must:
-
-1. Ask the server to stream by setting `x_stream_response="true"` (header), and
-2. Tell the client to parse an SSE stream by setting `stream_response=True`.
+To enable SSE streaming, set `stream_response=True`. The SDK sends the streaming request and parses the SSE response as `StreamEvent`s.
 
 ```python
 import asyncio
@@ -315,7 +312,6 @@ async def main() -> None:
             id=session.id,
             input="click the first link on the page",
             stream_response=True,
-            x_stream_response="true",
         )
         async for event in stream:
             # event is a StreamEvent (type: "system" | "log")

packages/server-v3/openapi.v3.yaml

@@ -9,9 +9,11 @@ info:
 
     All endpoints except /sessions/start require an active session ID.
 
-    Responses are streamed using Server-Sent Events (SSE) when the
+    Supported operations stream responses using Server-Sent Events (SSE) when
 
-    `x-stream-response: true` header is provided.
+    `streamResponse` is set to `true` in the request body, or when the
+
+    `x-stream-response: true` header is sent by legacy or no-body clients.
 
 
     This SDK is currently ALPHA software and is not production ready!

packages/server-v3/scripts/gen-openapi.ts

@@ -157,8 +157,9 @@ async function main() {
         description: `Stagehand SDK for AI browser automation [ALPHA]. This API allows clients to
 execute browser automation tasks remotely on the Browserbase cloud.
 All endpoints except /sessions/start require an active session ID.
-Responses are streamed using Server-Sent Events (SSE) when the
-\`x-stream-response: true\` header is provided.
+Supported operations stream responses using Server-Sent Events (SSE) when
+\`streamResponse\` is set to \`true\` in the request body, or when the
+\`x-stream-response: true\` header is sent by legacy or no-body clients.
 
 This SDK is currently ALPHA software and is not production ready!
 Please try it and give us your feedback, stay tuned for upcoming release announcements!`,

stainless.yml

@@ -154,6 +154,24 @@ openapi:
         value:
           x-stainless-any: true
 
+    # Override the generated Python API reference example for the dual-mode
+    # act endpoint so docs show the SSE stream shape instead of iterating over
+    # a non-streaming response object.
+    - command: merge
+      reason: Use streaming Python snippet for sessions.act docs
+      args:
+        target: '$.paths["/v1/sessions/{id}/act"].post'
+        value:
+          x-stainless-snippets:
+            python: |
+              stream = client.sessions.act(
+                  id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
+                  input="Click the login button",
+                  stream_response=True,
+              )
+              for event in stream:
+                  print(event)
+
 # `resources` define the structure and organization for your API, such as how
 # methods and models are grouped together and accessed. See the [configuration
 # guide] for more information.