agent()

Complete API reference for the agent() method

Agent

See how to use agent() to create autonomous AI agents for multi-step browser workflows

Agent Creation

TypeScript

// Create agent instance
const agent = stagehand.agent(config?: AgentConfig): AgentInstance

AgentConfig Interface:

interface AgentConfig {
  systemPrompt?: string;
  integrations?: (Client | string)[];
  tools?: ToolSet;
  cua?: boolean;
  model?: string | AgentModelConfig<string>;
  executionModel?: string | AgentModelConfig<string>;
}

// AgentModelConfig for advanced configuration
type AgentModelConfig<TModelName extends string = string> = {
  modelName: TModelName;
} & Record<string, unknown>;

AgentInstance Interface:

interface AgentInstance {
  execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
}

Agent Configuration

systemPrompt · string

Custom system prompt to provide to the agent. Overrides the default system prompt and defines agent behavior.

model · string | AgentModelConfig

The model to use for agent functionality. Can be either:

• A string in the format "provider/model" (e.g., "openai/computer-use-preview", "anthropic/claude-sonnet-4-20250514")
• An object with modelName and additional provider-specific options

Available CUA Models:

• "openai/computer-use-preview"
• "openai/computer-use-preview-2025-03-11"
• "anthropic/claude-3-7-sonnet-latest"
• "anthropic/claude-haiku-4-5-20251001"
• "anthropic/claude-sonnet-4-20250514"
• "anthropic/claude-sonnet-4-5-20250929"
• "google/gemini-2.5-computer-use-preview-10-2025"

Show AgentModelConfig Object

modelName · string · required

The model name

[key: string] · unknown

Additional provider-specific options (e.g., apiKey, baseURL)

executionModel · string | AgentModelConfig

The model to use for tool execution (observe/act calls within agent tools). If not specified, inherits from the main model configuration.

Format: "provider/model" (e.g., "openai/gpt-4o-mini", "google/gemini-2.0-flash-exp")

cua · boolean

Indicates whether Computer Use Agent (CUA) mode is enabled. When false, the agent uses standard tool-based operation instead of computer control.

integrations · (Client | string)[]

MCP (Model Context Protocol) integrations for external tools and services.

Array of: MCP server URLs (strings) or connected Client objects

tools · ToolSet

Custom tool definitions to extend agent capabilities using the AI SDK ToolSet format.

Execute Method

TypeScript

// String instruction
await agent.execute(instruction: string): Promise<AgentResult>

// With options
await agent.execute(options: AgentExecuteOptions): Promise<AgentResult>

AgentExecuteOptions Interface:

interface AgentExecuteOptions {
  instruction: string;
  maxSteps?: number;
  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
  highlightCursor?: boolean;
}

Execute Parameters

instruction · string · required

High-level task description in natural language.

maxSteps · number

Maximum number of actions the agent can take before stopping.

Default: Varies by configuration

page · PlaywrightPage | PuppeteerPage | PatchrightPage | Page

Optional: Specify which page to perform the agent execution on. Supports multiple browser automation libraries:

• Playwright: Native Playwright Page objects
• Puppeteer: Puppeteer Page objects
• Patchright: Patchright Page objects
• Stagehand Page: Stagehand’s wrapped Page object

If not specified, defaults to the current “active” page in your Stagehand instance.

highlightCursor · boolean

Whether to show a visual cursor on the page during agent execution. Useful for debugging and demonstrations.

Default: false

Response

Returns: Promise<AgentResult>

AgentResult Interface:

interface AgentResult {
  success: boolean;
  message: string;
  actions: AgentAction[];
  completed: boolean;
  metadata?: Record<string, unknown>;
  usage?: {
    input_tokens: number;
    output_tokens: number;
    inference_time_ms: number;
  };
}

// AgentAction can contain various tool-specific fields
interface AgentAction {
  type: string;
  reasoning?: string;
  taskCompleted?: boolean;
  action?: string;
  timeMs?: number;        // wait tool
  pageText?: string;      // ariaTree tool
  pageUrl?: string;       // ariaTree tool
  instruction?: string;   // various tools
  [key: string]: unknown; // Additional tool-specific fields
}

success · boolean

Whether the task was completed successfully.

message · string

