导航|地址|刷新
Human in the Loop

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/browser-run/llms.txt
Use this file to discover all available pages before exploring further.



DocsDirectoryAPISDKsChangelog

Search

Log in






Browser Run

/




Overview

Get started

Examples


Features


Live ViewBeta

Human in the LoopBeta

Session recordingBeta

WebMCPBeta

Custom fonts

Reuse sessions






Quick Actions


Overview

/content - Fetch HTML

/screenshot - Capture screenshot

/pdf - Render PDF

/markdown - Extract Markdown from a webpage

/snapshot - Capture multiple page formats

/accessibilityTree - Capture accessibility tree

/scrape - Scrape HTML elements

/json - Capture structured data using AI

/links - Retrieve links from a webpage

/crawl - Crawl web contentBeta

Reference ↗API






Chrome DevTools Protocol (CDP)Beta


Overview

Session management (HTTP)

Using with Puppeteer (CDP)

Using with Playwright (CDP)

Using with MCP clients (CDP)






Playwright


Overview

Playwright MCPBeta





Puppeteer

StagehandBeta


Tutorials


Deploy a Browser Run Worker

Generate PDFs Using HTML and CSS

Build a web crawler with Queues and Browser Run ↗

Deploy a Browser Run Worker with Durable Objects

Generate OG images for Astro sites

Pre-render pages for crawlers






Reference


Automatic request headers

Supported fonts

Quick Actions timeouts

robots.txt and sitemaps

Browser close reasons

Wrangler

Wrangler commands





FAQ

Limits

Pricing

Changelog

MCP serverMCP


Agent resources


Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Browser Run llms.txt ↗

Browser Run llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗













Home

/Browser Run

/Features

/Human in the Loop



Human in the Loop


Last updated Jul 28, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewUse casesHow it works Structured handoff (recommended) Manual detectionCloudflare CDP commands Cloudflare.handoff Cloudflare.handoffComplete event Cloudflare.getHandoffState Cloudflare.getLiveViewExample: structured handoffExample: manual detectionBest practices Provide clear instructions Set appropriate timeouts Monitor handoff state




Some browser automation workflows require manual intervention. A login page may need multi-factor authentication, a form may require sensitive credentials you do not want to pass to an automation script, or a task may be too complex to fully automate. Human in the Loop lets a human step into a live browser session through Live View to handle what automation cannot, then hand control back to the script.


Use cases


Authentication flows: Login pages with MFA, SSO, or CAPTCHA that cannot be bypassed programmatically

Sensitive data entry: Forms requiring credentials or personal information you do not want to pass to an automation script

Complex interactions: One-off tasks that are too difficult or not worth fully automating, such as configuring a dashboard or approving a workflow

Verification steps: Confirming an order, reviewing generated content, or approving an action before the script proceeds


How it works


Human in the Loop works with any Browser Session and provides two approaches for human intervention:


Structured handoff (recommended)


Your script uses Cloudflare CDP commands to formally request human intervention and wait for completion:

Your automation script encounters a scenario requiring human input.

The script subscribes to the Cloudflare.handoffComplete event.

The script sends Cloudflare.getLiveView with mode: tab and shares the returned URL with the human operator.

The script sends the Cloudflare.handoff CDP command with instructions for the human operator, then waits for Cloudflare.handoffComplete.

The operator opens the Live View (/browser-run/features/live-view/) URL, completes the required actions, and selects "Done" or "Failed".

Cloudflare.handoffComplete fires when the human marks the handoff as complete or the handoff times out.

The automation resumes with knowledge of whether the intervention succeeded.

Refer to Example: structured handoff for a complete code sample.


Manual detection


For simpler use cases, you can manually manage the handoff:

Your automation script goes to a page that needs human input.

The script retrieves the Live View URL from the session's target list and shares it with a human operator.

The human operator opens the Live View URL and completes the required action.

The automation script detects completion by polling for page elements or waiting for navigation events.

Refer to Example: manual detection for a complete code sample.


Cloudflare CDP commands


Browser Run extends the standard Chrome DevTools Protocol (CDP) ↗ with Cloudflare-specific commands under the Cloudflare.* namespace. These commands are only available when connected to a Browser Run session and provide capabilities that do not exist in the standard CDP specification, such as requesting human intervention, generating Live View URLs, and tracking handoff state.

You send these commands through a CDP session the same way you would send any standard CDP command. For full parameter and return type details, refer to the protocol reference.


TypeScript types


Make sure you are using the latest versions of @cloudflare/puppeteer or @cloudflare/playwright to get up-to-date type definitions for the Cloudflare CDP commands.




Cloudflare.handoff


