agentic_matching_selectors_finder

The agentic_matching_selectors_finder method uses a narrow Operator agent to identify every visible element that matches a prompt, then returns AgenticSelectors objects you can pass directly to agentic_selector. Use it when a workflow needs to loop over repeated controls, cards, rows, links, or accordion buttons and perform the same deterministic action on each match.

This method finds matching targets only. To click, fill, read, or hover over the returned elements, iterate through the selector objects and call agentic_selector().

Method Signature

async def agentic_matching_selectors_finder(
    self,
    *,
    prompt: str,
    timeout: int | None = 300,
) -> list[AgenticSelectors]

Parameters

prompt

str

required

Natural-language description of the visible elements to find. Include the page section or container when possible so the finder returns the intended repeated targets.

prompt='Find all visible "More details" buttons in the Highlights section'
prompt="Find all visible down-arrow expand buttons in the accordion"
prompt="Find all visible row action menus in the Open invoices table"

timeout

int | None

default:"300"

Maximum time in seconds to wait. The default is 300 seconds because this method may run an Operator agent.

Return Value

Returns a list of AgenticSelectors dictionaries. If no elements match, the method returns an empty list. Each returned selector object may include one or more selector fields:

{
    "id": "element-id",
    "data_testid": "test-id",
    "name": "input-name",
    "aria_label": "Button label",
    "role": "button",
    "type": "submit",
    "text_content": "More details",
    "tag_name": "button",
    "class_name": "btn-primary",
    "dom_path": "html > body > div > button",
    "xpath": "//button[normalize-space()='More details']"
}

Example

import asyncio
from narada import Narada

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

        await window.go_to_url(url="https://example.com/highlights")

        detail_button_selectors = await window.agentic_matching_selectors_finder(
            prompt='Find all visible "More details" buttons in the Highlights section',
        )

        print(f"Found {len(detail_button_selectors)} buttons")

        for index, selectors in enumerate(detail_button_selectors, start=1):
            await window.agentic_selector(
                action={"type": "click"},
                selectors=selectors,
                fallback_operator_query=(
                    f'Click "More details" button #{index} in the Highlights section'
                ),
            )
            await asyncio.sleep(1)

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

When to Use This vs agentic_selector

	`agentic_matching_selectors_finder`	`agentic_selector`
Purpose	Find many matching targets	Act on one target
Returns	`list[AgenticSelectors]`	`AgenticSelectorResponse`
Best for	Repeated controls or rows	Clicking, filling, reading, or hovering
Typical use	Collect once, then loop	Execute each deterministic action

Documentation Index

​Method Signature

​Parameters

​Return Value

​Example

​When to Use This vs agentic_selector

Method Signature

Parameters

Return Value

Example

When to Use This vs agentic_selector