Agents streaming #1315

tkattkat · 2025-11-26T19:08:06Z

why

Simplify the agent streaming API by moving the stream flag into agent configuration. This allows TypeScript to properly infer return types at compile time and provides a cleaner API with a single execute() method.

what changed

Added stream?: boolean to AgentConfig
agent({ stream: true }).execute() → returns AgentStreamResult
agent().execute() → returns AgentResult (unchanged)
Added TypeScript overloads for proper type inference
Added streaming support to V3AgentHandler and caching layer
Extracted shared setup logic into prepareAgentExecution() helper

test plan

tested locally

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

changeset-bot · 2025-11-26T19:08:10Z

🦋 Changeset detected

Latest commit: 276cafb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

greptile-apps

_{5 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

packages/core/lib/v3/handlers/v3AgentHandler.ts

packages/core/lib/v3/tests/agent-streaming.spec.ts

seanmcguire12 · 2025-11-26T22:17:28Z

@greptileai

greptile-apps · 2025-11-26T22:20:12Z

Greptile Overview

Greptile Summary

This PR refactors the agent streaming API by moving the stream flag from execution time to agent configuration, enabling better TypeScript type inference. The implementation adds a new stream() method to V3AgentHandler, TypeScript overloads to V3.agent(), and comprehensive caching support for streamed responses.

Key Changes:

Added stream?: boolean to AgentConfig for compile-time type inference
Refactored V3AgentHandler to extract shared logic into prepareAgent() helper
Added new stream() method in handler with onError and onFinish callbacks
Changed default maxSteps from 10 to 20
Enhanced AgentCache with tryReplayAsStream(), createCachedStreamResult(), and wrapStreamForCaching()
Added TypeScript overloads to properly type streaming vs non-streaming modes
Validates CUA + streaming incompatibility at agent creation time

Issues Found:
The previous review identified two issues that should be addressed (see existing comment threads for details).

Confidence Score: 4/5

This PR is mostly safe to merge with minor issues that should be addressed.
The refactoring is well-structured with good separation of concerns and comprehensive test coverage. However, there are two previously identified issues in error handling that could cause problems in edge cases. The default maxSteps change from 10 to 20 is undocumented but appears intentional.
Pay close attention to packages/core/lib/v3/handlers/v3AgentHandler.ts - review the existing comment threads about error handling in the stream() method.

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/lib/v3/types/public/agent.ts	5/5	Added `AgentStreamResult` type, `AgentContext`, `AgentState` interfaces, and `stream?: boolean` to `AgentConfig`. Type definitions are clean and well-structured.
packages/core/lib/v3/handlers/v3AgentHandler.ts	3/5	Refactored to support streaming via new `stream()` method and extracted shared logic into `prepareAgent()`. Changed default `maxSteps` from 10 to 20. Error handling in `stream()` has issues (see comments).
packages/core/lib/v3/v3.ts	4/5	Added TypeScript overloads for streaming/non-streaming modes, extracted `prepareAgentExecution()` helper. Properly validates CUA + streaming incompatibility. Stream caching integration looks correct.

Sequence Diagram

sequenceDiagram
    participant User
    participant V3
    participant AgentHandler
    participant AgentCache
    participant LLMClient
    
    User->>V3: agent({ stream: true })
    V3->>V3: Validate config (no CUA + stream)
    V3-->>User: Return agent instance
    
    User->>V3: agent.execute(instruction)
    V3->>V3: prepareAgentExecution()
    V3->>AgentCache: tryReplayAsStream()
    
    alt Cache Hit
        AgentCache->>AgentCache: createCachedStreamResult()
        AgentCache-->>V3: Mock AgentStreamResult
        V3-->>User: Cached stream result
    else Cache Miss
        V3->>AgentHandler: stream(instruction)
        AgentHandler->>AgentHandler: prepareAgent()
        AgentHandler->>LLMClient: streamText()
        
        loop Streaming chunks
            LLMClient-->>User: textStream chunks
            LLMClient->>AgentHandler: onStepFinish()
            AgentHandler->>AgentHandler: Update state
        end
        
        LLMClient->>AgentHandler: onFinish()
        AgentHandler->>AgentHandler: consolidateMetricsAndResult()
        AgentHandler-->>V3: AgentStreamResult
        
        V3->>AgentCache: wrapStreamForCaching()
        AgentCache->>AgentCache: beginRecording()
        AgentCache->>AgentCache: Store on completion
        
        V3-->>User: AgentStreamResult
        User->>User: Iterate textStream
        User->>User: await result
    end

greptile-apps

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

cubic-dev-ai

1 issue found across 8 files

Prompt for AI agents (all 1 issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/lib/v3/handlers/v3AgentHandler.ts">

<violation number="1" location="packages/core/lib/v3/handlers/v3AgentHandler.ts:158">
Errors from prepareAgent are now thrown outside the try/catch, so execute() can reject instead of returning a failure AgentResult.</violation>
</file>

Since this is your first cubic review, here's how it works:

cubic automatically reviews your code and comments on bugs and improvements
Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
Ask questions if you need clarification on any suggestion

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

packages/core/lib/v3/handlers/v3AgentHandler.ts

# why Simplify the agent streaming API by moving the `stream` flag into agent configuration. This allows TypeScript to properly infer return types at compile time and provides a cleaner API with a single `execute()` method. # what changed - Added `stream?: boolean` to `AgentConfig` - `agent({ stream: true }).execute()` → returns `AgentStreamResult` - `agent().execute()` → returns `AgentResult` (unchanged) - Added TypeScript overloads for proper type inference - Added streaming support to `V3AgentHandler` and caching layer - Extracted shared setup logic into `prepareAgentExecution()` helper # test plan - tested locally --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> Co-authored-by: Sean McGuire <[email protected]>

@miguelg719

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @browserbasehq/[email protected] ### Patch Changes - [#1388](#1388) [`605ed6b`](605ed6b) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix multiple click event dispatches on CDP and Anthropic CUA handling (double clicks) - [#1400](#1400) [`34e7e5b`](34e7e5b) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - don't write base64 encoded screenshots to disk when caching agent actions - [#1345](#1345) [`943d2d7`](943d2d7) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for aborting / stopping an agent run & continuing an agent run using messages from prior runs - [#1334](#1334) [`0e95cd2`](0e95cd2) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for google vertex provider - [#1410](#1410) [`d4237e4`](d4237e4) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: include extract in stagehand.history() - [#1315](#1315) [`86975e7`](86975e7) Thanks [@tkattkat](https://github.com/tkattkat)! - Add streaming support to agent through stream:true in the agent config - [#1304](#1304) [`d5e119b`](d5e119b) Thanks [@miguelg719](https://github.com/miguelg719)! - Add support for Microsoft's Fara-7B - [#1346](#1346) [`4e051b2`](4e051b2) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: don't attach to targets twice - [#1327](#1327) [`6b5a3c9`](6b5a3c9) Thanks [@miguelg719](https://github.com/miguelg719)! - Informed error parsing from api - [#1335](#1335) [`bb85ad9`](bb85ad9) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add support for page.addInitScript() - [#1331](#1331) [`88d28cc`](88d28cc) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: page.evaluate() now works with scripts injected via context.addInitScript() - [#1316](#1316) [`45bcef0`](45bcef0) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for callbacks in stagehand agent - [#1374](#1374) [`6aa9d45`](6aa9d45) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix key action mapping in Anthropic CUA - [#1330](#1330) [`d382084`](d382084) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: make act, extract, and observe respect user defined timeout param - [#1336](#1336) [`1df08cc`](1df08cc) Thanks [@tkattkat](https://github.com/tkattkat)! - Patch agent on api - [#1358](#1358) [`2b56600`](2b56600) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for 4.5 opus in cua agent ## @browserbasehq/[email protected] ### Patch Changes - [#1364](#1364) [`ca0630e`](ca0630e) Thanks [@tkattkat](https://github.com/tkattkat)! - Update model handling in agent evals cli - Updated dependencies \[[`605ed6b`](605ed6b), [`34e7e5b`](34e7e5b), [`943d2d7`](943d2d7), [`0e95cd2`](0e95cd2), [`d4237e4`](d4237e4), [`86975e7`](86975e7), [`d5e119b`](d5e119b), [`4e051b2`](4e051b2), [`6b5a3c9`](6b5a3c9), [`bb85ad9`](bb85ad9), [`88d28cc`](88d28cc), [`45bcef0`](45bcef0), [`6aa9d45`](6aa9d45), [`d382084`](d382084), [`1df08cc`](1df08cc), [`2b56600`](2b56600)]: - @browserbasehq/[email protected] ## @browserbasehq/[email protected] ### Patch Changes - Updated dependencies \[[`605ed6b`](605ed6b), [`34e7e5b`](34e7e5b), [`943d2d7`](943d2d7), [`0e95cd2`](0e95cd2), [`d4237e4`](d4237e4), [`86975e7`](86975e7), [`d5e119b`](d5e119b), [`4e051b2`](4e051b2), [`6b5a3c9`](6b5a3c9), [`bb85ad9`](bb85ad9), [`88d28cc`](88d28cc), [`45bcef0`](45bcef0), [`6aa9d45`](6aa9d45), [`d382084`](d382084), [`1df08cc`](1df08cc), [`2b56600`](2b56600)]: - @browserbasehq/[email protected] Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

@miguelg719

tkattkat and others added 20 commits November 21, 2025 14:24

agent steaming

861224d

put behind experimental

1fa6093

update typing

a0c8ddf

add streaming example

8d4f29d

lint

e9c63f6

update types

f0bfffe

change default max steps to 20

b21cd59

Merge remote-tracking branch 'origin/main' into agent-steaming

c5c60f1

manually bump version

57ec8c1

Update packages/core/examples/agent_stream_example.ts

e31d2df

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

changeset

ef9a78e

change example to verbose 0

5b5619c

add caching

e782674

format

1b7d126

add wrapStreamForCaching

51877dd

consolidate shared logic

ebd814f

remove version change

0d06078

agents streaming

eeee0dd

update example

7f88860

update changeset

ae01423

greptile-apps bot reviewed Nov 26, 2025

View reviewed changes

packages/core/lib/v3/handlers/v3AgentHandler.ts Outdated Show resolved Hide resolved

packages/core/lib/v3/handlers/v3AgentHandler.ts Show resolved Hide resolved

tkattkat added 5 commits November 26, 2025 11:12

update example

269d7fc

greptile suggestions

1e7af15

format

4ad4efc

throw error when stream is used with cua

05bdf3c

add test for streaming

3744a71

seanmcguire12 reviewed Nov 26, 2025

View reviewed changes

packages/core/lib/v3/tests/agent-streaming.spec.ts Outdated Show resolved Hide resolved

packages/core/lib/v3/tests/agent-streaming.spec.ts Show resolved Hide resolved

packages/core/lib/v3/tests/agent-streaming.spec.ts Outdated Show resolved Hide resolved

tkattkat added 2 commits November 26, 2025 14:01

update test

c14d736

lint

c1e3bae

browserbase deleted a comment from greptile-apps bot Nov 26, 2025

greptile-apps bot reviewed Nov 26, 2025

View reviewed changes

seanmcguire12 approved these changes Nov 26, 2025

View reviewed changes

make anthropic key available in e2e local CI step

62cf2b0

cubic-dev-ai bot reviewed Nov 26, 2025

View reviewed changes

packages/core/lib/v3/handlers/v3AgentHandler.ts Show resolved Hide resolved

tkattkat added 2 commits November 26, 2025 15:32

add try catch on prepare agent

008bceb

format

276cafb

tkattkat merged commit 86975e7 into main Nov 26, 2025
15 of 16 checks passed

This was referenced Nov 26, 2025

Version Packages #1305

Merged

Version Packages CloudEngineHub/stagehand#1

Open

This was referenced Dec 4, 2025

Version Packages thacio/stagehand#1

Open

Version Packages evolv3ai/stagehand#1

Open

Version Packages AlexOcculate/stagehand#1

Open

Version Packages qa-nparekh/stagehand#1

Open

Version Packages afanty2021/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Agents streaming #1315

Agents streaming #1315

Uh oh!

tkattkat commented Nov 26, 2025

Uh oh!

changeset-bot bot commented Nov 26, 2025 •

edited

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seanmcguire12 commented Nov 26, 2025

Uh oh!

greptile-apps bot commented Nov 26, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Agents streaming #1315

Agents streaming #1315

Uh oh!

Conversation

tkattkat commented Nov 26, 2025

why

what changed

test plan

Uh oh!

changeset-bot bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seanmcguire12 commented Nov 26, 2025

Uh oh!

greptile-apps bot commented Nov 26, 2025

Greptile Overview

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot bot commented Nov 26, 2025 •

edited

Loading