multi_browserbase_stagehand_act_session

Execute specific web page actions like clicking buttons or typing text within a browser session for automation tasks.

Instructions

Performs an action on a web page element. Act actions should be as atomic and specific as possible, i.e. "Click the sign in button" or "Type 'hello' into the search input". AVOID actions that are more than one step, i.e. "Order me pizza" or "Send an email to Paul asking him to call me". (for a specific session)

Input Schema

TableJSON Schema

Name	Required	Description
`sessionId`	Yes	The session ID to use
`action`	Yes	The action to perform. Should be as atomic and specific as possible, i.e. 'Click the sign in button' or 'Type 'hello' into the search input'. AVOID actions that are more than one step, i.e. 'Order me pizza' or 'Send an email to Paul asking him to call me'. The instruction should be just as specific as possible, and have a strong correlation to the text on the page. If unsure, use observe before using act.
`variables`	No	Variables used in the action template. ONLY use variables if you're dealing with sensitive data or dynamic content. For example, if you're logging in to a website, you can use a variable for the password. When using variables, you MUST have the variable key in the action template. For example: {"action": "Fill in the password", "variables": {"password": "123456"}}

Implementation Reference

src/tools/multiSession.ts:56-78 (handler)

Core handler logic for the multi_browserbase_stagehand_act_session tool. Wraps the original act tool handler with session ID resolution, session retrieval, and context overriding to target the specific browser session.

handle: async (
  context: Context,
  params: z.infer<typeof newInputSchema>,
): Promise<ToolResult> => {
  const { sessionId, ...originalParams } = params;

  // Get the session
  const session = stagehandStore.get(sessionId);
  if (!session) {
    throw new Error(`Session ${sessionId} not found`);
  }

  // Create a temporary context that points to the specific session
  const sessionContext = Object.create(context);
  sessionContext.currentSessionId =
    session.metadata?.bbSessionId || sessionId;
  sessionContext.getStagehand = async () => session.stagehand;
  sessionContext.getActivePage = async () => session.page;
  sessionContext.getActiveBrowser = async () => session.browser;

  // Call the original tool's handler with the session-specific context
  return originalTool.handle(sessionContext, originalParams);
},

src/tools/multiSession.ts:248-251 (registration)
Registers the multi_browserbase_stagehand_act_session tool by creating a session-aware wrapper around the base actTool, setting the exact tool name via prefixes/suffixes.
```
export const actWithSessionTool = createMultiSessionAwareTool(actTool, {
  namePrefix: "multi_",
  nameSuffix: "_session",
});
```

src/tools/act.ts:38-69 (handler)

Base handler for the act tool, delegated to by the multi-session wrapper. Executes the Stagehand page.act() method to perform the specified action on the page.

async function handleAct(
  context: Context,
  params: ActInput,
): Promise<ToolResult> {
  const action = async (): Promise<ToolActionResult> => {
    try {
      const stagehand = await context.getStagehand();

      await stagehand.page.act({
        action: params.action,
        variables: params.variables,
      });

      return {
        content: [
          {
            type: "text",
            text: `Action performed: ${params.action}`,
          },
        ],
      };
    } catch (error) {
      const errorMsg = error instanceof Error ? error.message : String(error);
      throw new Error(`Failed to perform action: ${errorMsg}`);
    }
  };

  return {
    action,
    waitForNetwork: false,
  };
}

src/tools/act.ts:6-24 (schema)

Input schema definition for the act action, which is extended by the multi-session tool schema with an additional sessionId field.

const ActInputSchema = z.object({
  action: z
    .string()
    .describe(
      "The action to perform. Should be as atomic and specific as possible, " +
        "i.e. 'Click the sign in button' or 'Type 'hello' into the search input'. AVOID actions that are more than one " +
        "step, i.e. 'Order me pizza' or 'Send an email to Paul asking him to call me'. The instruction should be just as specific as possible, " +
        "and have a strong correlation to the text on the page. If unsure, use observe before using act.",
    ),
  variables: z
    .object({})
    .optional()
    .describe(
      "Variables used in the action template. ONLY use variables if you're dealing " +
        "with sensitive data or dynamic content. For example, if you're logging in to a website, " +
        "you can use a variable for the password. When using variables, you MUST have the variable " +
        'key in the action template. For example: {"action": "Fill in the password", "variables": {"password": "123456"}}',
    ),
});

src/tools/index.ts:30-40 (registration)

Includes the multi_browserbase_stagehand_act_session (as actWithSessionTool) in the array of multi-session tools, likely used for MCP tool registration.

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

Browserbase MCP Server