DebugManager

AgentQL DebugManager provides a debug mode that helps users to debug AgentQL scripts. It is implemented as a context manager that wraps around AgentQL scripts. It will generate useful debug information locally either upon a crash or when exiting the context.

The following example shows how to use DebugManager to debug the script when it crashes:

agentql_debug_example.py
python
import agentql
from agentql.sync_api import DebugManager 
from playwright.sync_api import sync_playwright

URL = "https://scrapeme.live/shop/"

QUERY = """
{
    search_products_box
}
"""

# The first context manager below will enable debug mode for the script.
with DebugManager.debug_mode(), sync_playwright() as p, p.chromium.launch(  
    headless=False
) as browser:
    page = agentql.wrap(browser.new_page())

    page.goto(URL)

    response = page.query_elements(QUERY)

    # Buggy code that will crash the script. When it crashes, the debug manager will save debug files to designated directory (`$HOME/.agentql/debug` by default).
    response.search.type("ivysaur")

Debug Information

Once a crash happens or the script exits the context of DebugManager, DebugManager will save the following information to the debug folder specified during setup process or through AGENTQL_DEBUG_PATH environment variable (default path is $HOME/.agentql/debug):

  • A log of each action taken by AgentQL SDK.
  • Error information (if the script crashes).
  • A screenshot of each page on which a query action is performed.
  • The Accessibility Tree of the last page before the crash or the end of script.
  • Meta information (OS, Python version, AgentQL version)
  • A request ID for every query_elements(), query_data() or get_by_prompt() call

Methods

debug_mode

Creates a context manager that enable debugging features automatically during its scope. Upon exit, it will save the information as detailed in the Debug Information section above.

Usage

agentql_example.py
python
with DebugManager.debug_mode(), sync_playwright() as playwright, playwright.chromium.launch(
    headless=False
) as browser:
    page = agentql.wrap(browser.new_page())

get_last_trail

note

This method should be invoked outside of the scope of debug_mode().

Returns the log that contains each action taken by AgentQL SDK.

Usage

agentql_example.py
python
with DebugManager.debug_mode(), sync_playwright() as playwright, playwright.chromium.launch(
    headless=False
) as browser:
    page = agentql.wrap(browser.new_page())
    # Other codes

print(DebugManager.get_last_trail())

Returns

TrailLogger: A custom logging class used by the AgentQL SDK. This logger can be converted directly to a string or outputted to a console for detailed review of actions taken during the session.