[STG-1756] add Vertex auth params to Stagehand spec

[monadoid]

Summary

• add Vertex provider fields to the public Stagehand model config schema
• expose serializable google-auth-library auth options in the generated v3 OpenAPI spec
• add schema coverage to confirm Vertex auth params are preserved for act and agentExecute requests

Validation

• pnpm --dir stagehand --filter @browserbasehq/stagehand run build:esm
• pnpm --dir stagehand --filter @browserbasehq/stagehand run typecheck
• pnpm --dir stagehand --filter @browserbasehq/stagehand-server-v3 run typecheck
• pnpm --dir stagehand exec prettier --check packages/core/lib/v3/types/public/api.ts packages/core/lib/v3/types/public/model.ts packages/core/lib/v3/types/public/agent.ts packages/core/tests/unit/api-variables-schema.test.ts packages/server-v3/scripts/gen-openapi.ts packages/server-v3/openapi.v3.yaml
• pnpm --dir stagehand --filter @browserbasehq/stagehand run test:core -- packages/core/dist/esm/tests/unit/api-variables-schema.test.js
• BROWSERBASE_FLOW_LOGS=1 pnpm --dir stagehand --filter @browserbasehq/stagehand run test:core
• pnpm --dir stagehand --filter @browserbasehq/stagehand-server-v3 run build:esm-tests
• pnpm --dir stagehand --filter @browserbasehq/stagehand-server-v3 run test:unit

---

Summary by cubic

Adds Vertex provider support and auth options to the public Stagehand model config and OpenAPI v3 so clients can configure Vertex (express or service account) end-to-end. Addresses STG-1756; tests confirm params pass through act and agentExecute.

• New Features
  • Added vertex provider in AgentType and ModelConfigObject.provider.
  • Added Vertex fields: project, location, and googleAuthOptions (apiKey, keyFilename/keyFile, credentials, clientOptions, scopes, projectId, universeDomain).
  • Introduced GoogleServiceAccountCredentials and GoogleAuthOptions schemas in @browserbasehq/stagehand; included in OpenAPI v3 (input/output).
  • Expanded GoogleVertexProviderSettings to support baseURL and full googleAuthOptions.

^{Written for commit 05898f3. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 05898f3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

✱ Stainless preview builds for stagehand

This PR will update the stagehand SDKs with the following commit message.

feat: STG-1756 add Vertex auth params to Stagehand spec

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ stagehand-ruby studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ → test ✅

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-csharp studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-kotlin studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-java studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

Add the following URL as a Maven source: 'https://pkg.stainless.com/s/stagehand-java/5ac15b4b09035b60af75111c59fbc9d0512382d9/mvn'

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@789071449adc89c0ce929d016d5a726769252644

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-python studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

pip install https://pkg.stainless.com/s/stagehand-python/9a0bf1f089b296aee0acf353a18d94d1dcd48717/stagehand-3.20.0-py3-none-any.whl

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-php studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → lint ✅ → test ✅

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

✅ stagehand-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

npm install https://pkg.stainless.com/s/stagehand-typescript/985174bbaf04b3f713b506358a3f5e8c5ed09d23/dist.tar.gz

New diagnostics (2 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-15 13:06:11 UTC

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Client as External Client
    participant API as Stagehand API Server
    participant Schema as Zod Schema Validation
    participant Spec as OpenAPI v3 Spec
    participant SDK as Stagehand SDK
    participant Vertex as Vertex AI Provider

    Note over Client,Vertex: Vertex Auth Configuration Flow

    Client->>API: POST /v3/act or /v3/agent/execute
    Note over Client,API: NEW: includes vertex model config
    
    API->>Schema: validate request body
    Note over Schema: NEW: ModelConfigObjectSchema<br/>includes vertex, project, location,<br/>googleAuthOptions fields

    Schema-->>API: validated ModelConfigObject

    alt Request uses Google Vertex
        API->>SDK: pass ModelConfigObject with vertex fields
        
        SDK->>SDK: construct GoogleVertexProviderSettings
        Note over SDK: NEW: baseURL and full<br/>GoogleVertexAuthOptions included
        
        alt Has apiKey
            SDK->>Vertex: authenticate with Vertex express mode
            Note over SDK,Vertex: uses apiKey from googleAuthOptions
        else Has keyFile or credentials
            SDK->>Vertex: authenticate with service account
            Note over SDK,Vertex: uses keyFilename/keyFile<br/>or credentials object
        end

        Vertex-->>SDK: auth token
        SDK->>Vertex: execute model request with auth
        Vertex-->>SDK: model response
        SDK-->>API: result
    end

    API-->>Client: response with Vertex model results

    Note over Spec,Client: OpenAPI Spec Generation

    API->>Spec: generate OpenAPI v3 spec
    Note over Spec: NEW: GoogleServiceAccountCredentials,<br/>GoogleAuthOptions schemas<br/>added to components
    Note over Spec: NEW: "vertex" added to<br/>provider enum in ModelConfigObject<br/>and ModelConfigObjectOutput
    Spec-->>Client: accessible via /openapi/v3.yaml

    Note over Client,Vertex: Schema Coverage Tests

    Client->>API: act request with full Vertex auth
    Note over Client,API: includes provider:"vertex",<br/>project, location,<br/>googleAuthOptions with apiKey<br/>and credentials

    API->>Schema: validate ActRequestSchema
    Schema-->>API: successfully parsed
    API-->>Client: 200 OK with preserved Vertex config

    Client->>API: agentExecute request with Vertex model config
    Note over Client,API: agentConfig.model and<br/>executionModel both use Vertex

    API->>Schema: validate AgentExecuteRequestSchema
    Schema-->>API: successfully parsed  
    API-->>Client: 200 OK with preserved Vertex config for both models

Loading