Write a Function

Use defineFn from @browserbasehq/sdk-functions to register a named handler:

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";
import { z } from "zod";

defineFn(
  "extract-title",
  async (context, params) => {
    const browser = await chromium.connectOverCDP(
      context.session.connectUrl,
    );
    const page = browser.contexts()[0]!.pages()[0]!;

    await page.goto(params.url);

    return {
      sessionId: context.session.id,
      title: await page.title(),
    };
  },
  {
    parametersSchema: z.object({
      url: z.string().url(),
    }),
    sessionConfig: {
      browserSettings: {
        solveCaptchas: true,
      },
    },
  },
);

`defineFn` arguments

defineFn accepts a name, a handler, and an optional configuration object.

Name

The name identifies a Function within a Browserbase project. Each Function in an entrypoint must have a unique name. Publishing another definition with the same name creates a new version of that Function. Callers continue to use the same Function ID.

Handler

The async handler receives context and params. context.session contains:

Node.js

{
  connectUrl: string;
  id: string;
}

Use connectUrl to attach Stagehand, Playwright, or Puppeteer to the browser that Browserbase created for the invocation. Use id to inspect the session or add it to your logs. params contains the object supplied in the invoke request. The request can contain up to 64 KB of serialized JSON. The handler can return a JSON-serializable string, number, boolean, array, or object. Browserbase stores non-empty return values in the invocation’s results field. A handler that returns null or undefined completes without results.

Configuration

The optional third argument supports:

parametersSchema to validate invocation parameters with Zod.
sessionConfig to set the default browser session configuration for every invocation.

Validate parameters

Define parametersSchema with Zod:

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";
import { z } from "zod";

defineFn(
  "search",
  async (_context, params) => {
    return { query: params.query, limit: params.limit };
  },
  {
    parametersSchema: z.object({
      query: z.string().min(1),
      limit: z.number().int().min(1).max(20),
    }),
  },
);

Use a schema for every Function that accepts external input. It documents the expected shape and rejects invalid values before your browser logic uses them.

Configure the browser session

Set sessionConfig when every invocation needs the same browser settings:

Node.js

defineFn("authenticated-task", handler, {
  sessionConfig: {
    browserSettings: {
      context: {
        id: "YOUR_CONTEXT_ID",
        persist: true,
      },
    },
    proxies: true,
    timeout: 600,
  },
});

Functions support most Create a Session options. They don’t support region or keepAlive. The invocation timeout must be between 60 and 900 seconds. Callers can override supported defaults for one invocation with sessionCreateParams.

Connect a browser library

Stagehand
Playwright
Puppeteer

Connect Stagehand to the Function’s browser:

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";

defineFn("stagehand-task", async (context) => {
  const browser = await localBrowser.connect({
    cdpUrl: context.session.connectUrl,
  });
  const stagehand = await Stagehand.create({ browser });
  const page = await browser.context.activePage();

  await page.goto("https://example.com");
  await stagehand.act("Click the More information link");

  return { url: page.url() };
});

Connect Playwright over CDP:

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";

defineFn("playwright-task", async (context) => {
  const browser = await chromium.connectOverCDP(
    context.session.connectUrl,
  );
  const page = browser.contexts()[0]!.pages()[0]!;

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

  return { title: await page.title() };
});

Connect Puppeteer with the browser WebSocket endpoint:

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";
import puppeteer from "puppeteer-core";

defineFn("puppeteer-task", async (context) => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: context.session.connectUrl,
  });
  const page = (await browser.pages())[0]!;

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

  return { title: await page.title() };
});

A Function can also run a custom browser agent loop. Connect its browser tool to context.session.connectUrl. If you don’t need to own the model loop, use Browserbase Agents.

Publish multiple Functions

The publish command follows the entrypoint’s import graph. Each defineFn call in that graph becomes a Function. For a single file, define each Function in the entrypoint:

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";

defineFn("first-task", async () => ({ task: 1 }));
defineFn("second-task", async () => ({ task: 2 }));

For multiple files, import every file that registers a Function:

Node.js

// index.ts
import "./functions/extract-title.js";
import "./functions/take-screenshot.js";

Then deploy from the CLI.

Handle errors and logs

An unhandled error marks the invocation as failed. Catch an error only when your Function can add useful context or return a valid partial result. Use console.log, console.warn, and console.error for runtime logs. Browserbase captures this output in the invocation logs. Browserbase closes the browser session when the handler completes. You don’t need to close it in your code.

Deploy Functions

Publish from the CLI or the Playground.

Invoke a Function

Pass parameters and retrieve asynchronous results.

Functions limits

Check bundle, timeout, storage, and region constraints.

Welcome

Platform

Use cases

Optimization

Account

`defineFn` arguments

Name

Handler

Configuration

Validate parameters

Configure the browser session

Connect a browser library

Publish multiple Functions

Handle errors and logs

Deploy Functions

Invoke a Function

Functions limits

​defineFn arguments

​Name

​Handler

​Configuration

​Validate parameters

​Configure the browser session

​Connect a browser library

​Publish multiple Functions

​Handle errors and logs

Deploy Functions

Invoke a Function

Functions limits

`defineFn` arguments

Name

Handler

Configuration

Validate parameters

Configure the browser session

Connect a browser library

Publish multiple Functions

Handle errors and logs