> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

## Method Signature

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

## Parameters

<ParamField query="action" type="AgenticSelectorAction" required>
  The action to perform on the element. Supported actions:

  ```python theme={null}
  {"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
  ```
</ParamField>

<ParamField query="selectors" type="AgenticSelectors" required>
  CSS selectors to identify the target element. Available selector types:

  ```python theme={null}
  {
      "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']"
  }
  ```
</ParamField>

<ParamField query="fallback_operator_query" type="str" required>
  Natural language instruction for the Operator agent to use if selectors fail to find a unique element.

  ```python theme={null}
  fallback_operator_query='click on "Images" near the top of the page'
  fallback_operator_query='fill in the email field with test@example.com'
  ```
</ParamField>

<ParamField query="timeout" type="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.

  ```python theme={null}
  timeout=60     # Wait up to 60 seconds
  timeout=None   # Use default timeout (300 seconds)
  ```
</ParamField>

## 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.

```python theme={null}
# 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

```python theme={null}
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())
```