-
Notifications
You must be signed in to change notification settings - Fork 1.2k
patch stagehand agent api support #1116
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
🦋 Changeset detectedLatest 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 |
There was a problem hiding this 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"
1 file reviewed, no comments
There was a problem hiding this 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
1 file reviewed, no comments
eae3d75 to
af230c1
Compare
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