Skip to content

Conversation

@tkattkat
Copy link
Collaborator

@tkattkat tkattkat commented Oct 8, 2025

why

currently when using stagehand agent through api, it returns early without executing

what changed

we now properly handle the options when none are present

test plan

tested locally, and tested across other cua agents to ensure no breaking changes

@changeset-bot
Copy link

changeset-bot bot commented Oct 8, 2025

🦋 Changeset detected

Latest commit: af230c1

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

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

Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Greptile Overview

Summary

This PR fixes a critical runtime bug in the Stagehand agent API that was causing premature returns when no options parameter was provided. The issue occurred because the code was attempting to access properties on an undefined `options` object, resulting in a TypeError.

The fix adds proper null checking by initializing options as an empty object when it's undefined, and similarly initializing options.options if it doesn't exist. This ensures the agent can execute successfully through the API regardless of whether options are provided, maintaining backward compatibility while enabling proper API functionality.

This change integrates seamlessly with the existing Stagehand architecture, as it simply adds defensive programming around the options parameter handling without modifying any core agent logic or changing the expected behavior when options are properly provided.

Important Files Changed

Changed Files
Filename Score Overview
lib/index.ts 5/5 Added null checks to prevent TypeError when accessing undefined options parameter in agent API

Confidence score: 5/5

  • This PR is extremely safe to merge with minimal risk of causing any production issues
  • Score reflects a simple, well-targeted fix that addresses a specific runtime error without touching complex logic
  • No files require special attention as the change is straightforward defensive programming

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant AgentHandler
    participant StagehandAPI
    participant APIClient

    User->>Stagehand: "agent(options?)"
    Stagehand->>Stagehand: "Create agent instance"
    Stagehand->>User: "Return agent with execute method"
    
    User->>Stagehand: "agent.execute(instructionOrOptions)"
    Stagehand->>Stagehand: "Check if usingAPI is true"
    
    alt API mode and options is undefined
        Stagehand->>Stagehand: "Initialize empty options object"
        Stagehand->>Stagehand: "Initialize empty options.options object"
    end
    
    alt Provider specified
        Stagehand->>Stagehand: "Set API key based on provider"
        alt API key not found
            Stagehand->>User: "Throw error for missing API key"
        end
    end
    
    Stagehand->>StagehandAPI: "agentExecute(options, executeOptions)"
    StagehandAPI->>APIClient: "Send agent execute request"
    APIClient->>StagehandAPI: "Return execution result"
    StagehandAPI->>Stagehand: "Return agent result"
    Stagehand->>User: "Return AgentResult"
Loading

1 file reviewed, no comments

Edit Code Review Agent Settings | Greptile

@tkattkat tkattkat closed this Oct 8, 2025
@tkattkat tkattkat reopened this Oct 8, 2025
Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Greptile Overview

Summary

This PR fixes a critical bug in the Stagehand agent API support that was causing early termination when no options were provided. The issue occurred because the code attempted to access the `options` property on a null/undefined object, resulting in a runtime error that prevented the agent from executing properly.

The fix adds defensive programming checks to ensure both options and options.options are properly initialized as empty objects when they're undefined. This change is located in the agent method within lib/index.ts and maintains backward compatibility while making the API more robust for users who don't need to specify custom options.

This fix aligns with the broader Stagehand architecture where the agent functionality (introduced in version 2.5.0 according to the changelog) supports MCP servers and custom tools. The patch ensures that API users can reliably use the agent feature without being forced to provide empty options objects.

Important Files Changed

Changed Files
Filename Score Overview
lib/index.ts 5/5 Added null safety checks for options parameter in agent method to prevent runtime errors

Confidence score: 5/5

  • This PR is safe to merge with minimal risk as it only adds defensive null checks without changing core functionality
  • Score reflects the simple nature of the fix and thorough testing mentioned across CUA agents
  • No files require special attention as this is a straightforward bug fix with clear scope

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant AgentHandler as "Agent Handler"
    participant APIClient as "API Client"
    participant Browser

    User->>Stagehand: "agent(options?)"
    Stagehand->>Stagehand: "Log: Creating agent instance"
    
    alt options has integrations and not experimental
        Stagehand-->>User: "Throw StagehandError"
    end
    
    alt no options or no provider
        Stagehand->>AgentHandler: "new StagehandAgentHandler()"
    else options has provider
        Stagehand->>AgentHandler: "new CuaAgentHandler()"
    end
    
    User->>Stagehand: "execute(instructionOrOptions)"
    
    alt options has integrations and not experimental
        Stagehand-->>User: "Throw StagehandError"
    end
    
    Stagehand->>Stagehand: "resolveTools(options?.integrations, options?.tools)"
    Stagehand->>AgentHandler: "setTools(tools)"
    
    alt instructionOrOptions is string
        Stagehand->>Stagehand: "Convert to AgentExecuteOptions"
    end
    
    alt no instruction provided
        Stagehand-->>User: "Throw StagehandError"
    end
    
    alt using API
        alt no API client
            Stagehand-->>User: "Throw StagehandNotInitializedError"
        end
        
        note over Stagehand: "Fixed: Now properly handles when options is undefined"
        alt options is undefined
            Stagehand->>Stagehand: "options = {}"
        end
        
        alt options.options is undefined
            Stagehand->>Stagehand: "options.options = {}"
        end
        
        alt options has provider
            Stagehand->>Stagehand: "Set API key based on provider"
            alt no API key found
                Stagehand-->>User: "Throw StagehandError"
            end
        end
        
        Stagehand->>APIClient: "agentExecute(options, executeOptions)"
        APIClient->>Browser: "Execute agent instruction"
        APIClient-->>Stagehand: "AgentResult"
        Stagehand-->>User: "AgentResult"
    else not using API
        Stagehand->>AgentHandler: "execute(executeOptions)"
        AgentHandler->>Browser: "Execute agent instruction"
        AgentHandler-->>Stagehand: "AgentResult"
        Stagehand-->>User: "AgentResult"
    end
Loading

1 file reviewed, no comments

Edit Code Review Agent Settings | Greptile

@tkattkat tkattkat force-pushed the patch-stagehand-agent-api-support branch from eae3d75 to af230c1 Compare October 10, 2025 18:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants