← Создание агентов на Cloudflare / agents / tools

Браузер

Agents могут использовать Browser Run чтобы просматривать веб-страницы и взаимодействовать с ними через Chrome DevTools Protocol (CDP). Бета Инструменты браузера полезны, когда агенту нужно понять отрендеренную страницу, сделать скриншот, отладить поведение фронтенда или извлечь информацию, доступную только после выполнения JavaScript.

Вместо фиксированного набора действий браузера (click, screenshot, navigate) модель пишет код, который выполняет команды CDP в живой сессии браузера через cdp коннектор: он обращается ко всем доменам, командам, событиям и типам протокола. Выполнения используют устойчивый runtime Code Mode, чтобы запуск мог приостановиться для получения подтверждения и затем продолжиться с сохранённой сессией браузера.

Используйте инструменты браузера, если хотите, чтобы агент:

• Открывайте и анализируйте веб-страницы в реальном времени.
• Делайте снимки экрана или фиксируйте состояние страницы.
• Извлекайте отрендеренный контент, которого нет в статическом HTML.
• Отладка проблем на фронтенде с помощью команд CDP.
• Сочетайте проверку страниц с другими инструментами, например RAG или Sandbox.

Browser Run предоставляет изолированные сессии браузера, которыми агенты могут управлять через CDP. Агент может переходить по страницам, выполнять JavaScript, считывать состояние DOM, делать снимки экрана и просматривать вывод сети или консоли.

Поскольку сессии браузера выполняются вне Worker isolate, используйте их для задач, которым нужна настоящая среда браузера, а не для лёгких HTTP-запросов fetch.

Создайте инструменты браузера с помощью привязок Browser Run и Worker Loader, а затем передайте эти инструменты в вызов модели.

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();
	}
}

Инструменты браузера нужно создавать внутри Durable Object (например, Agent): устойчивая грань runtime и хранилище сессии находятся на его ctx. Вспомогательная функция предоставляет один устойчивый инструмент CDP, а также stateless-инструменты Quick Action, когда browser привязка присутствует:

Чтобы обнаружить поверхность протокола, модель вызывает cdp.spec() (актуальное нормализованное описание протокола CDP) или встроенное в среду выполнения codemode.search() и codemode.describe().

Добавьте привязки Browser Run и Worker Loader в wrangler.jsonc.

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

compatibility_flags = [ "nodejs_compat" ]

[browser]
binding = "BROWSER"

[[worker_loaders]]
binding = "LOADER"

Устойчивый runtime, стоящий за инструментом, работает в грани Durable Object, поэтому точка входа Worker должна экспортировать его (этот @cloudflare/codemode/vite плагин делает это автоматически):

export { CodemodeRuntime } from "agents/browser";

export { CodemodeRuntime } from "agents/browser";

agents/browser повторно экспортирует рантайм Code Mode для настройки инструментов браузера. Примеры для Code Mode также могут импортировать CodemodeRuntime от @cloudflare/codemode.

По умолчанию каждое выполнение получает новую сессию браузера, которая уничтожается по завершении запуска (one-shot). Передайте session опция для ещё двух режимов:

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 (по умолчанию): новая сессия для каждого выполнения, детерминированная очистка при достижении выполнением конечного статуса.
• reuse : именованная общая сессия, которая сохраняется между выполнениями, пока не будет явно закрыта или удалена при очистке.
• dynamic : запускается разово; модель может повысить сессию с помощью cdp.startSession() (например, после входа на странице), поэтому последующие выполнения продолжаются в том же браузере.

В reuse и dynamic режимах песочница дополнительно получает cdp.startSession(), cdp.sessionInfo(), cdp.closeSession(), а также cdp.resetSession().

Сессии устойчиво отслеживаются в хранилище Durable Object, поэтому они переживают гибернацию и паузы на подтверждение: запуск, приостановленный для подтверждения человеком, возобновляется с сохранённой сессией браузера, вкладками и файлами cookie. Если Browser Run завершает сессию, пока длится пауза, при возобновлении появляется явная ошибка, и модель начинает заново.

