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 experimental mode, with end-to-end substitution across act, observe, and agent tools. Tightened fillFormVision so secrets are only substituted at type-time and never leak via logs, replays, or tool outputs.

• New Features

  • Added variables to AgentExecuteOptionsSchema and server OpenAPI (Variables).
  • Removed experimental gating 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 (simple and rich forms).

• Bug Fixes

  • Updated fillFormVision to substitute variables only when typing and keep placeholders in action logs, replays, and returned arguments.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: a6e9d62

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)

✅ stagehand-ruby studio · conflict

Your SDK build had at least one note diagnostic.

⚠️ 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/f8e6f2bfb72d3f95c0cdc08ad7f7417a53aceff2/dist.tar.gz

⚠️ stagehand-csharp studio · code

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

⚠️ stagehand-python studio · conflict

Your SDK build had at least one warning diagnostic.

⚠️ stagehand-php studio · conflict

Your SDK build had at least one warning diagnostic.

✅ stagehand-kotlin studio · code

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

✅ stagehand-openapi studio · code

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

✅ 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@93160890e958a17d3159273abc12a33c5b1f9d57

✅ stagehand-java studio · code

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

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

---

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-06 18:56:55 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