Description of the execution result and status.

actions · AgentAction[]

Array of individual actions taken during execution. Each action contains tool-specific data.

completed · boolean

Whether the agent believes the task is fully complete.

metadata · Record<string, unknown>

Additional execution metadata and debugging information.

usage · object

Token usage and performance metrics.

Show Usage Metrics

input_tokens · number

Number of input tokens used

output_tokens · number

Number of output tokens generated

inference_time_ms · number

Total inference time in milliseconds

Example Response

{
  "success": true,
  "message": "Task completed successfully",
  "actions": [
    {
      "type": "act",
      "instruction": "click the submit button",
      "reasoning": "User requested to submit the form",
      "taskCompleted": false
    },
    {
      "type": "observe",
      "instruction": "check if submission was successful",
      "taskCompleted": true
    }
  ],
  "completed": true,
  "metadata": {
    "steps_taken": 2
  },
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 340,
    "inference_time_ms": 2500
  }
}

Code Examples

Basic Usage

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

// Initialize with Browserbase (API key and project ID from environment variables)
// Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID in your environment
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "anthropic/claude-sonnet-4-20250514"
});
await stagehand.init();

const page = stagehand.context.pages()[0];
// Create agent with default configuration
const agent = stagehand.agent();

// Navigate to a page
await page.goto("https://www.google.com");

// Execute a task
const result = await agent.execute("Search for 'Stagehand automation' and click the first result");

console.log(result.message);
console.log(`Completed: ${result.completed}`);
console.log(`Actions taken: ${result.actions.length}`);

Custom Configuration

// Create agent with custom model and system prompt
const agent = stagehand.agent({
  model: "openai/computer-use-preview",
  systemPrompt: "You are a helpful assistant that can navigate websites efficiently. Always verify actions before proceeding.",
  executionModel: "openai/gpt-4o-mini"  // Use faster model for tool execution
});

const page = stagehand.context.pages()[0];
await page.goto("https://example.com");

const result = await agent.execute({
  instruction: "Fill out the contact form with test data",
  maxSteps: 10,
  highlightCursor: true
});

Advanced Model Config

// Using AgentModelConfig for advanced configuration
const agent = stagehand.agent({
  model: {
    modelName: "anthropic/claude-sonnet-4-20250514",
    apiKey: process.env.ANTHROPIC_API_KEY,
    baseURL: "https://custom-proxy.com/v1"
  }
});

const result = await agent.execute("Complete the checkout process");

Multi-Page

const page1 = stagehand.context.pages()[0];
const page2 = await stagehand.context.newPage();

const agent = stagehand.agent();

// Execute on specific page
await page2.goto("https://example.com/dashboard");
const result = await agent.execute({
  instruction: "Export the data table",
  page: page2
});

MCP Integrations

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

// Create agent with MCP integrations
const agent = stagehand.agent({
  model: "anthropic/claude-sonnet-4-20250514",
  integrations: [
    "https://mcp-server.example.com",  // MCP server URL
    mcpClientInstance  // Or pre-connected Client object
  ]
});

const result = await agent.execute("Use the external tool to process this data");

Custom Tools

import { tool } from "ai";
import { z } from "zod/v3";

// Define custom tools using AI SDK format
const customTools = {
  calculateTotal: tool({
    description: "Calculate the total of items in cart",
    parameters: z.object({
      items: z.array(z.object({
        price: z.number(),
        quantity: z.number()
      }))
    }),
    execute: async ({ items }) => {
      const total = items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
      return { total };
    }
  })
};

const agent = stagehand.agent({
  model: "openai/computer-use-preview",
  tools: customTools
});

const result = await agent.execute("Calculate the total cost of items in the shopping cart");

Error Types

The following errors may be thrown by the agent() method:

• StagehandError - Base class for all Stagehand-specific errors
• StagehandInitError - Agent was not properly initialized
• MissingLLMConfigurationError - No LLM API key or client configured
• UnsupportedModelError - The specified model is not supported for agent functionality
• UnsupportedModelProviderError - The specified model provider is not supported
• InvalidAISDKModelFormatError - Model string does not follow the required provider/model format
• MCPConnectionError - Failed to connect to MCP server
• StagehandDefaultError - General execution error with detailed message