Agents streaming

[tkattkat]

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

[changeset-bot]

🦋 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}

[seanmcguire12]

@greptileai

[greptile-apps]

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

Loading

[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}