add variables to agent
Merged
TK
9mo ago+433+433+012345678901234567890123456789-45-45-01234567890123456789
Why
Users need a way to pass sensitive data (passwords, API keys, personal info) to agent executions without exposing the actual values to the LLM. This also enables reusable agent scripts where variable values can change without invalidating cached executions.
Usage
const agent = stagehand.agent({
model: "google/gemini-3-flash-preview",
mode: "hybrid"
});
await agent.execute({
instruction: "Log in to the dashboard",
variables: {
username: { value: "john@example.com", description: "The user's email address" },
password: { value: process.env.USER_PASSWORD, description: "The user's password" },
},
});
What Changed
- Added
variablesoption toagent.execute()acceptingRecord<string, { value: string | number | boolean; description: string }> - LLM sees variable names and descriptions in system prompt, uses
%variableName%syntax in tool calls - Variable substitution implemented in
act,type,fillForm, andfillFormVisiontools - Sensitive values never returned to LLM in tool outputs
- Cache keys use variable names only (not values) - changing values won't invalidate cache
- Feature requires
experimental: true, not supported in CUA mode - Shared utilities in
agent/utils/variables.ts
Test Plan
- Test agent execution with variables for login flow (username/password)
- Verify LLM correctly uses
%variableName%syntax in tool calls - Confirm sensitive values don't appear in LLM responses/tool outputs
- Test cache hit when variable values change but names stay same
- Verify error thrown when
variablesused withoutexperimental: true - Verify error thrown when
variablesused with CUA mode
Summary by cubic
Add first-class variables to agent.execute and act with a single VariableValue type. Use %name% placeholders that are swapped at runtime, never shown to the LLM, and cached by variable names only.
- New Features
- Unified API: Variables = Record<string, VariableValue> where VariableValue = string | number | boolean | { value; description? }; shared utils: resolveVariableValue, substituteVariables, flattenVariables.
- Prompt/tool UX: System prompt adds a variables section (names, optional descriptions, usage and example); tool inputs list available variables; %name% supported in act, type, fillForm, and fillFormVision (hybrid included).
- Runtime safety: Substitution only during execution; logs/replay keep original %tokens%; tool outputs never include sensitive values.
- Cache: Keys include variable names only; replay substitutes current values across act/fillForm steps.
- Guardrails/docs: Requires experimental: true; blocked in CUA mode with clear errors; docs updated for agent variables and act reference.