agent()

// With stream: true in AgentConfig
await agent.execute(options: AgentStreamExecuteOptions): Promise<AgentStreamResult>

interface AgentStreamExecuteOptions {
  instruction: string;
  maxSteps?: number;
  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
  highlightCursor?: boolean;
  messages?: ModelMessage[]; // Continue from previous conversation (experimental)
  signal?: AbortSignal; // Cancel execution (experimental)
  callbacks?: AgentStreamCallbacks;
}

interface AgentStreamCallbacks {
  prepareStep?: PrepareStepFunction<ToolSet>;
  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
  onChunk?: StreamTextOnChunkCallback<ToolSet>;
  onFinish?: StreamTextOnFinishCallback<ToolSet>;
  onError?: StreamTextOnErrorCallback;
  onAbort?: (event: { steps: Array<StepResult<ToolSet>> }) => void | Promise<void>;
}

interface AgentStreamResult {
  // Async iterable of text chunks for incremental output
  textStream: AsyncIterable<string>;
  
  // Async iterable of all stream events (tool calls, messages, etc.)
  fullStream: AsyncIterable<StreamPart>;
  
  // Promise that resolves to the final AgentResult when streaming completes
  result: Promise<AgentResult>;
  
  // Additional properties from StreamTextResult<ToolSet, never>
  // See Vercel AI SDK documentation for full details
}

// 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
});

// 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");

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
});

const stagehand = new Stagehand({
  env: "LOCAL",
  experimental: true, // Required for streaming
});
await stagehand.init();

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

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

const streamResult = await agent.execute({
  instruction: "Search for headphones and find the best deal",
  maxSteps: 20,
});

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

// Get the final result
const finalResult = await streamResult.result;
console.log("Completed:", finalResult.completed);

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

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

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

const result = await agent.execute({
  instruction: "Fill out the contact form",
  maxSteps: 10,
  callbacks: {
    prepareStep: async (stepContext) => {
      console.log(`Starting step ${stepContext.stepNumber}`);
      return stepContext;
    },
    onStepFinish: async (event) => {
      console.log(`Step finished: ${event.finishReason}`);
      if (event.toolCalls) {
        for (const tc of event.toolCalls) {
          console.log(`Tool: ${tc.toolName}`, tc.input);
        }
      }
    },
  },
});

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

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

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

const controller = new AbortController();

// Abort after 30 seconds
setTimeout(() => controller.abort("Timeout exceeded"), 30000);

try {
  const result = await agent.execute({
    instruction: "Complete a complex multi-step workflow",
    maxSteps: 50,
    signal: controller.signal,
  });
} catch (error) {
  if (error.name === "AgentAbortError") {
    console.log("Task cancelled:", error.message);
  }
}

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

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

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

// First execution
const firstResult = await agent.execute({
  instruction: "Search for laptops and list the top 3 options",
  maxSteps: 10,
});

// Continue conversation with context from first run
const secondResult = await agent.execute({
  instruction: "Filter those results by price under $1000",
  maxSteps: 10,
  messages: firstResult.messages, // Pass previous messages
});

// Chain further with accumulated context
const thirdResult = await agent.execute({
  instruction: "Add the best-rated one to cart",
  maxSteps: 10,
  messages: secondResult.messages,
});

console.log("Final:", thirdResult.message);

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");

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");