Skip to main content

First Steps

note

Make sure to follow the Installation Instructions before proceeding.

The simplest AgentQL script could look like this:

import agentql
import time

session = agentql.start_session("https://www.google.com")

QUERY = """
{
    search_box
    search_btn
    about_link
}
"""

response = session.query(QUERY)

print(response.about_link.text_content())

response.search_box.fill("tinyfish")
response.search_btn.click(force=True)

# This is not necessary for scripts to run. It's included so that the effect of script could be seen.
time.sleep(5)

session.stop()

The above script will start a new browser session, navigate to google.com, print the text value of "About" link, input "tinyfish" into a search field and click the "Search" button. At the end, it will wait 5 seconds before closing so that we can see the effects of this script.

Let's break this script down step by step.

Step by Step Breakdown​

Step 1: Import AgentQL and Time Libraries​

import agentql
import time

Import the agentql library and time library.

Step 2: Initialize Session​

session = agentql.start_session("https://www.google.com")

Start an AgentQL session with the URL "https://www.google.com" as a starting point. Created session will be the main interface for interacting with the web page and making AgentQL queries.

tip

By default start_session method creates and configures a default web interaction driver (we call it WebDriver) - PlaywrightWebDriver. If you would like to configure the web driver yourself (to start it in headless mode, for example), you can pass the web driver instance to the start_session method:

from agentql.ext.playwright import PlaywrightWebDriverSync

driver = PlaywrightWebDriverSync(headless=True)
session = agentql.start_session(URL, web_driver=driver)

Step 3: Define AgentQL Query​

AgentQL query - is the main way to query web page elements from a given web page. It defines the elements you want to interact with or consume content from

QUERY = """
{
    search_box
    search_btn
    about_link
}
"""

In this query, we specify three elements we want to interact with on "https://www.google.com":

  • search_box - search input field
  • search_btn - a button that would represent "Search" functionality
  • about_link - a link to the "About" page
info

To learn more about AgentQL query syntax, capabilities and best practices, check out our AgentQL Query documentation

Step 4: Execute AgentQL Query​

response = session.query(QUERY)

Session instance is used to execute the query

Step 5: Interact with Web Page​

response.search_box.fill("tinyfish")

This line uses the fill method on the search_box element found in the previous step. It inputs the text "tinyfish" into the search box. Essentially, this mimics typing "tinyfish" into Google's search box

response.search_btn.click(force=True)

Here, the click method is called on the search_btn element, simulating a click on the Google search button. The force=True argument does not wait for the element to be actionable.

info

The fill and click methods (and any other methods available for interacting with web elements) are coming from the Playwright library. Default AgentQL SDK implementation is built on top of Playwright and exposes all of its functionality. To get a full list of available methods, please refer to the Playwright documentation.

Step 6: Pause the Script Execution​

time.sleep(5)

Here, we use the time library provided by Python to pause the execution of the script for 5 seconds. Through this way, we could see the effect of this script.

info

time.sleep() is not necessary for scripts to run and will impact the performance. Feel free to remove this line in your script.

Step 7: Stop Session​

session.stop()

Finally, the stop method is called on the session object, ending the web browsing session. This is important for releasing resources and properly closing the session.