Unstuck Docs GitHub

AI agents

AI browser agents get stuck on exactly the things Unstuck is for. Give them a way to ask a person.

For browser-use, Unstuck Browser also gives the model a check_page tool, so a check after a navigation is caught even when the model doesn't notice it.

browser-use

Give the agent an ask_human tool. When it hits a CAPTCHA, a login or a 2FA prompt it calls the tool with the reason and the URL of the page it's stuck on; Unstuck takes over that tab in the same Chrome and returns once the person is done. Start Chrome with a debugging port (see MCP for the command) and share it with browser-use through Browser(cdp_url=...).

pip install unstuck playwright browser-use
@tools.action(
    "Ask a human to take over the browser: for a CAPTCHA, a login, a 2FA code or anything you can't do. "
    "Give the reason and the URL of the page you're stuck on."
)
async def ask_human(reason: str, url: str) -> str:
    async with async_playwright() as p:
        # The same Chrome browser-use is driving; take over the tab the agent is stuck on.
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        tabs = [pg for ctx in browser.contexts for pg in ctx.pages if pg.url.startswith(("http://", "https://"))]
        matching = [pg for pg in tabs if pg.url.startswith(url) or url.startswith(pg.url)]
        if not matching:
            return f"No open tab is on {url}; check the URL and ask again."
        page = matching[-1]
        print("Taking over", page.url, flush=True)

        def on_link(link):
            print(f"\n{link.reason}. Open this link:\n{link.url}\n", flush=True)

        async with Unstuck(on_link=on_link) as unstuck:
            result = await unstuck.takeover(page, reason=reason, timeout_s=600)
    print(f"Takeover {result.status} after {result.duration_s}s", flush=True)
    return f"The human finished: {result.status}. Look at the page again before continuing."

Then pass tools=tools and browser=Browser(cdp_url=CDP_URL) to your Agent; the complete file below shows it.

Stagehand

A local Stagehand browser gives you its CDP URL. Connect Playwright to it and hand that page to Unstuck when act() can't get past something. Give Stagehand.create your model and key explicitly (model: { modelName, apiKey }): Stagehand runs the model inside its browser extension, which can't read your environment. For a Browserbase browser, connect Playwright to its connect URL instead.

npm init -y && npm pkg set type=module
npm install @velmlabs/unstuck @browserbasehq/stagehand playwright
// Stuck? Hand the same page to a person.
const unstuck = new Unstuck({
  onLink: ({ url, reason }) => console.log(`\n${reason}. Open this link:\n${url}\n`),
});
const result = await unstuck.takeover(page, { reason: 'Please solve the CAPTCHA', timeoutS: 300 });
console.log(`Takeover ${result.status} after ${result.durationS}s`);

What the person sees

They open the link and see your agent's live page: on this machine by default, or on any phone with Unstuck Cloud. They tap and type straight into it (a Keyboard button opens the phone keyboard), then tap Done. If they can't, Can't solve hands it back with a reason.

The Unstuck viewer on a phone: the agent's live page with a CAPTCHA, a zoom and scroll rail, a Help button, and Keyboard, Can't solve and Done buttons
The complete browser-use file
"""Unstuck + browser-use: give the agent an `ask_human` tool. When it hits a CAPTCHA, a login or a 2FA prompt,
it calls the tool; Unstuck sends a person a link to the same Chrome and returns once they're done.

    pip install -r requirements.txt
    # Chrome with a debugging port, shared by browser-use and Unstuck:
    google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.unstuck-chrome"
    ANTHROPIC_API_KEY=... python main.py

Add UNSTUCK_API_KEY=uk_live_... to your environment to send the link through Unstuck Cloud.
"""

import asyncio
import os
import sys

from browser_use import Agent, Browser, Tools
from playwright.async_api import async_playwright

from unstuck import Unstuck

CDP_URL = os.environ.get("CDP_URL", "http://127.0.0.1:9222")
START_URL = sys.argv[1] if len(sys.argv) > 1 else "https://www.google.com/recaptcha/api2/demo"
tools = Tools()


