add example for custom tools and docs (#1211)

# why
We didn't have docs for passing custom tools to stagehand agent or
examples, only MCP integrations. Under the hood, stagehand treats both
the same, and passing custom tools directly is (most times) more
convenient and performant.

# what changed
Added an example `agent-custom-tools.ts` as well as docs under the
basics > agent section

# test plan

Author: miguelg719

.changeset/sharp-laws-knock.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add an example for passing custom tools to agent

packages/core/examples/agent-custom-tools.ts

@@ -0,0 +1,107 @@
+/**
+ * This example shows how to pass custom tools to stagehand agent (both CUA and non-CUA)
+ */
+import { z } from "zod/v3";
+import { tool } from "ai";
+import { Stagehand } from "../lib/v3";
+import chalk from "chalk";
+
+// Mock weather API, replace with your own API/tool logic
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const fetchWeatherAPI = async (location: string) => {
+  return {
+    temp: 70,
+    conditions: "sunny",
+  };
+};
+
+// Define the tool in an AI SDK format
+const getWeather = tool({
+  description: "Get the current weather in a location",
+  inputSchema: z.object({
+    location: z.string().describe("The location to get weather for"),
+  }),
+  execute: async ({ location }) => {
+    // Your custom logic here
+    const weather = await fetchWeatherAPI(location);
+    return {
+      location,
+      temperature: weather.temp,
+      conditions: weather.conditions,
+    };
+  },
+});
+
+async function main() {
+  console.log(
+    `\n${chalk.bold("Stagehand 🤘 Computer Use Agent (CUA) Demo")}\n`,
+  );
+
+  // Initialize Stagehand
+  const stagehand = new Stagehand({
+    env: "LOCAL",
+    verbose: 2,
+    experimental: true, // You must enable experimental mode to use custom tools / MCP integrations
+    model: "anthropic/claude-sonnet-4-5",
+  });
+  await stagehand.init();
+
+  try {
+    const page = stagehand.context.pages()[0];
+
+    // Create a computer use agent
+    const agent = stagehand.agent({
+      cua: true,
+      model: {
+        modelName: "anthropic/claude-sonnet-4-5-20250929",
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      systemPrompt: `You are a helpful assistant that can use a web browser.
+      You are currently on the following page: ${page.url()}.
+      Do not ask follow up questions, the user will trust your judgement. Today's date is ${new Date().toLocaleDateString()}.`,
+      tools: {
+        getWeather, // Pass the tools to the agent
+      },
+    });
+
+    // const agent = stagehand.agent({
+    //   systemPrompt: `You are a helpful assistant that can use a web browser.
+    //   You are currently on the following page: ${page.url()}.
+    //   Do not ask follow up questions, the user will trust your judgement. Today's date is ${new Date().toLocaleDateString()}.`,
+    //   // Pass the tools to the agent
+    //   tools: {
+    //     getWeather: getWeather,
+    //   },
+    // });
+
+    // Navigate to the Browserbase careers page
+    await page.goto("https://www.google.com");
+
+    // Define the instruction for the CUA
+    const instruction = "What's the weather in San Francisco?";
+    console.log(`Instruction: ${chalk.white(instruction)}`);
+
+    // Execute the instruction
+    const result = await agent.execute({
+      instruction,
+      maxSteps: 20,
+    });
+
+    console.log(`${chalk.green("✓")} Execution complete`);
+    console.log(`${chalk.yellow("⤷")} Result:`);
+    console.log(chalk.white(JSON.stringify(result, null, 2)));
+  } catch (error) {
+    console.log(`${chalk.red("✗")} Error: ${error}`);
+    if (error instanceof Error && error.stack) {
+      console.log(chalk.dim(error.stack.split("\n").slice(1).join("\n")));
+    }
+  } finally {
+    // Close the browser
+    await stagehand.close();
+  }
+}
+
+main().catch((error) => {
+  console.log(`${chalk.red("✗")} Unhandled error in main function`);
+  console.log(chalk.red(error));
+});

packages/core/lib/v3/v3.ts

@@ -1363,25 +1363,34 @@ export class V3 {
   } {
     this.logger({
       category: "agent",
-      message: "Creating v3 agent instance with options:",
+      message: `Creating v3 agent instance with options: ${JSON.stringify(options)}`,
       level: 1,
       auxiliary: {
         cua: { value: options?.cua ? "true" : "false", type: "boolean" },
-        model:
-          typeof options?.model === "string"
+        model: options?.model
+          ? typeof options?.model === "string"
             ? { value: options.model, type: "string" }
-            : { value: options.model.modelName, type: "string" },
+            : { value: options.model.modelName, type: "string" }
+          : { value: this.llmClient.modelName, type: "string" },
         systemPrompt: { value: options?.systemPrompt ?? "", type: "string" },
         tools: { value: JSON.stringify(options?.tools ?? {}), type: "object" },
-        integrations: {
-          value: JSON.stringify(options?.integrations ?? []),
-          type: "object",
-        },
+        ...(options?.integrations && {
+          integrations: {
+            value: JSON.stringify(options.integrations),
+            type: "object",
+          },
+        }),
       },
     });
 
     // If CUA is enabled, use the computer-use agent path
     if (options?.cua) {
+      if ((options?.integrations || options?.tools) && !this.experimental) {
+        throw new Error(
+          "MCP integrations and custom tools are experimental. Enable experimental: true in V3 options.",
+        );
+      }
+
       const modelToUse = options?.model || {
         modelName: this.modelName,
         ...this.modelClientOptions,
@@ -1499,9 +1508,9 @@ export class V3 {
     return {
       execute: async (instructionOrOptions: string | AgentExecuteOptions) =>
         withInstanceLogContext(this.instanceId, async () => {
-          if (options?.integrations && !this.experimental) {
+          if ((options?.integrations || options?.tools) && !this.experimental) {
             throw new Error(
-              "MCP integrations are experimental. Enable experimental: true in V3 options.",
+              "MCP integrations and custom tools are experimental. Enable experimental: true in V3 options.",
             );
           }
 

packages/docs/v3/basics/agent.mdx

@@ -142,6 +142,139 @@ When you use `agent()`, Stagehand will return a `Promise<AgentResult>` with the
 }
 ```
 
+## Custom Tools
+
+Agents can be enhanced with custom tools for more granular control and better performance. Unlike MCP integrations, custom tools are defined inline and execute directly within your application.
+
+<Note>Custom tools provide a cleaner, more performant alternative to MCP integrations when you need specific functionality.</Note>
+
+### Defining Custom Tools
+
+Use the `tool` helper from the [Vercel AI SDK](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling) to define custom tools:
+
+<CodeGroup>
+```typescript Basic Tool
+import { tool } from "ai";
+import { z } from "zod/v3";
+
+const agent = stagehand.agent({
+  model: "openai/gpt-5",
+  tools: {
+    getWeather: tool({
+      description: 'Get the current weather in a location',
+      inputSchema: z.object({
+        location: z.string().describe('The location to get weather for'),
+      }),
+      execute: async ({ location }) => {
+        // Your custom logic here
+        const weather = await fetchWeatherAPI(location);
+        return {
+          location,
+          temperature: weather.temp,
+          conditions: weather.conditions,
+        };
+      },
+    }),
+  },
+  systemPrompt: 'You are a helpful assistant with access to weather data.',
+});
+
+await agent.execute("What's the weather in San Francisco and should I bring an umbrella?");
+```
+
+```typescript Multiple Tools
+import { tool } from "ai";
+import { z } from "zod/v3";
+
+const agent = stagehand.agent({
+  cua: true,
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: {
+    searchDatabase: tool({
+      description: 'Search for records in the database',
+      inputSchema: z.object({
+        query: z.string().describe('The search query'),
+        limit: z.number().optional().describe('Max results to return'),
+      }),
+      execute: async ({ query, limit = 10 }) => {
+        const results = await db.search(query, limit);
+        return { results };
+      },
+    }),
+
+    calculatePrice: tool({
+      description: 'Calculate the total price with tax',
+      inputSchema: z.object({
+        amount: z.number().describe('The base amount'),
+        taxRate: z.number().describe('Tax rate as decimal (e.g., 0.08 for 8%)'),
+      }),
+      execute: async ({ amount, taxRate }) => {
+        const total = amount * (1 + taxRate);
+        return { total: total.toFixed(2) };
+      },
+    }),
+  },
+});
+
+await agent.execute("Find products under $50 and calculate the total with 8% tax");
+```
+
+```typescript Tool with API Integration
+import { tool } from "ai";
+import { z } from "zod/v3";
+
+const agent = stagehand.agent({
+  model: "google/gemini-2.0-flash",
+  tools: {
+    sendEmail: tool({
+      description: 'Send an email via SendGrid',
+      inputSchema: z.object({
+        to: z.string().email().describe('Recipient email address'),
+        subject: z.string().describe('Email subject'),
+        body: z.string().describe('Email body content'),
+      }),
+      execute: async ({ to, subject, body }) => {
+        const response = await fetch('https://api.sendgrid.com/v3/mail/send', {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            personalizations: [{ to: [{ email: to }] }],
+            from: { email: '[email protected]' },
+            subject,
+            content: [{ type: 'text/plain', value: body }],
+          }),
+        });
+
+        return {
+          sent: response.ok,
+          messageId: response.headers.get('X-Message-Id'),
+        };
+      },
+    }),
+  },
+});
+
+await agent.execute("Fill out the contact form and send me a confirmation email at [email protected]");
+```
+</CodeGroup>
+
+### Custom Tools vs MCP Integrations
+
+| Custom Tools                           | MCP Integrations                        |
+|----------------------------------------|-----------------------------------------|
+| Defined inline with your code          | Connect to external services            |
+| Direct function execution              | Standard protocol                       |
+| Better performance & optimized context | Reusable across applications            |
+| Type-safe with TypeScript              | Access to pre-built integrations        |
+| Granular control                       | Network-based communication             |
+
+<Tip>
+Use custom tools when you need specific functionality within your application. Use MCP integrations when connecting to external services or when you need standardized cross-application tools.
+</Tip>
+
 ## MCP Integrations
 
 Agents can be enhanced with external tools and services through MCP (Model Context Protocol) integrations. This allows your agent to access external APIs and data sources beyond just browser interactions.
@@ -188,12 +321,12 @@ await agent.execute("Search for restaurants and save the first result to the dat
 MCP integrations enable agents to be more powerful by combining browser automation with external APIs, databases, and services. The agent can intelligently decide when to use browser actions versus external tools.
 </Tip>
 
+## Agent Execution Configuration
+
 <Warning>
-Stagehand uses a 1288x711 viewport by default (the optimal size for Computer Use Agents). Other viewport sizes may reduce performance. If you need to modify the viewport, you can edit in the [Browser Configuration](/v3/configuration/browser).
+Stagehand uses a 1288x711 viewport by default. Other viewport sizes may reduce performance. If you need to modify the viewport, you can edit in the [Browser Configuration](/v3/configuration/browser).
 </Warning>
 
-## Agent Execution Configuration
-
 Control the maximum number of steps the agent can take to complete the task using the `maxSteps` parameter.
 
 <CodeGroup>