multi_browserbase_stagehand_session_create

Instructions

Implementation Reference

• src/tools/multiSession.ts:103-145 (handler)

  The handler function that implements the core logic: creates a new Stagehand session with optional name and existing Browserbase session ID, retrieves the debug URL using Browserbase SDK, and returns session creation confirmation with URLs.

  handle: async (
    context: Context,
    { name, browserbaseSessionID },
  ): Promise<ToolResult> => {
    try {
      const params: CreateSessionParams = {
        browserbaseSessionID,
        meta: name ? { name } : undefined,
      };
  
      const session = await stagehandStore.create(context.config, params);
  
      const bbSessionId = session.metadata?.bbSessionId;
      if (!bbSessionId) {
        throw new Error("No Browserbase session ID available");
      }
  
      // Get the debug URL using Browserbase SDK
      const bb = new Browserbase({
        apiKey: context.config.browserbaseApiKey,
      });
      const debugUrl = (await bb.sessions.debug(bbSessionId))
        .debuggerFullscreenUrl;
  
      return {
        action: async () => ({
          content: [
            {
              type: "text",
              text: `Created session ${session.id}${name ? ` (${name})` : ""}\nBrowserbase session: ${bbSessionId}\nBrowserbase Live Session View URL: https://www.browserbase.com/sessions/${bbSessionId}\nBrowserbase Live Debugger URL: ${debugUrl}`,
            },
          ],
        }),
        waitForNetwork: false,
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      throw new Error(
        `Failed to create browser session: ${errorMessage}. Please check your Browserbase credentials and try again.`,
      );
    }
  },

• src/tools/multiSession.ts:84-102 (schema)

  Tool schema definition including name, detailed description, and Zod input schema with optional 'name' and 'browserbaseSessionID' parameters.

  schema: {
    name: "multi_browserbase_stagehand_session_create",
    description:
      "Create parallel browser session for multi-session workflows. Use this when you need multiple browser instances running simultaneously: parallel data scraping, concurrent automation, A/B testing, multiple user accounts, cross-site operations, batch processing, or any task requiring more than one browser. Creates an isolated browser session with independent cookies, authentication, and state. Always pair with session-specific tools (those ending with '_session'). Perfect for scaling automation tasks that require multiple browsers working in parallel.",
    inputSchema: z.object({
      name: z
        .string()
        .optional()
        .describe(
          "Highly recommended: Descriptive name for tracking multiple sessions (e.g. 'amazon-scraper', 'user-login-flow', 'checkout-test-1'). Makes debugging and session management much easier!",
        ),
      browserbaseSessionID: z
        .string()
        .optional()
        .describe(
          "Resume an existing Browserbase session by providing its session ID. Use this to continue work in a previously created browser session that may have been paused or disconnected.",
        ),
    }),
  },

• src/tools/index.ts:26-34 (registration)

  Includes the tool in the multiSessionTools array exported as part of the overall TOOLS for MCP registration.

  export const multiSessionTools = [
    createSessionTool,
    listSessionsTool,
    closeSessionTool,
    navigateWithSessionTool,
    actWithSessionTool,
    extractWithSessionTool,
    observeWithSessionTool,
  ];

• src/index.ts:188-218 (registration)

  Registers all tools (including this one by name) to the MCP server via server.tool() in a loop over the TOOLS array.

  const tools: MCPToolsArray = [...TOOLS];
  
  // Register each tool with the Smithery server
  tools.forEach((tool) => {
    if (tool.schema.inputSchema instanceof z.ZodObject) {
      server.tool(
        tool.schema.name,
        tool.schema.description,
        tool.schema.inputSchema.shape,
        async (params: z.infer<typeof tool.schema.inputSchema>) => {
          try {
            const result = await context.run(tool, params);
            return result;
          } catch (error) {
            const errorMessage =
              error instanceof Error ? error.message : String(error);
            process.stderr.write(
              `[Smithery Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`,
            );
            throw new Error(
              `Failed to run tool '${tool.schema.name}': ${errorMessage}`,
            );
          }
        },
      );
    } else {
      console.warn(
        `Tool "${tool.schema.name}" has an input schema that is not a ZodObject. Schema type: ${tool.schema.inputSchema.constructor.name}`,
      );
    }
  });

• src/tools/multiSession.ts:113-119 (helper)

  Uses stagehandStore.create helper to perform the actual session creation (implementation in src/stagehandStore.ts).

  const session = await stagehandStore.create(context.config, params);
  
  const bbSessionId = session.metadata?.bbSessionId;
  if (!bbSessionId) {
    throw new Error("No Browserbase session ID available");
  }