Skip to main content
The agentic_selector method attempts to perform actions on web elements using traditional CSS selectors first. If the selectors don’t produce a unique element, it falls back to using the Operator agent to perform the action intelligently.
This method combines the speed of traditional selectors with the reliability of AI agents. Use it when you want fast, precise element targeting with intelligent fallback for dynamic pages.

​
Method Signature

async def agentic_selector(
    self,
    *,
    action: AgenticSelectorAction,
    selectors: AgenticSelectors,
    fallback_operator_query: str,
    timeout: int | None = 300,
) -> AgenticSelectorResponse

​
Parameters

​
action
AgenticSelectorAction
required
The action to perform on the element. Supported actions:
{"type": "click"}                                        # Click the element
{"type": "right_click"}                                  # Right-click the element
{"type": "double_click"}                                 # Double-click the element
{"type": "hover"}                                        # Hover over the element
{"type": "fill", "value": "text to enter"}               # Fill input with text
{"type": "select_option_by_index", "value": 0}           # Select dropdown option by index
{"type": "select_option_by_value", "value": "option_1"}  # Select dropdown option by value
{"type": "get_text"}                                     # Get the element's text content
{"type": "get_property", "property_name": "href"}        # Get an element property
​
selectors
AgenticSelectors
required
CSS selectors to identify the target element. Available selector types:
{
    "id": "element-id",
    "data_testid": "test-id",
    "name": "input-name",
    "aria_label": "Button label",
    "role": "button",
    "type": "submit",
    "text_content": "Click me",
    "tag_name": "button",
    "class_name": "btn-primary",
    "dom_path": "html > body > div > button",
    "xpath": "//button[@id='submit']"
}
​
fallback_operator_query
str
required
Natural language instruction for the Operator agent to use if selectors fail to find a unique element.
fallback_operator_query='click on "Images" near the top of the page'
fallback_operator_query='fill in the email field with test@example.com'
​
timeout
int | None
default:"300"
Maximum time in seconds to wait for the operation to complete. Default is 300 seconds since the Operator agent may need extra time when falling back.
timeout=60     # Wait up to 60 seconds
timeout=None   # Use default timeout (300 seconds)

​
Return Value

Returns an AgenticSelectorResponse object:
  • For get_text and get_property actions: response.value contains the extracted string.
  • For all other actions (click, fill, hover, etc.): response.value is None. The method completes when the action has been performed successfully.
# Extract text from an element
response = await window.agentic_selector(
    action={"type": "get_text"},
    selectors={"data_testid": "price-display"},
    fallback_operator_query="get the price text from the product card"
)
print(f"Price: {response.value}")  # e.g., "$29.99"

​
Example

import asyncio
from narada import Narada

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        # Navigate to Google
        await window.go_to_url(url="https://www.google.com")

        # Try to click using aria-label, fall back to Operator if needed
        await window.agentic_selector(
            action={"type": "click"},
            selectors={"aria_label": "Search for Images "},
            fallback_operator_query='click on "Images" near the top of the page'
        )

        # Fill a search box
        await window.agentic_selector(
            action={"type": "fill", "value": "python programming"},
            selectors={"name": "q"},
            fallback_operator_query='type "python programming" in the search box'
        )

if __name__ == "__main__":
    asyncio.run(main())