agentic_selector

Perform actions on web elements using CSS selectors with Operator agent fallback

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 [e-mail]'

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 agent.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 Agent, BrowserEnvironment

async def main():
    env = BrowserEnvironment()
    agent = Agent(environment=env)

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

        # Try to click using aria-label, fall back to Operator if needed
        await agent.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 agent.agentic_selector(
            action={"type": "fill", "value": "python programming"},
            selectors={"name": "q"},
            fallback_operator_query='type "python programming" in the search box'
        )
    finally:
        await env.close()

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