[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]

⚠️ No Changeset found

Latest commit: a41c76d

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-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

✅ stagehand-php studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → lint ⏭️ → test ⏭️

✅ stagehand-typescript studio · conflict

Your SDK build resulted in a merge conflict between your custom code and the newly generated changes, but this did not represent a regression.

✅ stagehand-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ⏭️ → lint ⏭️ → test ⏭️

go get github.com/stainless-sdks/stagehand-go@2a90bd99323ba29d24d179627286457c6e05b934

✅ stagehand-python studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ⏭️

✅ stagehand-ruby studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ⏭️ → lint ⏭️ → test ⏭️

✅ 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 ⏭️ → lint ⏭️ → test ⏭️

New diagnostics (1 note)

💡 Name/Renamed: 37 names were renamed due to language constraints, so fallback names will be used instead.

✅ stagehand-kotlin studio · conflict

Your SDK build resulted in a merge conflict between your custom code and the newly generated changes, but this did not represent a regression.

✅ stagehand-java studio · conflict

Your SDK build resulted in a merge conflict between your custom code and the newly generated changes, but this did not represent a regression.

---

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-19 17:35:06 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>