Для связывания на стороне хоста (проверка сессий, очистка, освобождение зависших пауз) используйте createBrowserRuntime, которая возвращает { runtime, connector, tools }. Вызовите connector.sweep() из запланированной задачи для освобождения истёкших или устаревших сессий, а также runtime.expirePaused() чтобы отклонять устаревшие паузы, которые так и не были подтверждены.

Используйте browser_execute для интерактивной многошаговой автоматизации. Для разовых задач просмотра используйте Browser Run Quick Actions. Инструментам Quick Action нужен только browser привязку, поэтому им не нужны Worker Loader или 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

По умолчанию createBrowserTools и createBrowserRuntime включают инструменты Quick Action всегда, когда browser привязка присутствует. Передайте quickActions: false чтобы оставить только browser_execute, либо передайте quickActions: { actions, maxChars, options } чтобы настроить инструменты без сохранения состояния.

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 },
});

Результат каждого Quick Action ограничен maxChars чтобы защитить контекстное окно модели, сохраняя при этом форму результата. Параметры запроса, предоставляемые хостом, такие как cookies, authenticate, gotoOptions, а также viewport, передаются один раз через options и не передаются модели.

Для Quick Actions требуется Worker compatibility_date 2026-03-24 или более поздней версии и remote: true для привязки браузера при локальной wrangler dev.

Live View позволяет человеку в реальном времени наблюдать за работающей сессией браузера или управлять ею. Используйте её для шагов с участием человека, таких как вход в систему, MFA, CAPTCHA или ввод конфиденциальных данных.

Поскольку рантайм Code Mode может приостановить запуск, сохранив сессию браузера, передача управления происходит по такой схеме:

1. Модель вызывает cdp.getLiveViewUrl() чтобы получить ссылку на текущую вкладку.
2. Агент показывает ссылку пользователю.
3. Модель выполняет вызов, требующий подтверждения, поэтому запуск устойчиво приостанавливается.
4. После утверждения выполнение возобновляется в той же сессии.

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 };
};

Передайте mode: "tab" для интерактивного просмотра страницы, либо mode: "devtools" для полного инспектора DevTools. URL действителен около пяти минут. Вызовите cdp.getLiveViewUrl() снова, чтобы создать новый URL.

Со стороны хоста connector.liveView() возвращает Live View URL для вкладок общей сессии. Каждая вкладка включает свой текущий pageUrl, чтобы UI агента мог подписывать вкладки и пропускать пустые или внутренние страницы.

Запись Session записывает сессию Browser Run в виде структурированных событий rrweb. Используйте записи для аудита или отладки того, что сделал автономный запуск браузера, после того как сессия завершится.

Включите для каждой сессии с помощью 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 },
});

Запись финализируется после закрытия сессии. Захватите идентификатор сессии, пока сессия активна, а затем получите запись через 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,
});

Записи хранятся 30 дней и ограничены двумя часами на сессию. Будьте осмотрительны при записи на общих reuse и dynamic сессий, потому что запись охватывает весь срок жизни сессии.

Внутри browser_execute, cdp пространство имён предоставляет следующие методы. Все методы принимают один аргумент объекта:

Каждый cdp.* вызов записывается в устойчивый журнал рантайма. Если запуск приостанавливается (для подтверждения) или sandbox прерывается, возобновление воспроизводит журнал и продолжает выполнение, поэтому вызовы коннектора должны быть последовательными и детерминированными. Код модели не должен Promise.all вызовы CDP (это обеспечивается инструкциями инструмента), а возвращённый sessionId это стабильный дескриптор сессии, который остаётся действительным при переподключениях после паузы и возобновления.

Полное пошаговое руководство, включающее настройку Browser Run, определения инструментов и снимки экрана, см. в примере browser agent.