update docs to add variables + remove zod v3 pin + export tool from s…

[tkattkat]

…tagehand

why

Update docs to reflect current code base

what changed

• updated documentation for variables
• removed pinned zod versions in docs
• replaced tool references to show them being exported from stagehand
• updated docs to reflect hybrid mode no longer being experimental

test plan

ran mintlify dev and looked at docs

---

Summary by cubic

Updated docs to add agent variables and clarify how they work (secure runtime substitution with names/descriptions only), switch tool imports to Stagehand, and remove outdated zod v3 and hybrid mode experimental notes. Examples and references are simpler and consistent.

• New Features

  • Documented agent variables for non-CUA (requires experimental: true), with Variables/VariableValue types, usage examples, and guidance to include descriptions.

• Refactors

  • Removed “experimental: true” from hybrid mode across docs.
  • Replaced import { tool } from "ai" with import { tool } from "@browserbasehq/stagehand".
  • Unpinned Zod imports to import { z } from "zod".
  • Updated agent reference and errors to include variables as an experimental feature (e.g., ExperimentalNotConfiguredError).

^{Written for commit 1d72c14. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1d72c14

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

[greptile-apps]

Greptile Summary

This PR updates the documentation to reflect recent changes to the codebase, specifically removing the experimental flag requirement for hybrid mode, unpinning zod v3, and updating tool import examples.

Key Changes:

• Hybrid mode no longer requires experimental: true flag - removed from all examples and warnings
• All zod/v3 imports updated to zod across documentation files
• Tool imports changed from import { tool } from "ai" to import { tool } from "@browserbasehq/stagehand"
• Variables documentation significantly improved with clearer descriptions and better examples
• Code comment in validateExperimentalFeatures.ts updated to reflect that variables (not hybrid mode) require experimental flag

Documentation Quality:
The changes are purely documentation updates with no functional code changes (except one comment update). All examples are consistent and follow the new conventions.

Confidence Score: 5/5

• This PR is safe to merge - it only updates documentation to match current codebase behavior
• All changes are documentation-only (except one comment update), accurately reflecting the removal of experimental flag requirement for hybrid mode, consistent import updates throughout all docs, and improved clarity for users
• No files require special attention

Important Files Changed

Filename	Overview
claude.md	Removed experimental flag requirement from hybrid mode documentation
packages/core/lib/v3/agent/utils/validateExperimentalFeatures.ts	Updated comment to reflect hybrid mode no longer requires experimental flag, added variables to experimental features list
packages/docs/v3/basics/agent.mdx	Updated to remove experimental flag from hybrid mode examples, changed tool imports from ai to stagehand, removed zod v3 pin, improved variables documentation
packages/docs/v3/references/agent.mdx	Added comprehensive variables documentation, removed experimental flag from hybrid mode, updated tool imports from ai to stagehand, removed zod v3 pin

_{Last reviewed commit: 8431332}

[greptile-apps]

_{12 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

1 issue found across 12 files

Confidence score: 4/5

• Only issue is a documentation inconsistency about the source of tool, so runtime behavior isn’t affected and merge risk looks low
• Consider updating the wording to match the new @browserbasehq/stagehand import to avoid reader confusion in the docs
• Pay close attention to packages/docs/v3/basics/agent.mdx - text references the old SDK source for tool

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/v3/basics/agent.mdx">

<violation number="1" location="packages/docs/v3/basics/agent.mdx:254">
P2: Documentation inconsistency: The surrounding text says to use the `tool` helper "from the Vercel AI SDK" but the import was updated to `@browserbasehq/stagehand`. Consider updating the text to reflect the new import source (e.g., mention that `tool` is re-exported from stagehand).</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client as User Application
    participant SH as Stagehand SDK
    participant Val as validateExperimentalFeatures
    participant LLM as Language Model (LLM)
    participant Browser as Browser Instance

    Note over Client,SH: Initialization & Setup

    Client->>SH: new Stagehand({ experimental: true/false })
    SH-->>Client: instance

    Client->>SH: agent({ model: "...", mode: "hybrid" })
    Note right of SH: CHANGED: Hybrid mode no longer<br/>requires experimental: true

    Note over Client,Browser: Agent Execution with Variables

    Client->>SH: execute({ instruction, variables: { key: { value, description } } })
    
    SH->>Val: validate(options)
    alt NEW: variables provided AND experimental: false
        Val-->>Client: Throw ExperimentalNotConfiguredError
    else Validation Success
        Val-->>SH: proceed
    end

    SH->>SH: Construct System Prompt
    Note right of SH: NEW: Prompt includes variable<br/>NAMES and DESCRIPTIONS only

    SH->>LLM: Fetch completion (Prompt + Instruction)
    LLM-->>SH: Return tool call (e.g. act("%password%"))

    alt NEW: Tool call contains %variable%
        SH->>SH: CHANGED: Substitute placeholder with ACTUAL value
    end

    SH->>Browser: Execute action (e.g. type "secret_password")
    Browser-->>SH: Action Result
    
    SH-->>Client: AgentResult (Logs exclude sensitive values)

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}