[STG-2090] Add Azure Entra model auth support

[monadoid]

Why

Support Azure OpenAI Microsoft Entra ID bearer-token auth through the Stagehand model config shape.

What changed

• Adds an explicit Azure model config branch with auth: { type: "azureEntraId", token } and providerOptions.azure.
• Adapts Azure Entra auth to the AI SDK Azure tokenProvider option.
• Bumps @ai-sdk/azure to the v5-compatible release with tokenProvider support.
• Regenerates the server-v3 OpenAPI spec and adds parser/schema/runtime tests.

Validation

• pnpm --filter @browserbasehq/stagehand run build:esm
• pnpm --filter @browserbasehq/stagehand run test:core -- packages/core/dist/esm/tests/unit/llm-provider.test.js packages/core/dist/esm/tests/unit/api-variables-schema.test.js packages/core/dist/esm/tests/unit/public-api/llm-and-agents.test.js
• pnpm --filter @browserbasehq/stagehand-server-v3 run gen:openapi
• pnpm --filter @browserbasehq/stagehand-server-v3 run build:esm-tests
• pnpm --filter @browserbasehq/stagehand-server-v3 run test:server -- packages/server-v3/dist/tests/unit/requestModelConfig.test.js
• pnpm --filter @browserbasehq/stagehand run typecheck
• pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck

---

Summary by cubic

Adds Azure OpenAI Microsoft Entra ID bearer-token auth to Stagehand. Implements STG-2090 and updates types, schemas, and OpenAPI to support the new azure provider.

• New Features

  • Add provider: "azure" with auth: { type: "azureEntraId", token } and providerOptions.azure (resourceName, baseURL, apiVersion, useDeploymentBasedUrls, headers).
  • Map Entra auth to the @ai-sdk/azure tokenProvider; Azure runs without experimental mode and never sends an API key when provider auth is set.
  • Preserve same-provider non-credential options when overriding credentials (inherit baseURL/headers/providerOptions; strip apiKey/auth) across client and server.
  • Prevent API key fallback when provider auth exists: ignore env/header/base-config keys, keep per-request Azure configs via withModelApiKeyFallback, and reject configs that mix apiKey with Entra auth.
  • Expand public types and Zod schemas (add AgentType: "azure"); regenerate OpenAPI with Azure schemas and normalize the generator output to preserve Azure union branches.
  • Add unit tests for schema validation, AI SDK client options, API client defaults, server request model config parsing, and tokenProvider behavior.

• Dependencies

  • Bump @ai-sdk/azure to ^2.0.109.

^{Written for commit 19e7a24. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 19e7a24

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-evals	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-2090] Add Azure Entra model auth support

✅ stagehand-openapi studio · code

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

⚠️ stagehand-php studio · code

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

⚠️ stagehand-java studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ❗

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

✅ stagehand-kotlin studio · code

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

✅ 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@ed24ee36d34f373257bbf5095338251e1fb6b53e

⚠️ 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/2727cc967c63b7e5ecf16e9b503e7ee1b605559a/stagehand-3.21.0-py3-none-any.whl

⚠️ stagehand-csharp studio · code

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

✅ stagehand-ruby studio · code

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

⚠️ stagehand-typescript studio · code

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

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

---

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-06-09 21:05:47 UTC

[cubic-dev-ai]

No issues found across 15 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 API Client
    participant Server as Fastify Server
    participant Header as getRequestModelConfig()
    participant Store as InMemorySessionStore
    participant LLM as LLMProvider
    participant AI as @ai-sdk/azure

    Note over Client,AI: Azure Entra ID model auth flow

    Client->>Server: POST /act (or /agent/execute)
    Server->>Header: Parse model config from body + headers
    Header->>Header: Extract model field & x-model-api-key header

    alt Azure Entra model config provided
        Header->>Header: Read auth.type === "azureEntraId"
        Header-->>Server: RequestModelConfig { model, apiKey: header fallback }
    else Generic model config
        Header->>Header: Fallback to apiKey from body or header
        Header-->>Server: RequestModelConfig { apiKey, model }
    end

    Server->>Store: initSession(options)
    Store->>Store: withModelApiKeyFallback(model, ctx.modelApiKey)

    alt Model has provider auth (e.g., azureEntraId)
        Store->>Store: Return model as-is, no apiKey merge
    else Model has own apiKey
        Store->>Store: Return model as-is, no apiKey merge
    else Model missing apiKey + header key present
        Store->>Store: Return { ...model, apiKey: headerKey }
    end

    Store-->>Server: V3Options with model config

    Server->>LLM: getClient(modelName, clientOptions)
    LLM->>LLM: toAISDKClientOptions(subProvider, options)

    alt subProvider === "azure"
        LLM->>LLM: Extract { auth, providerOptions.azure }
        alt auth.type === "azureEntraId"
            LLM->>LLM: Build tokenProvider: async () => auth.token
            LLM-->>AI: tokenProvider function
        end
        LLM-->>LLM: Spread azure provider options (resourceName, apiVersion, etc.)
    else subProvider === "vertex"
        LLM->>LLM: Build googleAuth from credentials
        LLM-->>AI: Vertex client with auth
    else generic provider
        LLM-->>AI: Pass clientOptions as-is
    end

    LLM-->>Server: AISDKProviderClientOptions
    Server->>AI: Create Azure OpenAI client with tokenProvider
    AI-->>Server: SDK client instance

    Server->>AI: Execute model request (chat completion)
    alt Success
        AI-->>Server: Model response
        Server-->>Client: Action result
    else Auth failure (invalid token)
        AI-->>Server: 401 / auth error
        Server-->>Client: Error response
    end

Loading

_{Re-trigger cubic}

[cubic-dev-ai]

2 issues found across 6 files (changes from recent commits).

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

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