From b6205570a4115fc96bdff58d88d6a534c70b1cb7 Mon Sep 17 00:00:00 2001 From: Pasha Dudka Date: Tue, 24 Jun 2025 14:03:22 -0700 Subject: [PATCH 1/5] Add External browser (Tetra) examples --- .../README.md | 6 +- .../main.js | 0 .../interact-with-external-browser/README.md | 25 +++++++ .../js/interact-with-external-browser/main.js | 57 ++++++++++++++++ .../README.md | 10 +-- .../main.py | 0 .../interact_with_external_browser/README.md | 25 +++++++ .../interact_with_external_browser/main.py | 67 +++++++++++++++++++ 8 files changed, 182 insertions(+), 8 deletions(-) rename examples/js/{interact-with-external-or-existing-browser => interact-with-existing-browser}/README.md (88%) rename examples/js/{interact-with-external-or-existing-browser => interact-with-existing-browser}/main.js (100%) create mode 100644 examples/js/interact-with-external-browser/README.md create mode 100644 examples/js/interact-with-external-browser/main.js rename examples/python/{interact_with_external_or_existing_browser => interact_with_existing_browser}/README.md (84%) rename examples/python/{interact_with_external_or_existing_browser => interact_with_existing_browser}/main.py (100%) create mode 100644 examples/python/interact_with_external_browser/README.md create mode 100644 examples/python/interact_with_external_browser/main.py diff --git a/examples/js/interact-with-external-or-existing-browser/README.md b/examples/js/interact-with-existing-browser/README.md similarity index 88% rename from examples/js/interact-with-external-or-existing-browser/README.md rename to examples/js/interact-with-existing-browser/README.md index aac19a21..812e6af7 100644 --- a/examples/js/interact-with-external-or-existing-browser/README.md +++ b/examples/js/interact-with-existing-browser/README.md @@ -1,12 +1,12 @@ --- title: Use AgentQL with an already open browser 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: interact with existing browser -This is an example shows how to interact with external or existing browser by retrieving and interacting with web elements in AgentQL. +This is an 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/interact-with-existing-browser/main.js similarity index 100% rename from examples/js/interact-with-external-or-existing-browser/main.js rename to examples/js/interact-with-existing-browser/main.js diff --git a/examples/js/interact-with-external-browser/README.md b/examples/js/interact-with-external-browser/README.md new file mode 100644 index 00000000..05c5b71e --- /dev/null +++ b/examples/js/interact-with-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: interact with an external AgentQL Chrome Browser (Tetra) + +This example demonstrates how to interact with an external AgentQL Chrome Browser (Tetra). + +## 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/interact-with-external-browser/main.js b/examples/js/interact-with-external-browser/main.js new file mode 100644 index 00000000..a02e2c7e --- /dev/null +++ b/examples/js/interact-with-external-browser/main.js @@ -0,0 +1,57 @@ +/** + * This example demonstrates how to interact with an external browser with AgentQL. + */ +import { UserAgentPreset, createBrowserSession, wrap } from 'agentql'; +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/interact_with_existing_browser/README.md similarity index 84% rename from examples/python/interact_with_external_or_existing_browser/README.md rename to examples/python/interact_with_existing_browser/README.md index 80f0aa7e..3bd2adbc 100644 --- a/examples/python/interact_with_external_or_existing_browser/README.md +++ b/examples/python/interact_with_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: Interact with an existing browser +description: Interact with an existing browser with AgentQL. +updated: 2025-06-24 --- -# Example script: interact with an external or existing browser with AgentQL +# Example script: interact with an existing browser with AgentQL -This example demonstrates how to interact with an external or existing browser with AgentQL. +This example demonstrates how to interact with an existing browser with AgentQL. ## Run the script diff --git a/examples/python/interact_with_external_or_existing_browser/main.py b/examples/python/interact_with_existing_browser/main.py similarity index 100% rename from examples/python/interact_with_external_or_existing_browser/main.py rename to examples/python/interact_with_existing_browser/main.py diff --git a/examples/python/interact_with_external_browser/README.md b/examples/python/interact_with_external_browser/README.md new file mode 100644 index 00000000..6a85d67d --- /dev/null +++ b/examples/python/interact_with_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: interact with an external AgentQL Chrome Browser (Tetra) + +This example demonstrates how to interact with an external AgentQL Chrome Browser (Tetra). + +## 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/interact_with_external_browser/main.py b/examples/python/interact_with_external_browser/main.py new file mode 100644 index 00000000..ad27bf50 --- /dev/null +++ b/examples/python/interact_with_external_browser/main.py @@ -0,0 +1,67 @@ +"""This example demonstrates how to interact with an external browser with AgentQL.""" + +import os + +import agentql +import httpx +from playwright.sync_api import sync_playwright + +URL = "https://scrapeme.live/shop" + +SEARCH_QUERY = """ +{ + search_products_box +} +""" + +STOCK_QUERY = """ +{ + number_in_stock +} +""" + +AGENTQL_API_KEY = os.getenv("AGENTQL_API_KEY") + + +def get_remote_browser_url(): + """This function allocates a new browser instance.""" + with httpx.Client() as client: + response = client.post( + "https://api.agentql.com/tetra/sessions", + headers={"X-API-Key": AGENTQL_API_KEY}, + ) + response.raise_for_status() + session = response.json() + cdp_url = session["cdp_url"] + print(f"Remote browser URL: {cdp_url}") + return cdp_url + + +def run_in_external_browser(): + """This function demonstrates how to open and interact with a new page using remote browser.""" + browser_url = get_remote_browser_url() + with sync_playwright() as p: + # Connect to the browser via Chrome DevTools Protocol + browser = 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 = browser.new_page() + page = agentql.wrap(page) + + page.goto(URL) + + # Use query_elements() method to locate the search product box from the page + response = page.query_elements(SEARCH_QUERY) + + # Use Playwright's API to fill the search box and press Enter + response.search_products_box.type("Charmander") + page.keyboard.press("Enter") + + # Use query_data() method to fetch the stock number from the page + response = page.query_data(STOCK_QUERY) + + print(response) + + +if __name__ == "__main__": + run_in_external_browser() From fe6b2f3620dc9bb503886b3d6c7b209f7902de93 Mon Sep 17 00:00:00 2001 From: Pasha Dudka Date: Tue, 24 Jun 2025 14:06:15 -0700 Subject: [PATCH 2/5] Rename --- .../README.md | 6 +++--- .../main.js | 0 .../README.md | 4 ++-- .../main.js | 0 .../README.md | 8 ++++---- .../main.py | 0 .../README.md | 6 +++--- .../main.py | 0 8 files changed, 12 insertions(+), 12 deletions(-) rename examples/js/{interact-with-existing-browser => use-existing-browser}/README.md (88%) rename examples/js/{interact-with-existing-browser => use-existing-browser}/main.js (100%) rename examples/js/{interact-with-external-browser => use-external-browser}/README.md (82%) rename examples/js/{interact-with-external-browser => use-external-browser}/main.js (100%) rename examples/python/{interact_with_existing_browser => use_existing_browser}/README.md (86%) rename examples/python/{interact_with_existing_browser => use_existing_browser}/main.py (100%) rename examples/python/{interact_with_external_browser => use_external_browser}/README.md (76%) rename examples/python/{interact_with_external_browser => use_external_browser}/main.py (100%) diff --git a/examples/js/interact-with-existing-browser/README.md b/examples/js/use-existing-browser/README.md similarity index 88% rename from examples/js/interact-with-existing-browser/README.md rename to examples/js/use-existing-browser/README.md index 812e6af7..073d80d4 100644 --- a/examples/js/interact-with-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-06-24 --- -# Example script: interact with existing browser +# Example script: Use existing browser with AgentQL -This is an example shows how to interact with 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-existing-browser/main.js b/examples/js/use-existing-browser/main.js similarity index 100% rename from examples/js/interact-with-existing-browser/main.js rename to examples/js/use-existing-browser/main.js diff --git a/examples/js/interact-with-external-browser/README.md b/examples/js/use-external-browser/README.md similarity index 82% rename from examples/js/interact-with-external-browser/README.md rename to examples/js/use-external-browser/README.md index 05c5b71e..3c02a090 100644 --- a/examples/js/interact-with-external-browser/README.md +++ b/examples/js/use-external-browser/README.md @@ -4,9 +4,9 @@ description: Browser is hosted remotely - you connect to it over CDP. updated: 2025-06-24 --- -# Example script: interact with an external AgentQL Chrome Browser (Tetra) +# Example script: Use external browser with AgentQL -This example demonstrates how to interact with an external AgentQL Chrome Browser (Tetra). +This example demonstrates how to use external browser with AgentQL. ## Run the script diff --git a/examples/js/interact-with-external-browser/main.js b/examples/js/use-external-browser/main.js similarity index 100% rename from examples/js/interact-with-external-browser/main.js rename to examples/js/use-external-browser/main.js diff --git a/examples/python/interact_with_existing_browser/README.md b/examples/python/use_existing_browser/README.md similarity index 86% rename from examples/python/interact_with_existing_browser/README.md rename to examples/python/use_existing_browser/README.md index 3bd2adbc..49ba2eaa 100644 --- a/examples/python/interact_with_existing_browser/README.md +++ b/examples/python/use_existing_browser/README.md @@ -1,12 +1,12 @@ --- -title: Interact with an existing browser -description: Interact with an existing browser with AgentQL. +title: Use existing browser with AgentQL +description: Use existing browser with AgentQL. updated: 2025-06-24 --- -# Example script: interact with an existing browser with AgentQL +# Example script: Use existing browser with AgentQL -This example demonstrates how to interact with an existing browser with AgentQL. +This example demonstrates how to use existing browser with AgentQL. ## Run the script diff --git a/examples/python/interact_with_existing_browser/main.py b/examples/python/use_existing_browser/main.py similarity index 100% rename from examples/python/interact_with_existing_browser/main.py rename to examples/python/use_existing_browser/main.py diff --git a/examples/python/interact_with_external_browser/README.md b/examples/python/use_external_browser/README.md similarity index 76% rename from examples/python/interact_with_external_browser/README.md rename to examples/python/use_external_browser/README.md index 6a85d67d..c43ea1d7 100644 --- a/examples/python/interact_with_external_browser/README.md +++ b/examples/python/use_external_browser/README.md @@ -1,12 +1,12 @@ --- -title: Use external browser for AgentQL queries +title: Use external browser with AgentQL description: Browser is hosted remotely - you connect to it over CDP. updated: 2025-06-24 --- -# Example script: interact with an external AgentQL Chrome Browser (Tetra) +# Example script: Use external browser with AgentQL -This example demonstrates how to interact with an external AgentQL Chrome Browser (Tetra). +This example demonstrates how to use external browser with AgentQL. ## Run the script diff --git a/examples/python/interact_with_external_browser/main.py b/examples/python/use_external_browser/main.py similarity index 100% rename from examples/python/interact_with_external_browser/main.py rename to examples/python/use_external_browser/main.py From 0a975e66c478460562e55ac3d5aa2560996a4f96 Mon Sep 17 00:00:00 2001 From: Pasha Dudka Date: Tue, 24 Jun 2025 15:00:13 -0700 Subject: [PATCH 3/5] Fix example --- examples/python/use_external_browser/main.py | 52 +++++++++----------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/examples/python/use_external_browser/main.py b/examples/python/use_external_browser/main.py index ad27bf50..dfb06291 100644 --- a/examples/python/use_external_browser/main.py +++ b/examples/python/use_external_browser/main.py @@ -1,10 +1,10 @@ """This example demonstrates how to interact with an external browser with AgentQL.""" -import os +import asyncio import agentql -import httpx -from playwright.sync_api import sync_playwright +from agentql.tools.async_api import BrowserSession, UserAgentPreset, create_browser_session +from playwright.async_api import async_playwright URL = "https://scrapeme.live/shop" @@ -20,48 +20,42 @@ } """ -AGENTQL_API_KEY = os.getenv("AGENTQL_API_KEY") +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 -def get_remote_browser_url(): - """This function allocates a new browser instance.""" - with httpx.Client() as client: - response = client.post( - "https://api.agentql.com/tetra/sessions", - headers={"X-API-Key": AGENTQL_API_KEY}, - ) - response.raise_for_status() - session = response.json() - cdp_url = session["cdp_url"] - print(f"Remote browser URL: {cdp_url}") - return cdp_url - -def run_in_external_browser(): +async def run_in_external_browser(): """This function demonstrates how to open and interact with a new page using remote browser.""" - browser_url = get_remote_browser_url() - with sync_playwright() as p: + browser_url = await get_remote_browser_url() + async with async_playwright() as p: # Connect to the browser via Chrome DevTools Protocol - browser = p.chromium.connect_over_cdp(browser_url) + 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 = browser.new_page() - page = agentql.wrap(page) + page = await browser.new_page() + page = await agentql.wrap_async(page) - page.goto(URL) + await page.goto(URL) # Use query_elements() method to locate the search product box from the page - response = page.query_elements(SEARCH_QUERY) + response = await page.query_elements(SEARCH_QUERY) # Use Playwright's API to fill the search box and press Enter - response.search_products_box.type("Charmander") - page.keyboard.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 = page.query_data(STOCK_QUERY) + response = await page.query_data(STOCK_QUERY) print(response) if __name__ == "__main__": - run_in_external_browser() + asyncio.run(run_in_external_browser()) From 1d00790c5e7e96ae908a2d3741d8b2d4e4c61627 Mon Sep 17 00:00:00 2001 From: Pasha Dudka Date: Tue, 24 Jun 2025 15:01:50 -0700 Subject: [PATCH 4/5] Fix README --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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) | From a355976324e3035d7ef107884c301546af94d058 Mon Sep 17 00:00:00 2001 From: Pasha Dudka Date: Tue, 24 Jun 2025 15:59:03 -0700 Subject: [PATCH 5/5] Fix js example --- examples/js/use-external-browser/main.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/js/use-external-browser/main.js b/examples/js/use-external-browser/main.js index a02e2c7e..0128919f 100644 --- a/examples/js/use-external-browser/main.js +++ b/examples/js/use-external-browser/main.js @@ -1,7 +1,8 @@ /** * This example demonstrates how to interact with an external browser with AgentQL. */ -import { UserAgentPreset, createBrowserSession, wrap } from 'agentql'; +import { wrap } from 'agentql'; +import { UserAgentPreset, createBrowserSession } from 'agentql/tools'; import { chromium } from 'playwright'; const URL = 'https://scrapeme.live/shop';