← Vytvářejte agenty na Cloudflare / agents / tools

Prohlížeč

Agents mohou používat Browser Run ke kontrole webových stránek a interakci s nimi prostřednictvím Chrome DevTools Protocol (CDP). Beta Nástroje prohlížeče se hodí, když agent potřebuje porozumět vykresleným stránkám, pořizovat snímky obrazovky, ladit chování frontendu nebo získat informace dostupné až po spuštění JavaScriptu.

Místo pevné sady akcí prohlížeče (click, screenshot, navigate) model píše kód, který spouští příkazy CDP proti živé relaci prohlížeče prostřednictvím cdp konektor, který má přístup ke všem doménám, příkazům, událostem a typům v protokolu. Spouštění používá trvalý runtime Code Mode, takže se běh může pozastavit kvůli schválení a poté pokračovat se zachovanou relací prohlížeče.

Používejte nástroje prohlížeče, pokud chcete, aby agent:

• Otevírejte a prohlížejte živé webové stránky.
• Pořizuje snímky obrazovky nebo stav stránky.
• Získávejte vykreslený obsah, který není přítomen ve statickém HTML.
• Ladění problémů na frontendu pomocí příkazů CDP.
• Kombinujte kontrolu stránky s dalšími nástroji, jako je RAG nebo Sandbox.

Browser Run poskytuje izolované relace prohlížeče, které agenti mohou ovládat pomocí CDP. Agent dokáže procházet stránky, vyhodnocovat JavaScript, číst stav DOM, pořizovat snímky obrazovky a sledovat výstup sítě nebo konzole.

Protože relace prohlížeče běží mimo Worker isolate, použijte je pro práci, která vyžaduje skutečné prostředí prohlížeče, nikoli pro odlehčená volání fetch.

Vytvořte nástroje prohlížeče pomocí vazeb Browser Run a Worker Loader a poté tyto nástroje předejte do volání modelu.

import { AIChatAgent } from "@cloudflare/ai-chat";
import { createBrowserTools } from "agents/browser/ai";
import { streamText, convertToModelMessages, stepCountIs } from "ai";
import { createWorkersAI } from "workers-ai-provider";

export class BrowserAgent extends AIChatAgent {
	async onChatMessage() {
		const workersai = createWorkersAI({ binding: this.env.AI });
		const browserTools = createBrowserTools({
			ctx: this.ctx,
			browser: this.env.BROWSER,
			loader: this.env.LOADER,
		});

		const result = streamText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			system: "You can inspect web pages with browser tools.",
			messages: await convertToModelMessages(this.messages),
			tools: browserTools,
			stopWhen: stepCountIs(10),
		});

		return result.toUIMessageStreamResponse();
	}
}

import { AIChatAgent } from "@cloudflare/ai-chat";
import { createBrowserTools } from "agents/browser/ai";
import { streamText, convertToModelMessages, stepCountIs } from "ai";
import { createWorkersAI } from "workers-ai-provider";

export class BrowserAgent extends AIChatAgent<Env> {
	async onChatMessage() {
		const workersai = createWorkersAI({ binding: this.env.AI });
		const browserTools = createBrowserTools({
			ctx: this.ctx,
			browser: this.env.BROWSER,
			loader: this.env.LOADER,
		});

		const result = streamText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			system: "You can inspect web pages with browser tools.",
			messages: await convertToModelMessages(this.messages),
			tools: browserTools,
			stopWhen: stepCountIs(10),
		});

		return result.toUIMessageStreamResponse();
	}
}

Nástroje prohlížeče musí být vytvořeny uvnitř Durable Object (například Agenta): trvalý runtime facet a úložiště relace žijí na jeho ctx. Pomocná funkce zpřístupňuje jeden trvalý nástroj CDP a bezstavové nástroje Quick Action, když browser vazba je přítomna:

Aby model zjistil rozsah protokolu, volá cdp.spec() (živý, normalizovaný popis protokolu CDP) nebo vestavěný nástroj běhového prostředí codemode.search() a codemode.describe().

Přidejte vazby Browser Run a Worker Loader do wrangler.jsonc.

