Repository navigation
an agent and an iframe
An iframe is a second document inside the first, and a browser agent driving the
outer one does not automatically get the inner one. Measured on 2026-09-17
against a host page with one same-origin frame in it, served from 127.0.0.1:
| what was tried | result |
|---|---|
browser_read_text |
the frame's text is not in it |
browser_read_html |
the frame's content is not in it |
browser_snapshot |
"interactive_elements": [] - the frame's button is not listed
|
browser_click with the button's selector |
fails: '#fb' not actionable in 15s after 275 attempts
|
browser_click_at on the button's position |
works |
browser_evaluate reading contentDocument
|
works, same-origin |
The frame's title went from child to FRAME-CLICKED after the coordinate
click, which is the page's own evidence that the click landed where it was meant
to rather than on the frame's border.
Because they operate on different things. The reads and the selector work on the document the tools are pointed at, and the frame is a boundary in that document: its contents belong to another one. The pointer works on the window. There is no boundary in a screen coordinate, so a real click at a position inside the frame's rectangle is delivered to whatever the compositor has there, which is the frame's button.
That is the whole explanation, and it generalises: anything routed through the document stops at the frame, anything routed through the input devices does not. Typing and key presses behave like the pointer once focus is inside.
A browser MCP server offers a ladder: a named tool with a selector first, coordinates when no selector describes the target, the picture when the snapshot does not list the thing at all. The ordering usually reads as a preference for precision. Here it is not a preference, it is the only route.
Get the coordinates the same way you would for a canvas or a slider: take a screenshot, find the control in the picture, and click where it is. The snapshot will not help you because, as measured above, it lists nothing from inside the frame.
Clicking by selector or by coordinates has the trade in general, including the failure asymmetry that makes the first rung worth trying first everywhere else.
The selector attempt is worth dwelling on, because of how it fails. It does not say "there is no such element". It retries for fifteen seconds, 275 times, and then reports the element as not actionable.
From the outside that looks like a slow page or a flaky selector, which is the wrong diagnosis and sends you off tuning waits. A click that burns the full fifteen seconds on a page you know contains the element is a strong hint that the element is in a frame, and it is worth checking before anything else.
The general shape of the "it retried and gave up" failure is in how long the agent waits before it gives up.
Two routes, and which one you get depends on origin.
Same origin: browser_evaluate can reach contentDocument and read the
frame's DOM. Measured above. That is a read, which this browser allows; acting on
it from script is refused, for the reason in
keeping an AI browser agent out of destructive actions.
Cross origin: nothing. contentDocument is null and the browser is enforcing
the same rule it enforces for every script on the web. There is no setting on
this side that changes it, and a tool that claimed otherwise would be describing
a security hole.
For a cross-origin frame the honest options are: click by coordinates, read it out of a screenshot, or navigate the frame's URL directly in the main page and work with it as a page of its own. The third is usually the best one and is the least considered.
The practical instruction, and it costs one sentence: tell the agent the content is in a frame, and tell it to use coordinates for it. Otherwise the default behaviour is to try the selector, wait fifteen seconds, conclude the element does not exist, and go looking for another way in.
Also worth saying: consent walls, payment fields, embedded maps, video players, chat widgets and comment sections are frames more often than not. If a control you can plainly see is invisible to every read, that is the first thing to suspect.
Can an AI agent click a button inside an iframe? By coordinates, yes, measured. By selector, no: it times out after fifteen seconds without finding the element.
Why does my agent say the element does not exist when I can see it? If it is in a frame, the reads and the snapshot genuinely do not contain it. Look for a frame before you suspect the selector.
Can it read text inside a frame? From a same-origin frame, yes, through
contentDocument. From a cross-origin one, no, and that is the browser's
security model rather than a limitation of the tool.
What is the best way to handle a cross-origin frame? Often to open the frame's own URL as the main page and work with it directly. Otherwise coordinates, or a screenshot.
How do I know something is in a frame? A control that is visible on screen
and absent from browser_snapshot is the signature. A fifteen-second timeout on
a selector you are sure about is the second.
See also: what a page snapshot costs, per control, which is the other half of understanding what the snapshot does and does not contain, and shadow DOM and an AI agent, which is the mirror image of this page: a boundary the reads cannot cross and the selector can.
- Measured 2026-09-17 through this project's MCP server over stdio, against a host page with one same-origin iframe served from
127.0.0.1. The snapshot returned{"title": "host", "url": "...", "interactive_elements": []};browser_clickon the frame button's selector returned'#fb' not actionable in 15s after 275 attempts;browser_click_atat the button's screen position changed the frame document's title fromchildtoFRAME-CLICKED, read back throughcontentDocument.
The pair to hold in your head: the document stops at the frame, the pointer does not. Every line above follows from that, including the fifteen seconds.
- OpenAI Operator alternatives
- Open-source Operator-style agents
- Is OpenAI Operator still available?
- OpenAI Operator vs Claude computer use
- browser-use alternatives
- Choosing an AI browser agent
- Open-source AI browser agents
- Open-source computer-use agents
- What is an AI web agent?
- AI browser agents vs traditional scraping
- Cloud browser infrastructure for AI agents, explained
- Browserbase alternatives
- Firecrawl vs an AI browser agent
- Skyvern alternatives
- Stagehand vs browser-use
- Project Mariner is gone: what replaced it
- Manus alternatives
- Gemini computer use vs Claude computer use
- A stealth browser MCP, reviewed honestly by its own wiki
- AI browser vs AI browser agent: which one do you want?
- AI browser agent vs RPA: which one fits the job
- AI browser agent vs n8n, Zapier and Make
- Vercel agent-browser alternatives, compared honestly
- What is an agentic browser? Definition and the two kinds
- Open-source agentic browsers: the three layers, compared
- Choosing an MCP server for browser automation: four axes
- Stealth MCP servers compared: Camoufox, nodriver, Patchright
- Playwright MCP alternatives, and the three you don't need
- Autonomous browser agents: the four rungs of autonomy
- What is actually free in the AI browser agent stack
- browser-use on GitHub: what the repo actually gives you
- Playwright MCP vs Chrome DevTools MCP: different jobs
- How to choose among MCP servers: a map by category
- Which MCP servers are worth adding to Claude Code
- MCP on GitHub: finding servers and judging them fast
- MCP vs an API: the decision, and what the wrapper costs
- MCP alternatives: when the protocol is the wrong shape
- Why does my AI agent get blocked?
- The timing signal AI agents give off
- Agent retry loops trip rate limits, not fingerprints
- Claude computer use detected as a bot
- browser-use getting blocked: what you can and cannot change
- Playwright MCP session blocked: four causes, four fixes
- Playwright MCP and captchas: what actually gets you past
- Cloudflare and a browser MCP server: what is being read
- Can an AI agent solve a captcha? The honest answer
- Getting an AI agent to fill out forms
- The best model for an MCP browser agent, and what it really costs
- Browser problem or model problem?
- How to use a Playwright MCP server with Claude Code
- Extracting data to a CSV with an AI agent
- Monitoring a page for changes with an AI agent
- How to let Claude Desktop control a browser
- How to add a browser to Cursor as an MCP server
- Using an AI agent to hunt for apartments
- Getting website data into Google Sheets with an AI agent
- Using an AI agent to download invoices from portals
- AI agents for web research
- Using an AI agent to test your own website
- How to add a browser to Cline as an MCP server
- Posting to social media with an AI agent
- Posting to Facebook with an AI agent
- Posting to Instagram with an AI agent
- Posting to X with an AI agent
- Automating LinkedIn posts: read this first
- Appointment bots: what they are and what an agent can legitimately do
- Track prices across sites with an AI agent
- Build a lead list with an AI browser agent
- Run an AI browser agent on a schedule
- AI browser agent with a local LLM: what changes
- Should you log your AI agent into your accounts?
- How to write a task an AI browser agent can follow
- Move data between two web apps with an AI agent
- The MCP server
- How the tools are shaped, and why
- Playwright MCP vs the Playwright CLI: which fits when
- Playwright MCP: browser is already in use, and the fix
- Playwright MCP best practices: four decisions that matter
- Playwright MCP with a proxy, and the three leaks it leaves
- A browser MCP server in GitHub Copilot: setup and limits
- Using a browser MCP server for web scraping: the pattern
- Which LLM for browser automation: the four properties
- How to build a browser agent, and what to take instead
- Getting an AI agent to log into a website: three routes
- MCP tools, resources and prompts: who controls each
- How many MCP tools is too many? The context arithmetic
- How to build an MCP server: the decisions, not the scaffold
- Local or remote MCP server: what changes, and what does not
- Writing an MCP client in Python: the thirty-line version
- Self-hosted AI agent: what one actually costs to run
- How long an AI browser agent takes per step, measured
- Text, HTML, snapshot or screenshot: what the agent should read
- Giving an AI browser agent a stopping condition
- Keeping an AI browser agent out of destructive actions
- Why did the AI agent click the wrong thing
- When the page changes under the AI agent
- Running one AI agent task across a list of sites
- Seeing a page as it appears in another country
- Getting data out of a dashboard with no export button
- Two browsers in one session: main and support
- Finding the dead links on a site with an AI agent
- Filling a CRM record from a company's website
- One form submission per spreadsheet row, with an AI agent
- Dated screenshots of a page as evidence
- Checking order and delivery status with an AI agent
- Reading a PDF that opens inside the browser
- Summarising a long page or thread with an AI agent
- Collecting every image on a page with its caption
- Collecting event and course listings with an AI agent
- Cancelling a subscription with an AI agent
- What an AI agent can and cannot do inside an iframe
- Shadow DOM and an AI agent: you can click it, you cannot read it
- How to add a browser to Codex as an MCP server
- What a page snapshot costs, per control
- How to let Gemini CLI use a browser
- Native selects and the ones that only look like selects
- Clicking by selector or by coordinates
- How long the agent waits before it gives up
- What a second browser costs
- Uploading a file with an AI agent, and why this one cannot
- Watching the agent work, and when it is worth it
- When not to use an AI browser agent
- Agent or script: deciding once instead of every time
- Using the keyboard instead of the mouse
- Secrets in an agent task: where they end up
- What an agent run should log
- Deduplicating what an AI agent collects
- Normalising values across sites
- Validating an AI agent's output
- Reading a table with an AI agent
- Driving a site's own search and filters
- The task works headed and fails headless
- How to let the AdaL CLI use a browser