From e67e9abff104acf0378844a14b92b39dafe69cd8 Mon Sep 17 00:00:00 2001 From: monadoid <43347795+monadoid@users.noreply.github.com> Date: Mon, 22 Jun 2026 18:11:28 +0200 Subject: [PATCH 1/3] STG-1784 fix SSE docs examples --- packages/docs/v3/sdk/python.mdx | 8 ++------ packages/server-v3/openapi.v3.yaml | 2 +- packages/server-v3/scripts/gen-openapi.ts | 2 +- stainless.yml | 18 ++++++++++++++++++ 4 files changed, 22 insertions(+), 8 deletions(-) diff --git a/packages/docs/v3/sdk/python.mdx b/packages/docs/v3/sdk/python.mdx index 16430acd90..1d46c8f7a5 100644 --- a/packages/docs/v3/sdk/python.mdx +++ b/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") diff --git a/packages/server-v3/openapi.v3.yaml b/packages/server-v3/openapi.v3.yaml index bdbf78aa4b..a5074d71f8 100644 --- a/packages/server-v3/openapi.v3.yaml +++ b/packages/server-v3/openapi.v3.yaml @@ -11,7 +11,7 @@ info: Responses are streamed using Server-Sent Events (SSE) when the - `x-stream-response: true` header is provided. + `streamResponse` request body field is set to `true`. This SDK is currently ALPHA software and is not production ready! diff --git a/packages/server-v3/scripts/gen-openapi.ts b/packages/server-v3/scripts/gen-openapi.ts index 8b6030541d..bfce524422 100644 --- a/packages/server-v3/scripts/gen-openapi.ts +++ b/packages/server-v3/scripts/gen-openapi.ts @@ -158,7 +158,7 @@ async function main() { 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. +\`streamResponse\` request body field is set to \`true\`. 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!`, diff --git a/stainless.yml b/stainless.yml index c8bf766ab3..cc4fa5ef6a 100644 --- a/stainless.yml +++ b/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. From 89189d9ba287d0d36ef7c62754c5786070ddad5d Mon Sep 17 00:00:00 2001 From: monadoid <43347795+monadoid@users.noreply.github.com> Date: Mon, 22 Jun 2026 18:22:03 +0200 Subject: [PATCH 2/3] STG-1784 clarify SSE OpenAPI description --- packages/server-v3/openapi.v3.yaml | 6 ++++-- packages/server-v3/scripts/gen-openapi.ts | 5 +++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/server-v3/openapi.v3.yaml b/packages/server-v3/openapi.v3.yaml index a5074d71f8..775f87492c 100644 --- a/packages/server-v3/openapi.v3.yaml +++ b/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 - `streamResponse` request body field is set to `true`. + `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! diff --git a/packages/server-v3/scripts/gen-openapi.ts b/packages/server-v3/scripts/gen-openapi.ts index bfce524422..054983d052 100644 --- a/packages/server-v3/scripts/gen-openapi.ts +++ b/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 -\`streamResponse\` request body field is set to \`true\`. +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!`, From ddf5930de56d929dc972e9c504416fc10da2baad Mon Sep 17 00:00:00 2001 From: monadoid <43347795+monadoid@users.noreply.github.com> Date: Mon, 22 Jun 2026 18:26:52 +0200 Subject: [PATCH 3/3] STG-1784 add changeset --- .changeset/sharp-garlics-stare.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/sharp-garlics-stare.md diff --git a/.changeset/sharp-garlics-stare.md b/.changeset/sharp-garlics-stare.md new file mode 100644 index 0000000000..6169b05b74 --- /dev/null +++ b/.changeset/sharp-garlics-stare.md @@ -0,0 +1,6 @@ +--- +"@browserbasehq/stagehand-server-v3": patch +"@browserbasehq/stagehand-docs": patch +--- + +Clarify SSE streaming docs examples