Add External browser (Tetra) examples

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)             |

examples/js/interact-with-external-or-existing-browser/README.md → 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
 

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)

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);

examples/python/interact_with_external_or_existing_browser/README.md → 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
 

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)

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())