diff --git a/README.md b/README.md index 5fa7733c..6436a04f 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,8 @@ AgentQL is a suite of tools for extracting data and automating workflows on live | Compare Product Prices | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/compare_product_prices) / [Colab](https://github.com/tinyfish-io/agentql/tree/main/examples/googlecolab/compare_product_prices) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/compare-product-prices) | | Get Element by Prompt | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/get_by_prompt) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/get-by-prompt) | | Infinite Scroll | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/infinite_scroll) / [Colab](https://github.com/tinyfish-io/agentql/tree/main/examples/googlecolab/infinite_scroll) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/infinite-scroll) | -| External Browser Integration | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/interact_with_external_or_existing_browser) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/interact-with-external-or-existing-browser) | +| Use External Browser | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/use_external_browser) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/use-external-browser) | +| Use Existing Browser | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/use_existing_browser) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/use-existing-browser) | | Query List Items | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/list_query_usage) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/list-query-usage) | | Site Login | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/log_into_sites) / [Colab](https://github.com/tinyfish-io/agentql/tree/main/examples/googlecolab/log_into_sites) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/log-into-sites) | | Headless Browser | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/python/run_script_in_headless_browser) / [Colab](https://github.com/tinyfish-io/agentql/tree/main/examples/googlecolab/run_script_in_headless_browser) | [Script](https://github.com/tinyfish-io/agentql/tree/main/examples/js/run-script-in-headless-browser) | diff --git a/examples/js/interact-with-external-or-existing-browser/README.md b/examples/js/use-existing-browser/README.md similarity index 86% rename from examples/js/interact-with-external-or-existing-browser/README.md rename to examples/js/use-existing-browser/README.md index aac19a21..073d80d4 100644 --- a/examples/js/interact-with-external-or-existing-browser/README.md +++ b/examples/js/use-existing-browser/README.md @@ -1,12 +1,12 @@ --- -title: Use AgentQL with an already open browser +title: Use existing browser with AgentQL description: If you don't want to use Playwright's default browser, you can bring your own. -updated: 2025-03-05 +updated: 2025-06-24 --- -# Example script: interact with external or existing browser +# Example script: Use existing browser with AgentQL -This is an example shows how to interact with external or existing browser by retrieving and interacting with web elements in AgentQL. +This example shows how to interact with existing browser by retrieving and interacting with web elements in AgentQL. ## Run the script diff --git a/examples/js/interact-with-external-or-existing-browser/main.js b/examples/js/use-existing-browser/main.js similarity index 100% rename from examples/js/interact-with-external-or-existing-browser/main.js rename to examples/js/use-existing-browser/main.js diff --git a/examples/js/use-external-browser/README.md b/examples/js/use-external-browser/README.md new file mode 100644 index 00000000..3c02a090 --- /dev/null +++ b/examples/js/use-external-browser/README.md @@ -0,0 +1,25 @@ +--- +title: Use external browser for AgentQL queries +description: Browser is hosted remotely - you connect to it over CDP. +updated: 2025-06-24 +--- + +# Example script: Use external browser with AgentQL + +This example demonstrates how to use external browser with AgentQL. + +## Run the script + +- [Install AgentQL SDK](https://docs.agentql.com/installation/sdk-installation) +- Save this JavaScript file locally as **main.js** +- Run the following command from the project's folder: + +```bash +node main.js +``` + +Script will take care of allocating AgentQL External Browser, connecting to it and running the AgentQL query. + +## Play with the query + +Install the [AgentQL Debugger Chrome extension](https://docs.agentql.com/installation/chrome-extension-installation) to play with the AgentQL query. [Learn more about the AgentQL query language](https://docs.agentql.com/agentql-query/query-intro) diff --git a/examples/js/use-external-browser/main.js b/examples/js/use-external-browser/main.js new file mode 100644 index 00000000..0128919f --- /dev/null +++ b/examples/js/use-external-browser/main.js @@ -0,0 +1,58 @@ +/** + * This example demonstrates how to interact with an external browser with AgentQL. + */ +import { wrap } from 'agentql'; +import { UserAgentPreset, createBrowserSession } from 'agentql/tools'; +import { chromium } from 'playwright'; + +const URL = 'https://scrapeme.live/shop'; + +const SEARCH_QUERY = ` +{ + search_products_box +} +`; + +const STOCK_QUERY = ` +{ + number_in_stock +} +`; + +async function getRemoteBrowserUrl() { + // This function creates a new browser session with Windows user agent preset + const session = await createBrowserSession(UserAgentPreset.WINDOWS); + const cdpUrl = session.cdpUrl; + console.log(`Remote browser URL: ${cdpUrl}`); + console.log(`Page streaming URL: ${session.getPageStreamingUrl(0)}`); + return cdpUrl; +} + +async function runInExternalBrowser() { + // This function demonstrates how to open and interact with a new page using remote browser + const browserUrl = await getRemoteBrowserUrl(); + + // Connect to the browser via Chrome DevTools Protocol + const browser = await chromium.connectOverCDP(browserUrl); + + // Create a new tab in the browser window and wrap it to get access to the AgentQL's querying API + const page = await browser.newPage(); + const wrappedPage = await wrap(page); + + await wrappedPage.goto(URL); + + // Use queryElements() method to locate the search product box from the page + const searchResponse = await wrappedPage.queryElements(SEARCH_QUERY); + + // Use Playwright's API to fill the search box and press Enter + await searchResponse.search_products_box.type('Charmander'); + await wrappedPage.keyboard.press('Enter'); + + // Use queryData() method to fetch the stock number from the page + const stockResponse = await wrappedPage.queryData(STOCK_QUERY); + + console.log(stockResponse); + await browser.close(); +} + +runInExternalBrowser().catch(console.error); diff --git a/examples/python/interact_with_external_or_existing_browser/README.md b/examples/python/use_existing_browser/README.md similarity index 84% rename from examples/python/interact_with_external_or_existing_browser/README.md rename to examples/python/use_existing_browser/README.md index 80f0aa7e..49ba2eaa 100644 --- a/examples/python/interact_with_external_or_existing_browser/README.md +++ b/examples/python/use_existing_browser/README.md @@ -1,12 +1,12 @@ --- -title: Interact with an external browser -description: Interact with an external or existing browser with AgentQL. -updated: 2025-03-05 +title: Use existing browser with AgentQL +description: Use existing browser with AgentQL. +updated: 2025-06-24 --- -# Example script: interact with an external or existing browser with AgentQL +# Example script: Use existing browser with AgentQL -This example demonstrates how to interact with an external or existing browser with AgentQL. +This example demonstrates how to use existing browser with AgentQL. ## Run the script diff --git a/examples/python/interact_with_external_or_existing_browser/main.py b/examples/python/use_existing_browser/main.py similarity index 100% rename from examples/python/interact_with_external_or_existing_browser/main.py rename to examples/python/use_existing_browser/main.py diff --git a/examples/python/use_external_browser/README.md b/examples/python/use_external_browser/README.md new file mode 100644 index 00000000..c43ea1d7 --- /dev/null +++ b/examples/python/use_external_browser/README.md @@ -0,0 +1,25 @@ +--- +title: Use external browser with AgentQL +description: Browser is hosted remotely - you connect to it over CDP. +updated: 2025-06-24 +--- + +# Example script: Use external browser with AgentQL + +This example demonstrates how to use external browser with AgentQL. + +## Run the script + +- [Install AgentQL SDK](https://docs.agentql.com/installation/sdk-installation) +- Save this Python file locally as **main.py** +- Run the following command from the project's folder: + +```bash +python3 main.py +``` + +Script will take care of allocating AgentQL External Browser, connecting to it and running the AgentQL query. + +## Play with the query + +Install the [AgentQL Debugger Chrome extension](https://docs.agentql.com/installation/chrome-extension-installation) to play with the AgentQL query. [Learn more about the AgentQL query language](https://docs.agentql.com/agentql-query/query-intro) diff --git a/examples/python/use_external_browser/main.py b/examples/python/use_external_browser/main.py new file mode 100644 index 00000000..dfb06291 --- /dev/null +++ b/examples/python/use_external_browser/main.py @@ -0,0 +1,61 @@ +"""This example demonstrates how to interact with an external browser with AgentQL.""" + +import asyncio + +import agentql +from agentql.tools.async_api import BrowserSession, UserAgentPreset, create_browser_session +from playwright.async_api import async_playwright + +URL = "https://scrapeme.live/shop" + +SEARCH_QUERY = """ +{ + search_products_box +} +""" + +STOCK_QUERY = """ +{ + number_in_stock +} +""" + + +async def get_remote_browser_url() -> str: + """This function creates a new browser session.""" + # Create a browser session with Windows user agent preset + session: BrowserSession = await create_browser_session(ua_preset=UserAgentPreset.WINDOWS) + cdp_url = session.cdp_url + print(f"Remote browser URL: {cdp_url}") + print(f"Page streaming URL: {session.get_page_streaming_url(0)}") + return cdp_url + + +async def run_in_external_browser(): + """This function demonstrates how to open and interact with a new page using remote browser.""" + browser_url = await get_remote_browser_url() + async with async_playwright() as p: + # Connect to the browser via Chrome DevTools Protocol + browser = await p.chromium.connect_over_cdp(browser_url) + + # Create a new tab in the browser window and wrap it to get access to the AgentQL's querying API + page = await browser.new_page() + page = await agentql.wrap_async(page) + + await page.goto(URL) + + # Use query_elements() method to locate the search product box from the page + response = await page.query_elements(SEARCH_QUERY) + + # Use Playwright's API to fill the search box and press Enter + await response.search_products_box.type("Charmander") + await page.keyboard.press("Enter") + + # Use query_data() method to fetch the stock number from the page + response = await page.query_data(STOCK_QUERY) + + print(response) + + +if __name__ == "__main__": + asyncio.run(run_in_external_browser())