Открывает НЕСКОЛЬКО URL в одном браузере — для глубокого ресёрча на 30-50 источников одним вызовом вместо серии холодных стартов. Кэш: уже посещённые URL возвращаются мгновенно, без браузера. Rate limit между переходами защищает от капчи. Батч ≥8 URL — параллельно (пул потоков, свой браузер на поток); число воркеров автоопределяется по ресурсам машины (слабый ПК — 1-2, мощный — 3-4), max_parallel — явное ограничение. Возвращает тексты с разделителями '--- URL: ...'. article_only=True — извлечь текст статьи (Trafilatura), без меню и баннеров. Пример: batch_fetch(urls=["https://docs.python.org/3/", "https://opencode.ai/docs/"], max_chars=20000, article_only=True) ХОЧУ ПОЛНОТУ → max_chars=20000..100000 + article_only=True + max_parallel=4; экономия контекста → max_chars=4000 при 30+ URL. Замер 21.09 (8 URL разных доменов, холодный кэш): 4000 → 32 598 симв. за 36.4с (все 8 обрезаны ровно по 4000), 12000 → 96 598 симв. за 30.3с, 20000 → 154 449 симв. за 45.9с — время НЕ растёт от объёма: страница и так читается до потолка кэша (100k), max_chars режет только ОТВЕТ. КОГДА: читать 10-50 URL одним вызовом (глубокий ресёрч после research(queries=[...]) или crawl/map_site). НЕ КОГДА: 1-2 страницы → fetch_page; URL ещё не собраны → research, sitemap, map_site сначала.

КОГДА: перед публикацией или после редизайна — найти битые ссылки на странице. ЧТО: HTTP-статусы собранных ссылок, отчёт вида «[404] URL». timeout — срок НА КАЖДУЮ ссылку (15с). Обычный путь (urllib) идёт ОГРАНИЧЕННЫМ ПУЛОМ потоков: CAMOUFOX_LINK_WORKERS (дефолт 8, потолок 16) — 50 ссылок ≈ минута, а не ~12. НО при поднятом живом браузере (serve) запросы идут через его sync-Playwright — он потокопривязан, поэтому пул принудительно 1 (последовательно). Бюджет вызова мост поднимает сам (900с) — таймаут MCP-клиента ставь ≥900с. НЕ: жди параллельности, когда поднят живой браузер — там строго по одной (грабли: 4 потока → 15/15 error); внешние ссылки → internal_only=False.

КОГДА: собрать содержимое САЙТА целиком (BFS по внутренним ссылкам) для синтеза, а не одну страницу. ЧТО: тексты страниц (depth ≤ max_depth, всего ≤ max_pages) с разделителями '--- URL:'; кэш делает повторный обход дешёвым. Идёт долго (десятки переходов) — таймаут MCP-клиента ставь ≥900с. НЕ: нужны только URL → map_site / sitemap; сайт огромный → sitemap + pattern и уже потом crawl нужного раздела; одна страница → fetch_page.

КОГДА: результат нужен файлом на диске — CSV для таблиц, JSON для автоматизации, MD для отчёта. ЧТО: файл (json/csv/md) по своему path или авто в ~/.cache/camoufox-research/exports/. НЕ: результат идёт в разговор и синтез → отдай текст как есть.

КОГДА: нужны конкретные поля страницы — при стабильной вёрстке селекторами (CSS/XPath) или из текста через llm=True, когда вёрстка хрупкая и селекторы отваливаются. ЧТО: schema — JSON-объект (можно строкой для совместимости): {"поле": "css:.price"} или {"поле": {"selector": ".price", "attr": "text|href|src"}}; llm=True — {"поле": "подсказка"} и нужен LLM (DeepSeek/Ollama), иначе честный ответ «недоступен». НЕ: нужен сплошной текст → fetch_page / batch_fetch; таблицы → table_extract; не знаешь селектор → сначала snapshot.

Собирает ссылки страницы (фильтр по подстроке pattern).

Текст страницы без HTML-мусора (статьи, доки, README). Кэш на сутки. article_only=True — текст статьи (Trafilatura), fallback — весь body. delta=True — delta-чтение: если контент не изменился с прошлого раза, вернёт маркер '[delta: ...]' вместо текста (не тратим токены на повтор). max_chars режет только ОТВЕТ, а не чтение: страница кладётся в кэш целиком (потолок 100k), поэтому повтор с большим max_chars мгновенный и бесплатный по времени (замер 21.09: asyncio-task.html = 46 094 симв. в кэше; 12000 = 26% текста, 40000 = 87%, все ответы 0.0с). КОГДА: прочитать 1 страницу (JS/SPA — тоже) чистым текстом. НЕ КОГДА: страниц 10+ → batch_fetch; нужны поля по схеме → extract; повторное чтение → delta=True; нужен клик/ввод → session_start.

КОГДА: понять структуру сайта — какие разделы и страницы есть, без чтения содержимого. ЧТО: ссылки того же домена со стартовой страницы (до max_links), pattern — фильтр по URL. НЕ: нужны тексты → crawl; есть sitemap.xml → sitemap (полнее и дешевле); одна страница → fetch_page.

КОГДА: страницу уже читали, и нужно узнать, что ИЗМЕНИЛОСЬ — цены, доки, новости (мониторинг, второй и далее заходы). ЧТО: дифф свежего чтения с прошлым из кэша, «что поменялось». НЕ: страница читается впервые — сравнивать не с чем, сначала fetch_page; нужна полная текстовая версия → fetch_page.

