remove experimental requirement on agent variables (#2079)

[miguelg719]

why

experimental: true is no longer required for agent variable support

what changed

• Removed the experimental gate on agent variables: dropped the variables check in validateExperimentalFeatures.ts and the @experimental JSDoc on AgentExecuteOptionsBase.variables.
• Added a variables field to the AgentExecuteOptions API schema (packages/core/lib/v3/types/public/api.ts) and reflected it in the generated openapi.v3.yaml (both request and output components).
• Updated docs to drop experimental: true from the Variables Note and Basic Usage example (kept the "Non-CUA agents only" caveat).
• Added unit tests covering the new surface
• Added integration coverage on the login eval site: new variables describe blocks in act.test.ts and agentExecute.test.ts (simple and rich { value, description } forms, verified via CDP), and updated observe.test.ts's existing variables tests to use the same scenario.

test plan

• pnpm --filter @browserbasehq/stagehand-server-v3 typecheck — passes.
• pnpm exec prettier --check on the three test files — passes.
• pnpm exec eslint on the three test files — passes.

---

Summary by cubic

Enable variables in v3 agentExecute without requiring experimental mode, with end-to-end substitution. API, types, and docs support simple and rich variables; variables remain unsupported in CUA mode.

• New Features
  • Added variables to AgentExecuteOptionsSchema and server OpenAPI (Variables).
  • Removed experimental validation for variables; CUA-mode rejection remains.
  • Updated JSDoc and docs to drop the experimental requirement.
  • Added tests: unit (validation, client serialization, schema) and integration for substitution in act, observe, and agentExecute.

^{Written for commit 4467fe1. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4467fe1

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

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

feat: remove experimental requirement on agent variables (#2079)

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

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

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

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

✅ stagehand-kotlin studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ (prev: 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 ✅ (prev: build ⏭️) → lint ✅ → test ✅

✅ stagehand-typescript studio · code · diff

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

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

✅ stagehand-python studio · code · diff

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

pip install https://pkg.stainless.com/s/stagehand-python/e61e847e1de7691f3f4997f3ab16abd50154121d/stagehand-3.19.5-py3-none-any.whl

✅ stagehand-java studio · code · diff

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

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

⚠️ stagehand-csharp studio · code · diff

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ (prev: build ⏭️) → lint ❗ (prev: lint ⏭️) → test ✅

New diagnostics (1 note)

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

---

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-05 00:06:34 UTC

[cubic-dev-ai]

No issues found across 8 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 Client (SDK User)
    participant API as StagehandAPI (agentExecute)
    participant Validate as validateExperimentalFeatures
    participant Schema as AgentExecuteOptionsSchema
    participant Spec as OpenAPI Spec (server-v3)
    participant Server as Backend API Service

    Note over Client,Server: Agent Execute with Variables Flow (v3)

    Client->>API: agentExecute({ instruction, variables })
    Note over Client,API: variables now accepted without experimental:true
    
    API->>Validate: validateExperimentalFeatures(options)
    alt mode is "cua" AND variables provided
        Validate-->>API: throw StagehandInvalidArgumentError
        API-->>Client: Error: variables not supported in CUA mode
    else all other modes (dom, etc.)
        Validate-->>API: pass (no experimental check for variables)
    end

    API->>Schema: parse/validate executeOptions
    Note over Schema: variables field defined in AgentExecuteOptionsSchema
    Schema-->>API: validated options with variables

    API->>Server: POST /agentExecute<br/>(agentConfig, executeOptions, variables)
    Note over Server: Variables sent via API request body
    
    alt simple variables
        Server-->>API: { variables: { username: "john@example.com" } }
    else rich variables (with description)
        Server-->>API: { variables: { password: { value: "secret", description: "..." } } }
    end

    API-->>Client: success response

Loading