agent()

agent(config?: AgentConfig): AgentInstance

execute(
  instructionOrOptions: string | AgentExecuteOptions
): Promise<AgentResult>

interface AgentResult {
  success: boolean;      // Whether the task completed successfully
  message: string;       // Agent's final message
  actions: AgentAction[]; // Actions taken by the agent
  completed: boolean;    // Whether agent called the done tool
  messages?: ModelMessage[]; // Conversation messages (for continuation)
  output?: Record<string, unknown>; // Custom output data (if schema provided)
  usage?: {              // Token usage statistics
    input_tokens: number;
    output_tokens: number;
    reasoning_tokens?: number;
    cached_input_tokens?: number;
    inference_time_ms: number;
  };
}

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
});

await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://news.ycombinator.com");

// Create and execute agent
const agent = stagehand.agent();

const result = await agent.execute(
  "Find the top story and click on it"
);

if (result.success) {
  console.log("Task completed:", result.message);
  console.log("Actions taken:", result.actions.length);
} else {
  console.error("Task failed:", result.message);
}

const agent = stagehand.agent({
  model: "anthropic/claude-sonnet-4-5-20250929",
  executionModel: "google/gemini-2.0-flash", // Fast model for tool execution
});

const result = await agent.execute({
  instruction: "Search for 'web scraping' and extract the first 5 results",
  maxSteps: 15,
});

const agent = stagehand.agent({
  model: "anthropic/claude-sonnet-4-5-20250929",
  stream: true, // Enable streaming
});

const agentRun = await agent.execute(
  "Go to Amazon and search for 'laptop'"
);

// Stream text output
for await (const delta of agentRun.textStream) {
  process.stdout.write(delta);
}

// Wait for final result
const result = await agentRun.result;
console.log("\nFinal result:", result);

import { z } from "zod";

const agent = stagehand.agent();

const result = await agent.execute({
  instruction: "Find the cheapest laptop on this page",
  output: z.object({
    name: z.string().describe("Product name"),
    price: z.string().describe("Product price"),
    rating: z.number().describe("Product rating out of 5"),
  }),
});

if (result.output) {
  console.log(`Found: ${result.output.name}`);
  console.log(`Price: ${result.output.price}`);
  console.log(`Rating: ${result.output.rating}/5`);
}

const agent = stagehand.agent();

// First task
const result1 = await agent.execute(
  "Go to GitHub and search for 'stagehand'"
);

// Continue the conversation
const result2 = await agent.execute({
  instruction: "Now click on the first repository",
  messages: result1.messages, // Continue from previous state
});

// Another continuation
const result3 = await agent.execute({
  instruction: "Read the README and summarize it",
  messages: result2.messages,
});

const agent = stagehand.agent();

await page.goto("https://example.com/login");

const result = await agent.execute({
  instruction: "Log in using the provided credentials",
  variables: {
    username: {
      value: process.env.USERNAME,
      description: "User's email address",
    },
    password: {
      value: process.env.PASSWORD,
      description: "User's password",
    },
  },
});

const agent = stagehand.agent();

const result = await agent.execute({
  instruction: "Navigate to the product page and click buy",
  excludeTools: ["screenshot", "extract"], // Faster execution
});

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 60000); // 1 minute

try {
  const result = await agent.execute({
    instruction: "Complete the checkout process",
    signal: controller.signal,
  });
  clearTimeout(timeoutId);
} catch (error) {
  if (error instanceof AgentAbortError) {
    console.log("Agent was aborted");
  }
}

const agent = stagehand.agent({
  mode: "hybrid", // Use coordinate-based tools
  model: "google/gemini-2.0-flash",
});

await page.goto("https://example.com");

const result = await agent.execute({
  instruction: "Click on the blue button in the top right",
  highlightCursor: true, // Show cursor movements
});

const agent = stagehand.agent({
  mode: "cua",
  model: "anthropic/claude-sonnet-4-5-20250929",
});

const result = await agent.execute(
  "Navigate to the settings page and enable dark mode"
);

const agent = stagehand.agent();

const result = await agent.execute({
  instruction: "Search for products and add to cart",
  callbacks: {
    onStepFinish: async (step) => {
      console.log("Step completed:", step.finishReason);
      if (step.toolCalls) {
        step.toolCalls.forEach((call) => {
          console.log(`Tool: ${call.toolName}`);
        });
      }
    },
  },
});

try {
  const result = await agent.execute(instruction);
  
  if (!result.success) {
    console.error("Agent failed:", result.message);
  }
} catch (error) {
  if (error instanceof AgentAbortError) {
    console.log("Agent was aborted");
  } else if (error instanceof StreamingCallbacksInNonStreamingModeError) {
    console.error("Invalid callback usage");
  } else {
    console.error("Unexpected error:", error);
  }
}