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

[monadoid]

Why

The generated SDK/OpenAPI surface needs to expose the Vertex service-account auth fields that Stagehand can already pass through.

What changed

• Add vertex model config fields to the canonical Stagehand Zod schema: project, location, baseURL, and googleAuthOptions.
• Model googleAuthOptions.credentials as a strict service-account-compatible object requiring client_email and private_key.
• Omit file-path auth, external credential-source auth, and Vertex Express Mode API-key auth from the AI SDK v5-compatible schema.
• Regenerate the v3 OpenAPI spec from the Zod source of truth.
• Add schema tests covering Vertex auth passthrough, minimal credentials, and rejection of unsupported auth shapes.

[changeset-bot]

🦋 Changeset detected

Latest commit: de277b4

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

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v4	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

[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

✅ stagehand-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

⚠️ stagehand-typescript studio · conflict

Your SDK build had at least one warning diagnostic.

⚠️ stagehand-python studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ✅ → lint ✅ → test ✅

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

✅ stagehand-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

⚠️ stagehand-csharp studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ✅ → lint ✅ → test ✅

✅ stagehand-kotlin studio · conflict

Your SDK build had at least one note diagnostic.

✅ stagehand-java studio · conflict

Your SDK build had at least one note diagnostic.

✅ stagehand-go studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@b381980c635b1d7968a2022709fa91921e77556e

⚠️ stagehand-php studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → lint ✅ → test ✅

---

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-20 19:18:37 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

[cubic-dev-ai]

3 issues found across 4 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>