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 = 60,
) -> None

​
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": "fill", "value": "text to enter"}     # Fill input with text
{"type": "select_option_by_index", "index": 0} # Select dropdown option by index
​
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"
}
​
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:"60"
Maximum time in seconds to wait for the operation to complete. Default is 60 seconds since the Operator agent may need extra time.
timeout=30     # Wait up to 30 seconds
timeout=None   # Use default timeout (60 seconds)

​
Return Value

This method returns None and completes when the action has been performed successfully.

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