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

packages/core/lib/v3/types/public/agent.ts

@@ -445,7 +445,8 @@ export type AgentType =
   | "anthropic"
   | "google"
   | "microsoft"
-  | "bedrock";
+  | "bedrock"
+  | "vertex";
 
 export const AVAILABLE_CUA_MODELS = [
   "openai/gpt-5.4",

packages/core/lib/v3/types/public/api.ts

@@ -56,10 +56,61 @@ export const LocalBrowserLaunchOptionsSchema = z
   .meta({ id: "LocalBrowserLaunchOptions" });
 
 /** Detailed model configuration object */
+export const GoogleServiceAccountCredentialsSchema = z
+  .object({
+    type: z.string().optional(),
+    project_id: z.string().optional(),
+    private_key_id: z.string().optional(),
+    private_key: z.string().optional(),
+    client_email: z.string().optional(),
+    client_id: z.string().optional(),
+    auth_uri: z.string().optional(),
+    token_uri: z.string().optional(),
+    auth_provider_x509_cert_url: z.string().optional(),
+    client_x509_cert_url: z.string().optional(),
+    universe_domain: z.string().optional(),
+  })
+  .catchall(z.unknown())
+  .meta({ id: "GoogleServiceAccountCredentials" });
+
+export const GoogleAuthOptionsSchema = z
+  .object({
+    apiKey: z.string().optional().meta({
+      description:
+        "API key used by google-auth-library for Vertex express mode",
+    }),
+    keyFilename: z.string().optional().meta({
+      description: "Path to a Google Cloud service account key file",
+    }),
+    keyFile: z.string().optional().meta({
+      description: "Path to a Google Cloud service account key file",
+    }),
+    credentials: GoogleServiceAccountCredentialsSchema.optional().meta({
+      description: "Google Cloud service account credentials",
+    }),
+    clientOptions: z.record(z.string(), z.unknown()).optional().meta({
+      description:
+        "Additional serializable options passed to the Google auth client",
+    }),
+    scopes: z
+      .union([z.string(), z.array(z.string())])
+      .optional()
+      .meta({
+        description: "Google auth scopes for the desired API request",
+      }),
+    projectId: z.string().optional().meta({
+      description: "Google Cloud project ID used by google-auth-library",
+    }),
+    universeDomain: z.string().optional().meta({
+      description: "Google Cloud universe domain",
+    }),
+  })
+  .meta({ id: "GoogleAuthOptions" });
+
 export const ModelConfigObjectSchema = z
   .object({
     provider: z
-      .enum(["openai", "anthropic", "google", "microsoft", "bedrock"])
+      .enum(["openai", "anthropic", "google", "microsoft", "bedrock", "vertex"])
       .optional()
       .meta({
         description:
@@ -83,6 +134,18 @@ export const ModelConfigObjectSchema = z
       description:
         "Custom headers sent with every request to the model provider",
     }),
+    project: z.string().optional().meta({
+      description: "Google Cloud project ID for Vertex AI models",
+      example: "my-gcp-project",
+    }),
+    location: z.string().optional().meta({
+      description: "Google Cloud location for Vertex AI models",
+      example: "us-central1",
+    }),
+    googleAuthOptions: GoogleAuthOptionsSchema.optional().meta({
+      description:
+        "google-auth-library options used to authenticate Vertex AI models",
+    }),
   })
   .meta({ id: "ModelConfigObject" });
 

packages/core/lib/v3/types/public/model.ts

@@ -18,6 +18,7 @@ export type AnthropicClientOptions = Pick<
 >;
 
 export interface GoogleServiceAccountCredentials {
+  [key: string]: unknown;
   type?: string;
   project_id?: string;
   private_key_id?: string;
@@ -31,13 +32,22 @@ export interface GoogleServiceAccountCredentials {
   universe_domain?: string;
 }
 
+export interface GoogleVertexAuthOptions {
+  apiKey?: string;
+  keyFilename?: string;
+  keyFile?: string;
+  credentials?: GoogleServiceAccountCredentials;
+  clientOptions?: Record<string, unknown>;
+  scopes?: string | string[];
+  projectId?: string;
+  universeDomain?: string;
+}
+
 export type GoogleVertexProviderSettings = Pick<
   GoogleVertexProviderSettingsBase,
-  "project" | "location" | "headers"
+  "project" | "location" | "headers" | "baseURL"
 > & {
-  googleAuthOptions?: {
-    credentials?: GoogleServiceAccountCredentials;
-  };
+  googleAuthOptions?: GoogleVertexAuthOptions;
 };
 
 export type AnthropicJsonSchemaObject = {

packages/core/tests/unit/api-variables-schema.test.ts

@@ -62,3 +62,59 @@ describe("API variable schemas", () => {
     });
   });
 });
