MCP Browser Agent

Instructions

Implementation Reference

• browser-use.py:210-299 (handler)

  The execute_actions tool handler, registered via @mcp.tool(). Validates the actions input dictionary, converts actions to models using Controller.registry, executes them sequentially with DOM change detection to prevent stale selectors, and returns execution results or errors.
  @mcp.tool() async def execute_actions(actions: Dict[str, Any], ctx: Context) -> str: """Execute actions from the planner state. Args: actions: A dictionary containing the planner state and actions in format: { "current_state": { "evaluation_previous_goal": str, "memory": str, "next_goal": str }, "action": [ {"action_name": {"param1": "value1"}}, ... ] } Note: If the page state changes (new elements appear) during action execution, the sequence will be interrupted and you'll need to get a new planner state. """ browser_context = await browser_initialized_check() controller = ctx.request_context.lifespan_context["controller"] try: # Validate input format if not isinstance(actions, dict) or "action" not in actions: return "Error: Actions must be a dictionary containing 'action' list" action_list = actions["action"] if not action_list: return "No actions to execute" # Get initial state for DOM change detection initial_state = await browser_context.get_state() initial_path_hashes = set(e.hash.branch_path_hash for e in initial_state.selector_map.values()) # Convert system prompt action format to action models action_models = [] for action_dict in action_list: if not isinstance(action_dict, dict) or len(action_dict) != 1: return "Error: Each action must be a dictionary with exactly one key-value pair" action_name = list(action_dict.keys())[0] params = action_dict[action_name] # Create action model using the controller's registry action_model = controller.registry.create_action_model()(**{action_name: params}) action_models.append(action_model) # Execute actions one by one to check for DOM changes results = [] for i, action_model in enumerate(action_models): # Execute single action result = await controller.act(action_model, browser_context) results.append(result) # Check if this action requires element interaction requires_elements = any(param in str(action_model) for param in ["index", "xpath"]) # If not the last action and next action might need elements, check for DOM changes if i < len(action_models) - 1: new_state = await browser_context.get_state() new_path_hashes = set(e.hash.branch_path_hash for e in new_state.selector_map.values()) # If DOM changed and next action needs elements, break sequence if requires_elements and not new_path_hashes.issubset(initial_path_hashes): msg = f"Page state changed after action {i + 1}/{len(action_models)}. Please get new planner state before continuing." logger.info(msg) results.append(ActionResult(extracted_content=msg, include_in_memory=True)) break # Stop if there was an error if result.error: break # Process results output = [] for result in results: if result.extracted_content: output.append(result.extracted_content) elif result.error: output.append(f"Error: {result.error}") else: output.append("Action executed successfully") return "\n".join(output) except Exception as e: logger.error(f"Error executing actions: {str(e)}") return f"Error executing actions: {str(e)}"
• browser-use.py:212-230 (schema)

  Docstring defining the expected input schema for the actions parameter, including structure for current_state and action list.
  """Execute actions from the planner state. Args: actions: A dictionary containing the planner state and actions in format: { "current_state": { "evaluation_previous_goal": str, "memory": str, "next_goal": str }, "action": [ {"action_name": {"param1": "value1"}}, ... ] } Note: If the page state changes (new elements appear) during action execution, the sequence will be interrupted and you'll need to get a new planner state. """
• browser-use.py:210-210 (registration)

  MCP tool registration decorator for execute_actions.
  @mcp.tool()