Поиск научных статей: arXiv + Semantic Scholar (бесплатные API, без ключей). Возвращает статьи с годом/авторами/цитатами — первоисточники (tier 0), которых общий поиск почти не видит (паттерн индустрии: vertical index / arxiv-канал рядом с вебом). Кэш на сутки. sources — какие индексы брать (arxiv/semantic/ crossref/wiki); пусто — arxiv+semantic. Пример: paper_search("deep research agents", sources=["arxiv"])

Проверка связи: возвращает pong.

Это ПРИКЛАДНОЙ health-тул, а не протокольный ping (его в спеке 2026-07-28 убрали). Имя оставлено публичным контрактом — менять нельзя.

КОГДА: нужен документ (PDF/DOCX/XLSX) — отчёт, прайс, спецификация; такие файлы часто попадаются ссылками с сайтов. ЧТО: текст документа; source — URL или локальный путь (pypdf / python-docx / openpyxl, до max_chars). Локальный путь — только из каталога загрузок сервера (туда кладёт session_download); свой путь — вентиль CAMOUFOX_ALLOW_ANY_PATH=1. НЕ: HTML-страница → fetch_page (дешевле); старые .doc/.xls не читаются — сначала libreoffice --convert-to docx/xlsx.

Когда: нужно СЕЙЧАС 10+ источников на тему одним вызовом — глубокий разбор без фонового ожидания. Один факт, новость или точный URL — это web_search. Что: сервер ищет по КАЖДОЙ формулировке (queries), дедуплицирует URL и отдаёт список со сниппетами; fetch_top>0 сразу читает топ-N текстов. Результат кэшируется на сутки.

По умолчанию хватит queries (2-4 формулировки) и fetch_top=3..5. Остальное — тонкая настройка, всё рабочее, но трогать не обязательно: max_chars режет только ответ; max_parallel — воркеры чтения; target_domains=N — цель по РАЗНЫМ доменам (20 = двадцать сайтов, доборка волнами); domains_limit=K — не больше K с одного домена; expand=True — переформулировки («X comparison», «X documentation»); terms_wave=True — вторая волна из редких термов первой (паттерн Open Deep Research); quality_first=True — доки/GitHub/arXiv первыми; fetch_all=True — тексты ВСЕХ отобранных, а не топ-N (30 источников × 12k ≈ 90k токенов); as_json=True — машинный JSON: meta (счётчики, follow-up запросы), sources (title/url/domain/tier/tier_label/snippet), texts, notes (тот же объект в structuredContent, content — прежняя строка); academic=True — вертикальный arXiv + Semantic Scholar канал (tier 0, без ключей); llm_planner=True — LLM-планировщик follow-up (DeepSeek/Ollama, нужен DEEPSEEK_API_KEY или OLLAMA_HOST, иначе пропуск); mode="быстро"|"полно"|"глубоко" (fast/full/deep) — пресет одним словом, трогает только ручки на дефолте (явный аргумент сильнее пресета). Пример глубокого разбора: research(queries=["deep research agents"], target_domains=20, domains_limit=2, expand=True, terms_wave=True, quality_first=True, academic=True, llm_planner=True, fetch_all=True, as_json=True, max_results_per_query=6).

Замер 21.09 (5 источников): fetch_top=0 — 0 текстов и 2 822 симв. за 5.5с; fetch_top=3 + max_chars=12000 — 3 текста и 32 432 симв. за 23.1с. ⏱ Долгий: один вызов идёт до ~15 мин (внутренний таймаут 900с, столько же ставь таймауту MCP-клиента) — ждать ответа, не поллить.

КОГДА: следить за обновлениями — новости, блог, changelog, релизы (лента отдаёт даты одним вызовом). ЧТО: посты RSS/Atom: title, link, дата (до limit). НЕ: у URL обычная HTML-страница → fetch_page; следить за лентой целиком → crawl/map_site.

КОГДА: нужен полный список страниц сайта — фид для crawl или проверка «что вообще есть на домене». ЧТО: URL из sitemap.xml (+ .xml.gz и вложенные sitemapindex), до max_links. НЕ: у сайта нет sitemap → map_site (ссылки со страницы); тексты → crawl.

КОГДА: понять, какие тулы реально работают и что падает — аудит вызовов и отладка клиента. ЧТО: по каждому тулу счётчик вызовов, среднее время, ошибки, плюс последние вызовы (секреты замаскированы). В профилях caps виден ВСЕГДА (ALWAYS_ON); явные CAMOUFOX_TOOLS_ONLY / CAMOUFOX_TOOL_HIDE сильнее и могут его убрать. НЕ: это не метрика «какими тулами пользуются» (её даёт ~/.cache/camoufox-research/tool_usage.json) и не здоровье сервера (его даёт ping).

КОГДА: на странице есть — прайсы, характеристики, сравнения. ЧТО: CSV-текст таблиц (до max_tables) по CSS-селектору. НЕ: нужных данных в таблице нет → extract; таблиц нет вовсе → fetch_page; JS-грид на div'ах → extract / snapshot.

Когда: БЫСТРЫЙ ОТВЕТ — один запрос, факт, новость, точный URL. Что: номера, заголовки и URL из DuckDuckGo (анти-детект браузер), кэш на сутки; include_snippets — сниппет под URL, pages>1 — пагинация. engines — явный список движков для диагностики (["brave"], ["ddg_html","bing"]), пусто — цепочка из env CAMOUFOX_SEARCH_ENGINES; transport — "auto"/"http"/"browser" (HTTP-фолбэк быстрее, браузер нужен JS/consent-движкам); proxy — разовый прокси на этот вызов ('host:port', 'user:pass@host:port', 'socks5://host:port'); без них поведение прежнее. Не когда: нужно 10+ разных сайтов → research (сейчас); научные статьи → paper_search.