docs: add more examples

Author: stainless-app[bot]

README.md

@@ -190,6 +190,98 @@ CompletableFuture<SessionActResponse> response = client.sessions().act(params);
 
 The asynchronous client supports the same options as the synchronous one, except most methods return `CompletableFuture`s.
 
+## Streaming
+
+The SDK defines methods that return response "chunk" streams, where each chunk can be individually processed as soon as it arrives instead of waiting on the full response. Streaming methods generally correspond to [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) or [JSONL](https://jsonlines.org) responses.
+
+Some of these methods may have streaming and non-streaming variants, but a streaming method will always have a `Streaming` suffix in its name, even if it doesn't have a non-streaming variant.
+
+These streaming methods return [`StreamResponse`](stagehand-java-core/src/main/kotlin/com/browserbase/api/core/http/StreamResponse.kt) for synchronous clients:
+
+```java
+import com.browserbase.api.core.http.StreamResponse;
+import com.browserbase.api.models.sessions.StreamEvent;
+
+try (StreamResponse<StreamEvent> streamResponse = client.sessions().actStreaming(params)) {
+    streamResponse.stream().forEach(chunk -> {
+        System.out.println(chunk);
+    });
+    System.out.println("No more chunks!");
+}
+```
+
+Or [`AsyncStreamResponse`](stagehand-java-core/src/main/kotlin/com/browserbase/api/core/http/AsyncStreamResponse.kt) for asynchronous clients:
+
+```java
+import com.browserbase.api.core.http.AsyncStreamResponse;
+import com.browserbase.api.models.sessions.StreamEvent;
+import java.util.Optional;
+
+client.async().sessions().actStreaming(params).subscribe(chunk -> {
+    System.out.println(chunk);
+});
+
+// If you need to handle errors or completion of the stream
+client.async().sessions().actStreaming(params).subscribe(new AsyncStreamResponse.Handler<>() {
+    @Override
+    public void onNext(StreamEvent chunk) {
+        System.out.println(chunk);
+    }
+
+    @Override
+    public void onComplete(Optional<Throwable> error) {
+        if (error.isPresent()) {
+            System.out.println("Something went wrong!");
+            throw new RuntimeException(error.get());
+        } else {
+            System.out.println("No more chunks!");
+        }
+    }
+});
+
+// Or use futures
+client.async().sessions().actStreaming(params)
+    .subscribe(chunk -> {
+        System.out.println(chunk);
+    })
+    .onCompleteFuture();
+    .whenComplete((unused, error) -> {
+        if (error != null) {
+            System.out.println("Something went wrong!");
+            throw new RuntimeException(error);
+        } else {
+            System.out.println("No more chunks!");
+        }
+    });
+```
+
+Async streaming uses a dedicated per-client cached thread pool [`Executor`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executor.html) to stream without blocking the current thread. This default is suitable for most purposes.
+
+To use a different `Executor`, configure the subscription using the `executor` parameter:
+
+```java
+import java.util.concurrent.Executor;
+import java.util.concurrent.Executors;
+
+Executor executor = Executors.newFixedThreadPool(4);
+client.async().sessions().actStreaming(params).subscribe(
+    chunk -> System.out.println(chunk), executor
+);
+```
+
+Or configure the client globally using the `streamHandlerExecutor` method:
+
+```java
+import com.browserbase.api.client.StagehandClient;
+import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
+import java.util.concurrent.Executors;
+
+StagehandClient client = StagehandOkHttpClient.builder()
+    .fromEnv()
+    .streamHandlerExecutor(Executors.newFixedThreadPool(4))
+    .build();
+```
+
 ## Raw responses
 
 The SDK defines methods that deserialize responses into instances of Java classes. However, these methods don't provide access to the response headers, status code, or the raw response body.