patch agent on api

[tkattkat]

why

if no options are provided, we need to provide an empty object

what changed

when options is empty, we fallback to empty object

test plan

tested locally
tested on api

---

Summary by cubic

Default options to {} for agentExecute calls in V3 to prevent errors when no options are provided. This makes API agent execution more resilient.

Why:

• agentExecute expects an object; undefined options caused failures.

What:

• Use options ?? {} when calling apiClient.agentExecute in V3.

Test Plan:

• Call agent without options; verify it executes without error.
• Call agent with options; verify values are passed unchanged.
• Smoke test on API with an active page; confirm normal behavior.

^{Written for commit 8980e9f. Summary will update automatically on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 8980e9f

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

[cubic-dev-ai]

No issues found across 1 file

[greptile-apps]

Greptile Overview

Greptile Summary

This PR fixes a defensive programming issue in the V3 agent execution path. When the agent method is called without options (a common and valid use case), the options parameter becomes undefined. The apiClient.agentExecute method expects an object, so passing undefined causes runtime errors. The fix adds a nullish coalescing operator (?? {}) to ensure an empty object is passed when options are undefined, making the API agent execution path consistent with the rest of the codebase that already handles optional options gracefully.

Important Files Changed

Filename	Score	Overview
packages/core/lib/v3/v3.ts	5/5	Added nullish coalescing operator to default options to empty object in apiClient.agentExecute call

Confidence score: 5/5

• This PR is extremely safe to merge with minimal risk of causing any issues
• Score reflects a simple, well-tested defensive programming fix that prevents runtime errors without changing any core functionality
• No files require special attention as this is a single-line defensive fix that maintains API consistency

Sequence Diagram

sequenceDiagram
    participant User
    participant V3
    participant AgentCache
    participant StagehandAPIClient
    participant V3AgentHandler
    participant V3CuaAgentHandler

    User->>V3: "agent(options).execute(instructionOrOptions)"
    
    alt "CUA mode enabled (options?.cua)"
        V3->>V3: "validateCUARequirements()"
        V3->>AgentCache: "buildConfigSignature(options)"
        V3->>V3: "normalizeToV3Page(resolvedOptions.page)"
        V3->>AgentCache: "shouldAttemptCache(instruction)"
        
        alt "cache enabled"
            V3->>AgentCache: "prepareContext()"
            AgentCache->>AgentCache: "tryReplay(cacheContext)"
            alt "cache hit"
                AgentCache-->>V3: "cached result"
                V3-->>User: "AgentResult"
            end
        end
        
        alt "API client enabled and not experimental"
            V3->>StagehandAPIClient: "agentExecute(options ?? {}, resolvedOptions, frameId)"
            StagehandAPIClient-->>V3: "AgentResult"
        else "local execution"
            V3->>V3CuaAgentHandler: "new V3CuaAgentHandler()"
            V3->>V3CuaAgentHandler: "execute(instructionOrOptions)"
            V3CuaAgentHandler-->>V3: "AgentResult"
        end
        
        alt "recording enabled"
            V3->>AgentCache: "store(cacheContext, agentSteps, result)"
        end
        
        V3-->>User: "AgentResult"
    
    else "Standard mode with streaming (options?.stream)"
        V3->>V3: "prepareAgentExecution()"
        V3->>V3AgentHandler: "new V3AgentHandler()"
        
        alt "cache enabled"
            V3->>AgentCache: "tryReplayAsStream(cacheContext)"
            alt "cache hit"
                AgentCache-->>V3: "stream result"
                V3-->>User: "AgentStreamResult"
            end
        end
        
        V3->>V3AgentHandler: "stream(instructionOrOptions)"
        V3AgentHandler-->>V3: "AgentStreamResult"
        
        alt "caching enabled"
            V3->>AgentCache: "wrapStreamForCaching()"
        end
        
        V3-->>User: "AgentStreamResult"
    
    else "Standard mode without streaming"
        V3->>V3: "prepareAgentExecution()"
        V3->>V3AgentHandler: "new V3AgentHandler()"
        
        alt "cache enabled"
            V3->>AgentCache: "tryReplay(cacheContext)"
            alt "cache hit"
                AgentCache-->>V3: "cached result"
                V3-->>User: "AgentResult"
            end
        end
        
        alt "API client enabled and not experimental"
            V3->>StagehandAPIClient: "agentExecute(options ?? {}, resolvedOptions, frameId)"
            StagehandAPIClient-->>V3: "AgentResult"
        else "local execution"
            V3->>V3AgentHandler: "execute(instructionOrOptions)"
            V3AgentHandler-->>V3: "AgentResult"
        end
        
        alt "recording enabled"
            V3->>AgentCache: "store(cacheContext, agentSteps, result)"
        end
        
        V3-->>User: "AgentResult"
    end

Loading

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}