Skip to main content

​
ActResult

Result returned from act() method. 
interface ActResult {
  success: boolean;
  message: string;
  actionDescription: string;
  actions: Action[];
}
​
success
boolean
required
Whether the action completed successfully
​
message
string
required
Human-readable result messageExamples:
​
actionDescription
string
required
Detailed description of what was done
​
actions
Action[]
required
Array of low-level actions that were performed

​
Example

const result = await stagehand.act("click the login button");

if (result.success) {
  console.log("Success:", result.message);
  console.log("Action:", result.actionDescription);
  console.log("Steps taken:", result.actions.length);
} else {
  console.error("Failed:", result.message);
}

​
AgentResult

Result returned from agent.execute() method. 
interface AgentResult {
  success: boolean;
  message: string;
  actions: AgentAction[];
  completed: boolean;
  metadata?: Record<string, unknown>;
  usage?: {
    input_tokens: number;
    output_tokens: number;
    reasoning_tokens?: number;
    cached_input_tokens?: number;
    inference_time_ms: number;
  };
  messages?: ModelMessage[];
  output?: Record<string, unknown>;
}
​
success
boolean
required
Whether the task completed successfully
​
message
string
required
Final result message from the agent
​
actions
AgentAction[]
required
Array of actions taken by the agent
​
completed
boolean
required
Whether the agent finished naturally (vs. hitting max steps or being aborted)
​
metadata
Record<string, unknown>
Additional metadata about the execution
​
usage
object
Token usage and performance metrics
​
messages
ModelMessage[]
Conversation messages (for continuing the conversation)
​
output
Record<string, unknown>
Structured output data if an output schema was provided

​
Example

const agent = stagehand.agent();
const result = await agent.execute("Find the cheapest flight");

console.log("Success:", result.success);
console.log("Message:", result.message);
console.log("Steps taken:", result.actions.length);
console.log("Completed naturally:", result.completed);

if (result.usage) {
  console.log("Tokens used:", result.usage.input_tokens + result.usage.output_tokens);
  console.log("Time:", result.usage.inference_time_ms, "ms");
}

​
AgentAction

Single action taken by an agent. 
interface AgentAction {
  type: string;
  reasoning?: string;
  taskCompleted?: boolean;
  action?: string;
  timeMs?: number;
  pageText?: string;
  pageUrl?: string;
  instruction?: string;
  [key: string]: unknown;
}
​
type
string
required
Type of action (e.g., “click”, “type”, “navigate”, “extract”)
​
reasoning
string
Agent’s reasoning for this action
​
taskCompleted
boolean
Whether this action completed the task
​
action
string
Description of the action
​
timeMs
number
Time taken for this action in milliseconds
​
pageText
string
Page text at the time of action
​
pageUrl
string
Page URL at the time of action
​
instruction
string
Instruction given for this action

​
AgentStreamResult

Result returned from streaming agent execution. 
type AgentStreamResult = StreamTextResult<ToolSet, never> & {
  result: Promise<AgentResult>;
};
​
textStream
AsyncIterable<string>
required
Stream of text chunks from the agent
​
result
Promise<AgentResult>
required
Promise that resolves to the final AgentResult

​
Example

const agent = stagehand.agent({ stream: true });
const streamResult = await agent.execute("Complete the task");

// Process stream
for await (const chunk of streamResult.textStream) {
  process.stdout.write(chunk);
}

// Get final result
const result = await streamResult.result;
console.log("\nFinal result:", result.message);

​
StagehandMetrics

Token usage and performance metrics. 
interface StagehandMetrics {
  // Act metrics
  actPromptTokens: number;
  actCompletionTokens: number;
  actReasoningTokens: number;
  actCachedInputTokens: number;
  actInferenceTimeMs: number;
  
  // Extract metrics
  extractPromptTokens: number;
  extractCompletionTokens: number;
  extractReasoningTokens: number;
  extractCachedInputTokens: number;
  extractInferenceTimeMs: number;
  
  // Observe metrics
  observePromptTokens: number;
  observeCompletionTokens: number;
  observeReasoningTokens: number;
  observeCachedInputTokens: number;
  observeInferenceTimeMs: number;
  
  // Agent metrics
  agentPromptTokens: number;
  agentCompletionTokens: number;
  agentReasoningTokens: number;
  agentCachedInputTokens: number;
  agentInferenceTimeMs: number;
  
  // Total metrics
  totalPromptTokens: number;
  totalCompletionTokens: number;
  totalReasoningTokens: number;
  totalCachedInputTokens: number;
  totalInferenceTimeMs: number;
}

​
Example

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();

// Perform operations
await stagehand.act("click button");
await stagehand.extract("Get title");

// Get metrics
const metrics = await stagehand.metrics;

console.log("Total tokens:", metrics.totalPromptTokens + metrics.totalCompletionTokens);
console.log("Act tokens:", metrics.actPromptTokens + metrics.actCompletionTokens);
console.log("Total inference time:", metrics.totalInferenceTimeMs, "ms");

​
EvaluationResult

Result from V3Evaluator.ask() method. 
interface EvaluationResult {
  evaluation: "YES" | "NO" | "INVALID";
  reasoning: string;
}
​
evaluation
'YES' | 'NO' | 'INVALID'
required
Evaluation result:
  • "YES": Goal was achieved
  • "NO": Goal was not achieved
  • "INVALID": Unable to evaluate
​
reasoning
string
required
Detailed reasoning for the evaluation

​
Example

import { V3Evaluator } from "@browserbasehq/stagehand";

const evaluator = new V3Evaluator(stagehand);

const result = await evaluator.ask({
  question: "Is the user logged in?",
  screenshot: true,
});

if (result.evaluation === "YES") {
  console.log("User is logged in");
  console.log("Reasoning:", result.reasoning);
} else {
  console.log("User is not logged in");
}

​
SnapshotResult

Result from page snapshot operations. 
interface SnapshotResult {
  formattedTree: string;
  xpathMap: Record<string, string>;
  urlMap: Record<string, string>;
}
​
formattedTree
string
required
Formatted accessibility tree representation
​
xpathMap
Record<string, string>
required
Mapping of element IDs to XPath selectors
​
urlMap
Record<string, string>
required
Mapping of element IDs to URLs (for links)

Build docs developers (and LLMs) love

Get started for freeTalk to us