[docs]: add variables feature documentation for agent

[chromiebot]

Add comprehensive documentation for the agent variables feature:

• Add Variables row to feature availability table (DOM/Hybrid only)
• Add new Variables section in basics/agent.mdx with:
  • Basic usage example with experimental flag
  • How variables work (LLM descriptions, placeholder syntax, runtime substitution)
  • Variable types (string, number, boolean)
  • Supported tools by mode (DOM vs Hybrid)
  • Cache optimization benefits
  • Best practices guide
• Update references/agent.mdx with:
  • Variables parameter in AgentExecuteOptions interfaces
  • Variable type definitions (Variable, VariableValue, Variables)
  • ParamField documentation with examples
  • New code example tab for variables usage

why

what changed

test plan

---

Summary by cubic

Adds variables docs for agents so developers can pass sensitive data without exposing values to the LLM. Addresses STG-1188 and updates the basics page with usage, tool support, and best practices.

• New Features
  • Feature table: added Variables (DOM/Hybrid only; not CUA; requires experimental).
  • basics/agent.mdx: variables section with basic usage, how it works (descriptions, placeholders, runtime substitution), value types (string/number/boolean), tool support by mode, cache optimization, and best practices.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: ef3e710

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

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/stagehand-docs	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

[greptile-apps]

Greptile Summary

Added comprehensive documentation for the agent variables feature across basics and reference pages. The changes include:

• Updated feature availability table to show Variables are supported in DOM and Hybrid modes only
• Added detailed Variables section in basics/agent.mdx explaining:
  • Basic usage with experimental flag requirement
  • How the LLM receives descriptions only while actual values are substituted at runtime
  • Supported value types (string, number, boolean)
  • Tool compatibility by mode (DOM: act, fillForm; Hybrid: type, fillFormVision, act)
  • Cache optimization benefits
  • Best practices with do/don't examples
• Added variables parameter to AgentExecuteOptions and AgentStreamExecuteOptions interfaces in references/agent.mdx
• Included type definitions for Variable, VariableValue, and Variables
• Added ParamField documentation with detailed examples
• Created new code example tab demonstrating variables usage

The documentation is clear, well-structured, and follows the existing documentation patterns in the codebase.

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• Documentation-only PR with well-structured, clear content that follows existing patterns. No code changes, no security concerns, and consistent with the project's documentation style
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/basics/agent.mdx	Added comprehensive Variables section with usage examples, supported tools, cache optimization details, and best practices
packages/docs/v3/references/agent.mdx	Added variables parameter to AgentExecuteOptions interfaces with type definitions, ParamField documentation, and code example tab

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Browser
    
    User->>Agent: execute({ variables: { password: {value, description} } })
    Agent->>LLM: System prompt with variable descriptions only
    Note over LLM: Sees "password: The user's password"<br/>NOT the actual value
    LLM->>Agent: Returns tool call with "%password%"
    Note over Agent: Runtime substitution
    Agent->>Agent: Replace "%password%" with actual value
    Agent->>Browser: Execute action with substituted value
    Browser-->>Agent: Action complete
    Agent-->>User: Result (no sensitive data logged)

Loading

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


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

<violation number="1" location="packages/docs/v3/references/agent.mdx:160">
P2: Documentation advertises agent `variables` option and `Variables` type that are not present in the actual AgentExecuteOptions/AgentStreamExecuteOptions API.</violation>
</file>

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