# region snippet
@tools.action(
    "Ask a human to take over the browser: for a CAPTCHA, a login, a 2FA code or anything you can't do. "
    "Give the reason and the URL of the page you're stuck on."
)
async def ask_human(reason: str, url: str) -> str:
    async with async_playwright() as p:
        # The same Chrome browser-use is driving; take over the tab the agent is stuck on.
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        tabs = [pg for ctx in browser.contexts for pg in ctx.pages if pg.url.startswith(("http://", "https://"))]
        matching = [pg for pg in tabs if pg.url.startswith(url) or url.startswith(pg.url)]
        if not matching:
            return f"No open tab is on {url}; check the URL and ask again."
        page = matching[-1]
        print("Taking over", page.url, flush=True)

        def on_link(link):
            print(f"\n{link.reason}. Open this link:\n{link.url}\n", flush=True)

        async with Unstuck(on_link=on_link) as unstuck:
            result = await unstuck.takeover(page, reason=reason, timeout_s=600)
    print(f"Takeover {result.status} after {result.duration_s}s", flush=True)
    return f"The human finished: {result.status}. Look at the page again before continuing."
# endregion snippet


async def main() -> None:
    if not (os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("OPENAI_API_KEY")):
        print("There is no model key, so the agent is skipped and we ask for help directly.", flush=True)
        await ask_human("Please solve the CAPTCHA", START_URL)
        return
    llm = "anthropic:claude-sonnet-5-5" if os.environ.get("ANTHROPIC_API_KEY") else "openai:gpt-5"
    agent = Agent(
        task=f"Open {START_URL} and submit the form. Ask a human for any CAPTCHA.",
        llm=llm,
        browser=Browser(cdp_url=CDP_URL),
        tools=tools,
    )
    await agent.run()


if __name__ == "__main__":
    asyncio.run(main())
The complete Stagehand file
// Unstuck + Stagehand: Stagehand drives the browser; when act() can't get past a CAPTCHA or a login,
// Unstuck hands the same browser to a person and returns once they're done.
//
//   npm init -y && npm pkg set type=module
//   npm install @velmlabs/unstuck @browserbasehq/stagehand playwright
//   ANTHROPIC_API_KEY=… npx tsx index.ts [url]
//
// CHROME_PATH picks a Chrome binary if Stagehand can't find one. Add UNSTUCK_API_KEY=uk_live_… for Unstuck Cloud.
import { Stagehand, localBrowser } from '@browserbasehq/stagehand';
import { chromium } from 'playwright';
import { Unstuck } from '@velmlabs/unstuck';

const browser = await localBrowser.launch({ executablePath: process.env.CHROME_PATH, headless: true });
// Stagehand's model runs in its browser extension, so it gets the key explicitly.
const key = process.env.ANTHROPIC_API_KEY;
const stagehand = await Stagehand.create({ browser, model: key ? { modelName: 'anthropic/claude-sonnet-5-5', apiKey: key } : undefined });

// Playwright on the same local browser, over its CDP URL: Unstuck takes a Playwright page.
// (A Browserbase browser has no CDP URL here; use its connect URL with chromium.connectOverCDP instead.)
const pw = await chromium.connectOverCDP(browser.cdpUrl!);
const context = pw.contexts()[0]!;
const page = context.pages().find((p) => p.url() !== 'about:blank') ?? (await context.newPage());
await page.goto(process.argv[2] ?? 'https://www.google.com/recaptcha/api2/demo');

if (key) {
  await stagehand.act('submit the form');
} else {
  console.log('There is no model key, so act() is skipped and we ask for help directly.');
}

// #region snippet
// Stuck? Hand the same page to a person.
const unstuck = new Unstuck({
  onLink: ({ url, reason }) => console.log(`\n${reason}. Open this link:\n${url}\n`),
});
const result = await unstuck.takeover(page, { reason: 'Please solve the CAPTCHA', timeoutS: 300 });
console.log(`Takeover ${result.status} after ${result.durationS}s`);
// #endregion snippet

await unstuck.close();
await stagehand.close();
await browser.close();
process.exit(0);