+
+describe("API model config schemas", () => {
+  const vertexModel = {
+    provider: "vertex",
+    modelName: "vertex/gemini-2.5-flash",
+    project: "test-gcp-project",
+    location: "us-central1",
+    googleAuthOptions: {
+      apiKey: "vertex-express-key",
+      credentials: {
+        audience:
+          "//iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/pool/providers/provider",
+        client_email: "vertex@example.iam.gserviceaccount.com",
+        private_key:
+          "-----BEGIN PRIVATE KEY-----\\ntest\\n-----END PRIVATE KEY-----",
+      },
+      clientOptions: {
+        eagerRefreshThresholdMillis: 300000,
+        forceRefreshOnFailure: true,
+      },
+      scopes: ["https://www.googleapis.com/auth/cloud-platform"],
+      projectId: "test-gcp-project",
+      universeDomain: "googleapis.com",
+    },
+  };
+
+  it("preserves Vertex auth params for act requests", () => {
+    const result = Api.ActRequestSchema.safeParse({
+      input: "click the search button",
+      options: {
+        model: vertexModel,
+      },
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) throw result.error;
+    expect(result.data.options?.model).toEqual(vertexModel);
+  });
+
+  it("preserves Vertex auth params for agent model configs", () => {
+    const result = Api.AgentExecuteRequestSchema.safeParse({
+      agentConfig: {
+        model: vertexModel,
+        executionModel: vertexModel,
+      },
+      executeOptions: {
+        instruction: "find the search box",
+      },
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) throw result.error;
+    expect(result.data.agentConfig.model).toEqual(vertexModel);
+    expect(result.data.agentConfig.executionModel).toEqual(vertexModel);
+  });
+});

packages/server-v3/openapi.v3.yaml

@@ -168,6 +168,66 @@ components:
         acceptDownloads:
           type: boolean
       additionalProperties: false
+    GoogleServiceAccountCredentials:
+      type: object
+      properties:
+        type:
+          type: string
+        project_id:
+          type: string
+        private_key_id:
+          type: string
+        private_key:
+          type: string
+        client_email:
+          type: string
+        client_id:
+          type: string
+        auth_uri:
+          type: string
+        token_uri:
+          type: string
+        auth_provider_x509_cert_url:
+          type: string
+        client_x509_cert_url:
+          type: string
+        universe_domain:
+          type: string
+      additionalProperties: {}
+    GoogleAuthOptions:
+      type: object
+      properties:
+        apiKey:
+          description: API key used by google-auth-library for Vertex express mode
+          type: string
+        keyFilename:
+          description: Path to a Google Cloud service account key file
+          type: string
+        keyFile:
+          description: Path to a Google Cloud service account key file
+          type: string
+        credentials:
+          description: Google Cloud service account credentials
+          $ref: "#/components/schemas/GoogleServiceAccountCredentials"
+        clientOptions:
+          description: Additional serializable options passed to the Google auth client
+          type: object
+          propertyNames:
+            type: string
+          additionalProperties: {}
+        scopes:
+          description: Google auth scopes for the desired API request
+          anyOf:
+            - type: string
+            - type: array
+              items:
+                type: string
+        projectId:
+          description: Google Cloud project ID used by google-auth-library
+          type: string
+        universeDomain:
+          description: Google Cloud universe domain
+          type: string
     ModelConfigObject:
       type: object
       properties:
@@ -181,6 +241,7 @@ components:
             - google
             - microsoft
             - bedrock
+            - vertex
         modelName:
           description: Model name string with provider prefix (e.g., 'openai/gpt-5-nano')
           example: openai/gpt-5.4-mini
@@ -201,6 +262,17 @@ components:
             type: string
           additionalProperties:
             type: string
+        project:
+          description: Google Cloud project ID for Vertex AI models
+          example: my-gcp-project
+          type: string
+        location:
+          description: Google Cloud location for Vertex AI models
+          example: us-central1
+          type: string
+        googleAuthOptions:
+          description: google-auth-library options used to authenticate Vertex AI models
+          $ref: "#/components/schemas/GoogleAuthOptions"
       required:
         - modelName
     ModelConfig:
@@ -1238,6 +1310,41 @@ components:
         acceptDownloads:
           type: boolean
       additionalProperties: false
+    GoogleAuthOptionsOutput:
+      type: object
+      properties:
+        apiKey:
+          description: API key used by google-auth-library for Vertex express mode
+          type: string
+        keyFilename:
+          description: Path to a Google Cloud service account key file
+          type: string
+        keyFile:
+          description: Path to a Google Cloud service account key file
+          type: string
+        credentials:
+          description: Google Cloud service account credentials
+          $ref: "#/components/schemas/GoogleServiceAccountCredentials"
+        clientOptions:
+          description: Additional serializable options passed to the Google auth client
+          type: object
+          propertyNames:
+            type: string
+          additionalProperties: {}
+        scopes:
+          description: Google auth scopes for the desired API request
+          anyOf:
+            - type: string
+            - type: array
+              items:
+                type: string
+        projectId:
+          description: Google Cloud project ID used by google-auth-library
+          type: string
+        universeDomain:
+          description: Google Cloud universe domain
+          type: string
+      additionalProperties: false
     ModelConfigObjectOutput:
       type: object
       properties:
@@ -1251,6 +1358,7 @@ components:
             - google
             - microsoft
             - bedrock
+            - vertex
         modelName:
           description: Model name string with provider prefix (e.g., 'openai/gpt-5-nano')
           example: openai/gpt-5.4-mini
@@ -1271,6 +1379,17 @@ components:
             type: string
           additionalProperties:
             type: string
+        project:
+          description: Google Cloud project ID for Vertex AI models
+          example: my-gcp-project
+          type: string
+        location:
+          description: Google Cloud location for Vertex AI models
+          example: us-central1
+          type: string
+        googleAuthOptions:
+          description: google-auth-library options used to authenticate Vertex AI models
+          $ref: "#/components/schemas/GoogleAuthOptionsOutput"
       required:
         - modelName
       additionalProperties: false

packages/server-v3/scripts/gen-openapi.ts

@@ -42,6 +42,9 @@ async function main() {
       BrowserbaseRegion: Api.BrowserbaseRegionSchema,
       // Shared components
       LocalBrowserLaunchOptions: Api.LocalBrowserLaunchOptionsSchema,
+      GoogleServiceAccountCredentials:
+        Api.GoogleServiceAccountCredentialsSchema,
+      GoogleAuthOptions: Api.GoogleAuthOptionsSchema,
       ModelConfigObject: Api.ModelConfigObjectSchema,
       ModelConfig: Api.ModelConfigSchema,
       Action: Api.ActionSchema,