Requests human intervention for the current page. The target is automatically resolved from the CDP session.
const cdp = await page.createCDPSession();const { handoffId } = await cdp.send("Cloudflare.handoff", { // targetId will automatically be resolved from the CDP session instructions: "Please log in", timeout: 1800000, // optional, max 30 minutes, if undefined handoff will have no timeout});
To request a handoff for a specific target when your browser has multiple pages:
// Get all targetsconst { targetInfos } = await cdp.send("Target.getTargets");// Find a specific target (for example, a page with a specific URL)const target = targetInfos.find( (t) => t.type === "page" && t.url.includes("example.com"),);if (!target) { throw new Error("Target not found");}// Request handoff for the selected targetconst { handoffId } = await cdp.send("Cloudflare.handoff", { targetId: target.targetId, instructions: "Please complete the CAPTCHA on this page",});

Cloudflare.handoffComplete event


Emitted when human intervention completes or times out. Listen for this event to resume automation once the human is done.
cdp.once("Cloudflare.handoffComplete", (result) => { if (result.success) { console.log("Handoff completed successfully"); } else { console.log(`Handoff failed: ${result.reason}`); }});

Cloudflare.getHandoffState


Checks whether a handoff is currently active for the current page.
const state = await cdp.send("Cloudflare.getHandoffState", { targetId, // optional, defaults to the current page});if (state.active) { console.log( `Handoff ${state.handoffId} has been active for ${state.durationMs}ms`, );}

Cloudflare.getLiveView


Generates a Live View URL for the browser session. Use this alongside Cloudflare.handoff to give the human operator access to the live browser.
const { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", { targetId, // optional, defaults to the current page mode: "tab", // optional, one of "tab", "full", or "devtools" (default) expiresInMs: 300000, // optional, default 5 minutes, max 1 hour});console.log(`Live View URL: ${devtoolsFrontendUrl}`);

Example: structured handoff


This example demonstrates the structured handoff flow. The script requests human intervention using the Cloudflare CDP commands and waits for a completion event before resuming:





import puppeteer, { type HandoffCompleteResponse } from "@cloudflare/puppeteer";const ACCOUNT_ID = "<your-account-id>";const API_TOKEN = "<your-api-token>";// Connect to Browser Runconst browser = await puppeteer.connect({ browserWSEndpoint: `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-run/devtools/browser?keep_alive=600000`, headers: { Authorization: `Bearer ${API_TOKEN}` },});// If using a Cloudflare Worker, you can use: await puppeteer.launch(env.MYBROWSER)const page = await browser.newPage();await page.goto("https://github.com/login");// Create a CDP session to send Browser Run commandsconst cdp = await page.createCDPSession();// Get the Live View URL for the human operatorconst { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", { mode: "tab", // required, only "tab" supports handoff expiresInMs: 300000, // optional, default is 5 minutes});// Share the Live View URL with the human operator (for example, send it via Slack, email, or display it in a UI)console.log(`Human input needed. Open this URL: ${devtoolsFrontendUrl}`);// Set up completion listener before initiating handoffconst handoffCompletePromise = new Promise<HandoffCompleteResponse>((resolve) => { cdp.once("Cloudflare.handoffComplete", (event) => resolve(event as HandoffCompleteResponse));});// Request human intervention with specific instructionsconst { handoffId } = await cdp.send("Cloudflare.handoff", { instructions: "Please log in with your GitHub credentials", timeout: 600_000, // 10 minute timeout});console.log(`Human intervention requested (ID: ${handoffId})`);// Wait for human to complete the taskconst result = await handoffCompletePromise;if (result.success) { console.log("Login successful, continuing automation..."); // Continue with your automation... await page.goto("https://github.com/settings/profile");} else { console.error(`Human intervention failed: ${result.reason}`);}await browser.close();

import type { HandoffCompleteResponse } from "@cloudflare/playwright";import { chromium } from "playwright-core";// If using a Cloudflare Worker, import { launch } from "@cloudflare/playwright" and use launch(env.MYBROWSER) instead.const ACCOUNT_ID = "<your-account-id>";const API_TOKEN = "<your-api-token>";// Connect to Browser Runconst browser = await chromium.connectOverCDP( `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-run/devtools/browser?keep_alive=600000`, { headers: { Authorization: `Bearer ${API_TOKEN}` } },);const context = browser.contexts()[0] ?? (await browser.newContext());const page = await context.newPage();await page.goto("https://github.com/login");// Create a CDP session to send Browser Run commandsconst cdp = await context.newCDPSession(page);// Get the Live View URL for the human operatorconst { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", { mode: "tab", // required, only "tab" supports handoff expiresInMs: 300000, // optional, default is 5 minutes});// Share the Live View URL with the human operator (for example, send it via Slack, email, or display it in a UI)console.log(`Human input needed. Open this URL: ${devtoolsFrontendUrl}`);// Set up completion listener before initiating handoff.// `cdp.once` for Cloudflare.* events needs a call-site cast because// Playwright's `CDPSession.on/once/off` are declared as arrow-property// signatures that TypeScript can't merge overloads into.const handoffCompletePromise = new Promise<HandoffCompleteResponse>((resolve) => { (cdp.once as (event: string, listener: (p: HandoffCompleteResponse) => void) => void)( "Cloudflare.handoffComplete", resolve, );});// Request human intervention with specific instructionsconst { handoffId } = await cdp.send("Cloudflare.handoff", { instructions: "Please log in with your GitHub credentials", timeout: 600000, // 10 minute timeout});console.log(`Human intervention requested (ID: ${handoffId})`);// Wait for human to complete the taskconst result = await handoffCompletePromise;if (result.success) { console.log("Login successful, continuing automation..."); // Continue with your automation... await page.goto("https://github.com/settings/profile");} else { console.error(`Human intervention failed: ${result.reason}`);}await browser.close();




Example: manual detection


This example uses the manual approach of sharing a Live View URL and polling for completion:





import puppeteer from "@cloudflare/puppeteer";const ACCOUNT_ID = "<your-account-id>";const API_TOKEN = "<your-api-token>";// Connect to Browser Runconst browser = await puppeteer.connect({ browserWSEndpoint: `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-run/devtools/browser?keep_alive=600000`, headers: { Authorization: `Bearer ${API_TOKEN}` },});const page = await browser.newPage();await page.goto("https://github.com/login");// Create CDP session and get Live View URLconst cdp = await page.createCDPSession();const { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", { expiresInMs: 300000, // 5 minutes});// Share the Live View URL with the human operator (for example, send it via Slack, email, or display it in a UI)console.log(`Human input needed. Open this URL: ${devtoolsFrontendUrl}`);// Wait until GitHub reports a non-empty `<meta name="user-login">` in the// page head. This meta tag is always present, but its content is empty// for logged-out viewers and set to the username after login. Waiting for// content to be populated is a reliable "human finished logging in" signal.await page.waitForFunction( () => document .querySelector('meta[name="user-login"]') ?.getAttribute("content") !== "", { timeout: 300000 },);// Login complete, continue automationconsole.log("Login complete. Continuing automation...");// Verify we're logged in and read the usernameconst username = await page.$eval('meta[name="user-login"]', (el) => el.getAttribute("content"),);console.log(`Logged in as: ${username}`);await page.goto("https://github.com/");await browser.close();

import type { GetLiveViewResponse } from "@cloudflare/playwright";import { chromium } from "playwright-core";// If using a Cloudflare Worker, import { launch } from "@cloudflare/playwright" and use launch(env.MYBROWSER) instead.const ACCOUNT_ID = "<your-account-id>";const API_TOKEN = "<your-api-token>";// Connect to Browser Runconst browser = await chromium.connectOverCDP( `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-run/devtools/browser?keep_alive=600000`, { headers: { Authorization: `Bearer ${API_TOKEN}` } },);const context = browser.contexts()[0] ?? (await browser.newContext());const page = await context.newPage();await page.goto("https://github.com/login");// Create CDP session and get Live View URLconst cdp = await context.newCDPSession(page);const { devtoolsFrontendUrl }: GetLiveViewResponse = await cdp.send( "Cloudflare.getLiveView", { expiresInMs: 300000 }, // 5 minutes);// Share the Live View URL with the human operator (for example, send it via Slack, email, or display it in a UI)console.log(`Human input needed. Open this URL: ${devtoolsFrontendUrl}`);// Wait until GitHub reports a non-empty `<meta name="user-login">` in the// page head. This meta tag is always present, but its content is empty// for logged-out viewers and set to the username after login. Waiting for// content to be populated is a reliable "human finished logging in" signal.await page.waitForFunction( () => document .querySelector('meta[name="user-login"]') ?.getAttribute("content") !== "", null, { timeout: 300000 },);// Login complete, continue automationconsole.log("Login complete. Continuing automation...");// Verify we're logged in and read the usernameconst username = await page.$eval('meta[name="user-login"]', (el) => el.getAttribute("content"),);console.log(`Logged in as: ${username}`);await page.goto("https://github.com/");await browser.close();




Best practices



Provide clear instructions


Give human operators specific, actionable guidance:
// Good: specific and actionableawait cdp.send("Cloudflare.handoff", { instructions: "Review the items in the cart and if approved for checkout, click 'Done'. Otherwise, click 'Failed' and provide a reason.",});

Set appropriate timeouts


Match timeout duration to task complexity:
// Quick tasks — 2-3 minutesawait cdp.send("Cloudflare.handoff", { instructions: "Click the 'I agree' checkbox and submit", timeout: 120000,});// Complex tasks - 10-15 minutesawait cdp.send("Cloudflare.handoff", { instructions: "Complete the multi-page application form with test data", timeout: 900000,});

Monitor handoff state


Check handoff status when needed:
// Check if a handoff is already active before requesting a new oneconst currentState = await cdp.send("Cloudflare.getHandoffState");if (currentState.active) { console.log(`Handoff already active: ${currentState.handoffId}`); // Wait for current handoff or handle appropriately} else { // Safe to start new handoff await cdp.send("Cloudflare.handoff", { /* ... */ });}

Bot detection


Browser Run requests are
…(内容过长已截断)

------
导航页 打开网址