Overview
The Agent provides autonomous, multi-step task execution using AI. It can navigate websites, interact with elements, extract data, and complete complex workflows.Creating an Agent
Create an agent usingstagehand.agent():
const agent = stagehand.agent(config?);
Show properties
Show properties
Model to use for agent reasoningFormat:
"provider/model" (e.g., "openai/gpt-4o")Model for tool execution (observe/act calls)Inherits from
model if not specifiedCustom system prompt for the agent
Tool mode:
dom: Semantic tools (act, fillForm) - defaulthybrid: Coordinate-based tools (click, type)cua: Computer Use Agent (screenshot-based)
"dom"Enable streaming modeDefault:
falseMCP (Model Context Protocol) integrations
Custom tools for the agent
Agent instance with execute() method
execute()
Execute a task with the agent.Non-streaming Mode
const result = await agent.execute(instructionOrOptions);
Task instruction or options object
Show AgentExecuteOptions properties
Show AgentExecuteOptions properties
Task description in natural language
Maximum number of stepsDefault:
100Page to operate on (defaults to active page)
Show cursor overlay during execution
Previous conversation messages to continue from
Signal to cancel execution
Tool names to exclude (not supported in CUA mode)Available tools:
- DOM mode:
act,fillForm,ariaTree,extract,goto,scroll,keys,navback,screenshot,think,wait,done,search - Hybrid mode:
click,type,dragAndDrop,clickAndHold,fillFormVision,act,ariaTree,extract,goto,scroll,keys,navback,screenshot,think,wait,done,search
Zod schema for structured output
Variables for form filling and typingRequires
experimental: trueFormat: { name: value } or { name: { value, description } }Show AgentResult properties
Show AgentResult properties
Whether the task completed successfully
Result message
Array of actions taken
Whether the agent finished naturally
Additional metadata
Conversation messages (for continuation)
Structured output data (if output schema provided)
Streaming Mode
Whenstream: true is set in AgentConfig:
const streamResult = await agent.execute(options);
// Access the text stream
for await (const chunk of streamResult.textStream) {
console.log(chunk);
}
// Get final result
const result = await streamResult.result;
Stream result with
textStream and result propertiesExamples
Basic Agent
import { Stagehand } from "@browserbasehq/stagehand";
const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = await stagehand.context.newPage();
await page.goto("https://github.com");
// Create and execute agent
const agent = stagehand.agent();
const result = await agent.execute(
"Find the most starred TypeScript repository"
);
console.log(result.message);
console.log(`Steps taken: ${result.actions.length}`);
await stagehand.close();
Agent with Structured Output
import { z } from "zod";
const agent = stagehand.agent();
const result = await agent.execute({
instruction: "Find flight information from NYC to LA",
output: z.object({
price: z.string().describe("Flight price"),
airline: z.string().describe("Airline name"),
departureTime: z.string(),
}),
});
console.log(result.output);
// { price: "$299", airline: "Delta", departureTime: "8:00 AM" }
Agent with Variables
const agent = stagehand.agent();
const result = await agent.execute({
instruction: "Fill out the login form and submit",
variables: {
username: {
value: "[email protected]",
description: "Login email",
},
password: {
value: "secret123",
description: "Account password",
},
},
});
Streaming Agent
const agent = stagehand.agent({ stream: true });
const streamResult = await agent.execute({
instruction: "Search for restaurants near me",
callbacks: {
onChunk: async (chunk) => {
process.stdout.write(chunk.text);
},
onStepFinish: async (step) => {
console.log("\nStep completed:", step.toolCalls);
},
},
});
const result = await streamResult.result;
console.log("\nFinal result:", result.message);
Agent with Abort Signal
const controller = new AbortController();
// Abort after 30 seconds
setTimeout(() => controller.abort(), 30000);
const agent = stagehand.agent();
const result = await agent.execute({
instruction: "Complete this long task",
signal: controller.signal,
});
if (!result.completed) {
console.log("Task was aborted");
}
CUA Mode Agent
// Computer Use Agent mode with screenshot-based interaction
const agent = stagehand.agent({
mode: "cua",
model: "anthropic/claude-opus-4-5",
});
const result = await agent.execute({
instruction: "Navigate to settings and enable dark mode",
callbacks: {
onSafetyConfirmation: async (checks) => {
console.log("Safety checks:", checks);
// Return { acknowledged: true } to proceed
return { acknowledged: true };
},
},
});