Agent streaming

[tkattkat]

why

We wanted to add streaming support to the non-CUA agent in V3

what changed

1. Added stream method to V3AgentHandler:

   • Wraps AI SDK's streamText instead of generateText
   • Returns AgentStreamResult, which extends StreamTextResult with an added result: Promise<AgentResult> property
   • Uses onFinish callback to resolve the result promise with metrics and final state

2. Consolidated duplicate logic:

   • Created prepareAgent() helper to build context (system prompt, tools, wrapped model) for both execute and stream
   • Created createStepHandler() to generate the onStepFinish callback used by both methods
   • Created consolidateMetricsAndResult() to handle metrics updates and AgentResult construction
   • Created handleStop() helper to check for "close" tool calls before falling back to step count limit

3. Moved types to public agent types:

   • Exported AgentContext and AgentState interfaces from packages/core/lib/v3/types/public/agent.ts
   • Added AgentStreamResult type that combines StreamTextResult<ToolSet, never> with result: Promise<AgentResult>

4. Updated V3.agent() return type:

   • Added optional stream method alongside execute for non-CUA agents
   • CUA agents only expose execute (no streaming support)

notes : context handling will likely be moved to prepareStep callback in the very near future, currently we have to maintain a state of the messages which is not ideal. prepareStep should eliminate the need for this

[changeset-bot]

🦋 Changeset detected

Latest commit: 0d06078

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]

Greptile Overview

Greptile Summary

Added streaming support to the V3 non-CUA agent by implementing a new stream() method that wraps AI SDK's streamText. The implementation consolidated duplicate logic from the existing execute() method into reusable helpers (prepareAgent, createStepHandler, consolidateMetricsAndResult, handleStop).

Key changes:

• New stream() method in V3AgentHandler returns AgentStreamResult (extends StreamTextResult with a result Promise)
• Refactored shared logic into helper methods to support both execute() and stream()
• Changed default maxSteps from 10 to 20
• Added new types: AgentContext, AgentState, AgentStreamResult
• Streaming is gated behind the experimental flag
• Example file demonstrates usage with textStream iteration

The refactoring improves code maintainability by eliminating duplication between streaming and non-streaming paths.

Confidence Score: 5/5

• Safe to merge with minimal risk - well-structured refactoring with proper error handling
• Clean implementation with good separation of concerns, proper Promise handling in streaming, and consistent error handling between execute and stream methods. The refactoring improves maintainability without changing existing behavior.
• packages/core/examples/agent_stream_example.ts has a typo that should be fixed

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/examples/agent_stream_example.ts	4/5	Added example demonstrating agent streaming API usage with text streaming; contains typo in instruction ("seach" instead of "search")
packages/core/lib/v3/handlers/v3AgentHandler.ts	5/5	Refactored to add streaming support by extracting shared logic into helper methods (prepareAgent, createStepHandler, consolidateMetricsAndResult, handleStop); changed default maxSteps from 10 to 20
packages/core/lib/v3/types/public/agent.ts	5/5	Added types for streaming support: AgentContext, AgentState, and AgentStreamResult to support the new streaming API
packages/core/lib/v3/v3.ts	5/5	Added optional stream method to non-CUA agent instances, gated behind experimental flag check

Sequence Diagram

sequenceDiagram
    participant User
    participant V3
    participant V3AgentHandler
    participant LLMClient
    participant AI_SDK

    User->>V3: agent.stream(instruction)
    V3->>V3: check experimental flag
    V3->>V3AgentHandler: new V3AgentHandler(...)
    V3->>V3AgentHandler: stream(instruction)
    
    V3AgentHandler->>V3AgentHandler: prepareAgent(instruction)
    V3AgentHandler->>V3AgentHandler: create AgentState
    V3AgentHandler->>V3AgentHandler: create Promise for result
    
    V3AgentHandler->>LLMClient: streamText(config)
    LLMClient->>AI_SDK: streamText with tools
    AI_SDK-->>V3AgentHandler: StreamTextResult
    
    V3AgentHandler->>V3AgentHandler: attach result Promise
    V3AgentHandler-->>V3: AgentStreamResult
    V3-->>User: AgentStreamResult
    
    Note over User,AI_SDK: Streaming phase begins
    
    loop For each text delta
        AI_SDK-->>User: textStream delta
    end
    
    loop For each step
        AI_SDK->>V3AgentHandler: onStepFinish(event)
        V3AgentHandler->>V3AgentHandler: createStepHandler processes
        V3AgentHandler->>V3AgentHandler: update AgentState
        V3AgentHandler->>V3AgentHandler: check for "close" tool
        V3AgentHandler->>V3AgentHandler: map tool results to actions
    end
    
    AI_SDK->>V3AgentHandler: onFinish(event)
    V3AgentHandler->>V3AgentHandler: consolidateMetricsAndResult()
    V3AgentHandler->>V3: updateMetrics()
    V3AgentHandler->>V3AgentHandler: resolve result Promise
    
    User->>User: await result.result
    V3AgentHandler-->>User: AgentResult

Loading

[greptile-apps]

_{4 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}