Skip to main content
A CAPTCHA on the page doesn’t mean your agent needs a human. Browserbase may already be solving it. If the agent clicks the challenge, reloads, or navigates away, it can interrupt that solve. Listen for Browserbase’s CAPTCHA solving events, wait while the solver is working, and check the page before deciding whether to continue or escalate.

​
Let Browserbase finish before continuing

Browserbase sends messages to the browser console as it works on a CAPTCHA. Your application can use those messages to tell whether the solver is working, has finished, or hit an error. When solving starts, let Browserbase work without clicking, typing, reloading, or navigating away. Wait before asking a human to take over, too. For example, if your agent encounters a challenge during checkout, it should give the solver time to finish before asking someone to click the challenge. When solving finishes, check that you can actually continue the task. Look for something concrete: the account dashboard after login, or the order confirmation after checkout. The solver finishing does not necessarily mean the site has granted access. If no challenge appears and the expected page is ready, continue normally. CAPTCHA solving can take up to 30 seconds depending on the challenge. Set an overall wait limit that allows time for the solve and the site’s response. Keep it within your browser tool and session timeouts, and don’t restart it each time another challenge appears.

​
Listen for solver events

Register a console listener before the first navigation or action that could trigger a challenge. Keep listening throughout the task, including after clicks and form submissions. Track each page separately and attach listeners to new tabs before driving them. If you build your own agent loop, put this behavior in the browser tool so the agent cannot skip the wait:
  1. Subscribe to events before driving the page. Remember the latest solver status, including events that arrive before the tool starts waiting.
  2. Before issuing an action, wait for any active solve to settle within your wait limit.
  3. Execute one browser action. If it triggers a solve, wait before returning control to the agent for another action or handoff decision.
  4. Check for the page or element you need while continuing to listen. If another challenge starts, wait again within the original time limit.
  5. Tell the agent whether the page is ready or why the wait failed. Remove listeners when the page or task is finished.
See the Playwright and Selenium event examples for subscribing to the console. Those examples show event collection; your application must implement the waiting and readiness checks above. With Selenium, poll logs throughout the wait rather than reading them only once.

​
Know when to ask for help

Recheck the page after solving finishes and allow time for the page or element you need to load, within your overall wait limit. An errored event ends an attempt, but the site may trigger another challenge. Keep the listener attached and watch for a new started event while checking the page, within the original overall wait limit. If another solve starts, keep waiting without restarting that deadline. Ask for human help only when no solve is active and the page remains blocked after you have waited for the expected page or element. If the overall deadline expires while a solve is active, return a timeout with that state to your application instead of handing control to a human. If the result of a submission is uncertain, inspect it before retrying. Include the session ID, affected page, last solver event and its timestamp, and what you expected to see on the page. Use Session live view when your workflow needs a human to inspect the same session.

​
Give your agent matching instructions

Once your browser tool handles the wait, use a prompt to explain the behavior to your agent. The tool must listen for events and share the solver status with the agent; a prompt alone cannot do that. Printing events to your application’s terminal does not make them visible to the model.
Add this instruction alongside your task prompt.
Adapt this example to your tool names and wait limit. Its 60-second timeout is an example application budget, not a solve-time guarantee.

​
Troubleshoot missing events

  • Listener attached too late: subscribing after goto() or a click can miss a fast solve. Subscribe first.
  • Events never reach the agent: verify that your tool returns solver status or holds the action until the solve settles. A screenshot alone does not tell the agent whether Browserbase is working.
  • Wrong page or new tab: listen on the page where the challenge occurs, not only the original tab.
  • Wait is too short: check the browser tool’s timeout as well as the agent’s overall budget. A longer session timeout does not extend a shorter tool timeout.
  • Solving is disabled: confirm the session did not set browserSettings.solveCaptchas to false.
  • Unsupported or undetected challenge: no started event does not prove a listener bug. For custom image CAPTCHAs, see custom selectors. If the page stays blocked, return the session ID for investigation instead of waiting indefinitely.
If a session’s logs show browserbase-solving-finished but your agent reports that it never arrived, inspect listener timing, page selection, and event forwarding before changing the prompt or increasing the timeout.

CAPTCHA solving

Configure CAPTCHA solving and subscribe to solver events.

Session live view

Let a human inspect a session when your workflow needs help.