{
	"compatibility_flags": ["nodejs_compat"],
	"browser": {
		"binding": "BROWSER"
	},
	"worker_loaders": [
		{
			"binding": "LOADER"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]

[browser]
binding = "BROWSER"

[[worker_loaders]]
binding = "LOADER"

Trvalý runtime za nástrojem žije ve facetu Durable Object, takže ho musí váš vstupní bod Workeru exportovat (@cloudflare/codemode/vite plugin to dělá automaticky):

export { CodemodeRuntime } from "agents/browser";

export { CodemodeRuntime } from "agents/browser";

agents/browser reexportuje runtime Code Mode pro nastavení nástrojů prohlížeče. Příklady specifické pro Code Mode mohou také importovat CodemodeRuntime z @cloudflare/codemode.

Ve výchozím nastavení každé spuštění získá novou relaci prohlížeče, která se ukončí po skončení běhu (one-shot). Předejte session možnost pro další dva režimy:

createBrowserTools({
	ctx: this.ctx,
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	session: { mode: "dynamic" }, // or { mode: "reuse", key: "main" }
});

createBrowserTools({
	ctx: this.ctx,
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	session: { mode: "dynamic" }, // or { mode: "reuse", key: "main" }
});

• one-shot (výchozí): nová relace pro každé spuštění, deterministické vyčištění po dosažení konečného stavu spuštění.
• reuse : Pojmenovaná sdílená relace, která přetrvává napříč spuštěními, dokud není explicitně uzavřena nebo odstraněna při úklidu.
• dynamic : spustí se jednorázově; model může relaci povýšit pomocí cdp.startSession() (například po přihlášení na stránce), aby další spuštění pokračovala ve stejném prohlížeči.

V reuse a dynamic režimech sandbox navíc získá cdp.startSession(), cdp.sessionInfo(), cdp.closeSession(), a cdp.resetSession().

Relace jsou trvale sledovány v úložišti Durable Object, takže přežijí hibernaci i pauzy na schválení: běh, který se pozastaví kvůli schválení člověkem, se obnoví se zachovanou relací prohlížeče, kartami a soubory cookie. Pokud Browser Run relaci ukončí, zatímco čeká na pauzu, obnovení skončí jasnou chybou a model začne znovu.

Pro propojení na straně hostitele (kontrola relací, úklid, obnova zastaralých pozastavení) použijte createBrowserRuntime, který vrací { runtime, connector, tools }. Zavolejte connector.sweep() z naplánované úlohy pro obnovu vypršených nebo zastaralých relací, a runtime.expirePaused() k zamítnutí zastaralých nikdy neschválených pozastavení.

Použijte browser_execute pro interaktivní vícekrokovou automatizaci. Pro jednorázové úlohy procházení použijte Browser Run Quick Actions. Quick Actions potřebují jen browser vazbu, takže nepotřebují Worker Loader ani sandbox.

import { createQuickActionTools } from "agents/browser/ai";

const tools = createQuickActionTools({ browser: this.env.BROWSER });
// browser_markdown, browser_extract, browser_links, browser_scrape

import { createQuickActionTools } from "agents/browser/ai";

const tools = createQuickActionTools({ browser: this.env.BROWSER });
// browser_markdown, browser_extract, browser_links, browser_scrape

Standardně createBrowserTools a createBrowserRuntime zahrnují nástroje Quick Action vždy, když browser vazba je přítomna. Předejte quickActions: false k zachování pouze browser_execute, nebo předejte quickActions: { actions, maxChars, options } pro konfiguraci bezstavových nástrojů.

createBrowserTools({
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	quickActions: { maxChars: 20_000 },
});

createBrowserTools({
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	quickActions: { maxChars: 20_000 },
});

Každý výsledek Quick Action je omezen na maxChars k ochraně kontextového okna modelu při zachování tvaru výsledku. Možnosti požadavku poskytnuté hostitelem, například cookies, authenticate, gotoOptions, a viewport, se jednou předají přes options a nejsou modelu vystaveny.

Quick Actions vyžadují Worker compatibility_date z 2026-03-24 nebo novější a remote: true na browser bindingu pro lokální wrangler dev.

Live View umožňuje člověku sledovat nebo ovládat běžící relaci prohlížeče v reálném čase. Použijte ji pro kroky vyžadující lidský zásah, jako je přihlášení, MFA, CAPTCHA nebo zadání citlivých údajů.

Protože runtime Code Mode dokáže pozastavit běh se zachovanou relací prohlížeče, předání řízení probíhá podle tohoto vzoru:

1. Model volá cdp.getLiveViewUrl() k získání odkazu na aktuální kartu.
2. Agent zobrazí odkaz uživateli.
3. Model provede volání podmíněné schválením, takže se běh trvale pozastaví.
4. Po schválení běh pokračuje ve stejné relaci.

async () => {
	const { targetId } = await cdp.send({
		method: "Target.createTarget",
		params: { url: "https://example.com/login" },
	});

	const { url } = await cdp.getLiveViewUrl({ targetId, mode: "tab" });
	return { needsHumanLogin: url };
};

async () => {
	const { targetId } = await cdp.send({
		method: "Target.createTarget",
		params: { url: "https://example.com/login" },
	});

	const { url } = await cdp.getLiveViewUrl({ targetId, mode: "tab" });
	return { needsHumanLogin: url };
};

Předejte mode: "tab" pro interaktivní zobrazení stránky nebo mode: "devtools" pro úplný inspektor DevTools. Adresa URL je platná zhruba pět minut. Zavolejte cdp.getLiveViewUrl() znovu, čímž vytvoříte novou URL adresu.

Na straně hostitele connector.liveView() vrátí adresy URL Live View pro karty sdílené relace. Každá karta obsahuje svůj aktuální pageUrl, takže UI agenta může popisovat karty a přeskakovat prázdné nebo interní stránky.

Nahrávání Session zaznamená relaci Browser Run jako strukturované události rrweb. Záznamy použijte k auditu nebo ladění toho, co autonomní běh prohlížeče provedl, poté co se relace uzavře.

Aktivujte pro jednotlivé relace pomocí recording: true:

import { createBrowserRuntime } from "agents/browser/ai";

const { connector } = createBrowserRuntime({
	ctx: this.ctx,
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	session: { mode: "reuse", key: "main", recording: true },
});

import { createBrowserRuntime } from "agents/browser/ai";

const { connector } = createBrowserRuntime({
	ctx: this.ctx,
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	session: { mode: "reuse", key: "main", recording: true },
});

Nahrávka se finalizuje po uzavření relace. Zachyťte ID relace, dokud je relace aktivní, a poté nahrávku načtěte z Browser Rendering REST API:

import { getBrowserRecording } from "agents/browser";

const { sessionId } = (await connector.sessionInfo()) ?? {};
if (!sessionId) {
	throw new Error("No active browser session");
}

const recording = await getBrowserRecording({
	accountId: this.env.CF_ACCOUNT_ID,
	apiToken: this.env.CF_API_TOKEN,
	sessionId,
});

import { getBrowserRecording } from "agents/browser";

const { sessionId } = (await connector.sessionInfo()) ?? {};
if (!sessionId) {
	throw new Error("No active browser session");
}

const recording = await getBrowserRecording({
	accountId: this.env.CF_ACCOUNT_ID,
	apiToken: this.env.CF_API_TOKEN,
	sessionId,
});

Nahrávky se uchovávají po dobu 30 dnů a jsou omezeny na dvě hodiny na relaci. Při nahrávání na sdílených reuse a dynamic relací, protože záznam pokrývá celou dobu trvání relace.

Uvnitř browser_execute, cdp namespace poskytuje následující metody. Všechny metody přijímají jeden argument typu objekt:

Každý cdp.* volání se zaznamená do trvalého logu runtimu. Pokud se běh pozastaví (kvůli schválení) nebo sandbox se přeruší, obnovení přehraje log a pokračuje dál. Volání konektorů proto musí být sekvenční a deterministická. Kód modelu nesmí Promise.all volání CDP (tyto pokyny nástroje vynucují), a vrácený sessionId je stabilní identifikátor relace, který zůstává platný i při opětovném připojení po pozastavení a obnovení.

Kompletní postup včetně nastavení Browser Run, definic nástrojů a pořizování snímků obrazovky najdete v příkladu agenta pro prohlížeč.