/yandex-search-api

name: yandex-search-api
description: |
  Поиск в Яндексе через Yandex Cloud Search API v2 с содержательными
  выдержками найденных страниц (smart snippets) — материал для ответа,
  а не только ссылки. Синхронный и асинхронный режимы, кэш результатов.
  Triggers: yandex search api, поиск в яндексе, выдача яндекса,
  serp яндекс, парсинг выдачи, smart snippets, смарт-сниппеты,
  инфоконтексты, выдержки страниц, найди в яндексе, что пишут в рунете.

yandex-search-api

Parse Yandex SERP via Yandex Cloud Search API v2 (sync + async).

Инфоконтексты (Smart Snippets)

Search API отдаёт не только ссылку и сниппет в пару предложений, а фрагмент найденной страницы примерно на 500 токенов — релевантный запросу и с цитатами из документа. Информации уже достаточно, чтобы ответить, а обрабатывать страницу самому не нужно.

Это то, ради чего скилл ставят в агента: одного запроса хватает на ответ, а не только на список ссылок.

Включено по умолчанию, отдельного скрипта не нужно:

bash scripts/web_search_sync.sh --query "как считается НДС для УСН в 2026" --region-id 225

Тексты в ответ не печатаются — они уходят в `cache/results/<hash>.md`, а в stdout приходит индекс по строке на документ. Дальше читай пак файлом: целиком, если нужен весь материал, или грепом, если нужен один источник. Повторный поиск той же фразы ради текста, который уже лежит в паке, — потраченные деньги.

Три ограничения, которые меняют выбор команды:

• **Только синхронный режим.** `web_search_async.sh` инфоконтекстов не вернёт.
• **Только `SEARCH_TYPE_RU`.** С другим типом поиска скилл выполнит запрос, но

без инфоконтекстов, и скажет об этом.

• **Не больше 20 документов.** Попросить больше нельзя: при `--results` выше 20

API отдаёт не 20, а вдвое меньше — по той же цене. Скилл клампит сам.

• **Дороже.** 1 500 ₽ за 1000 запросов против 488 ₽ у обычного синхронного.

Когда нужны только позиции и домены — `--no-snippets` (или `search.smart_snippets.enabled: false` в конфиге).

Подробности, формат ответа, отладка и разбор ошибок: [references/SMART_SNIPPETS.md](references/SMART_SNIPPETS.md).

Config

Для работы нужен сервисный аккаунт Яндекс.Облака с ролью `search-api.webSearch.user`. Поддерживаются IAM через авторизованный JSON-ключ и API-ключ сервисного аккаунта. Пошаговая настройка обоих вариантов: [config/README.md](config/README.md).

Существующие IAM-конфигурации работают без изменений. Для API-ключа задайте `auth.mode: "api_key"` в `config.json` и `YANDEX_AI_API_KEY` в `config/.env`.

Workflow

STOP! Before any search:

1. **Определи регион:**

• Если пользователь указал город/регион — найди ID автоматически:

     bash scripts/search_region.sh --name "Казань"

• Если регион не понятен из контекста — **СПРОСИ и ЖДИ ответа:**

     "Для какого региона искать?
     - Вся Россия (по умолчанию)
     - Москва
     - Конкретный город (какой?)"

**НЕ ПРОДОЛЖАЙ пока пользователь не ответит!**

• Полученное название → `search_region.sh --name "..."` → получаешь ID
• Для неоднозначных случаев (Москва город vs область) — уточни у пользователя

2. **Режим поиска** берётся из `config.json` → `search.mode` (по умолчанию `sync`). Не спрашивай — используй то, что в конфиге. Исключение: если нужны инфоконтексты, режим всегда `sync`, а тип поиска — `SEARCH_TYPE_RU`; в асинхронном API и в других поисковых базах их нет.

3. **Verify config**: убедись, что заданы `yandex_cloud_folder_id`, соответствующий credential (поле `auth.mode` необязательно). Не печатай ключ или токен. 4. **Run search** с полученным region ID 5. **Present results**: со snippets — прочитай пак `cache/results/<hash>.md` и отвечай по нему, ссылаясь на источники; без snippets — позиция, заголовок, URL, сниппет

Scripts

iam_token_get.sh

Generate or validate IAM token from Service Account key. Needed only when `auth.mode` is `iam`.

bash scripts/iam_token_get.sh

Token is cached in `cache/iam_token.json` and auto-refreshed when expired.

web_search_sync.sh

Synchronous search — one query at a time, immediate results. Единственный режим, который умеет smart snippets.

# Single query — с выдержками страниц
bash scripts/web_search_sync.sh \
  --query "купить дымоход" \
  --region-id 213

# Только позиции и ссылки, без выдержек
bash scripts/web_search_sync.sh \
  --query "купить дымоход" \
  --region-id 213 \
  --no-snippets

# Batch from file — по строке на запрос в stdout, пак на каждый запрос
bash scripts/web_search_sync.sh \
  --file queries.txt \
  --region-id 225

| Param | Required | Default | Values | |-------|----------|---------|--------| | `--query, -q` | yes* | - | Search text | | `--file, -f` | yes* | - | File with queries (one per line) | | `--region-id, -r` | no | from config (225) | Region ID | | `--results, -n` | no | 20 со snippets, иначе из конфига (10) | Со snippets клампится до 20; без них 1-100 | | `--page, -p` | no | 0 | Page number | | `--search-type` | no | SEARCH_TYPE_RU | SEARCH_TYPE_RU / SEARCH_TYPE_TR / SEARCH_TYPE_COM / SEARCH_TYPE_KK / SEARCH_TYPE_BE / SEARCH_TYPE_UZ | | `--family-mode` | no | FAMILY_MODE_MODERATE | FAMILY_MODE_NONE / FAMILY_MODE_MODERATE / FAMILY_MODE_STRICT | | `--snippets` | no | вкл | Просить выдержки со страниц | | `--no-snippets` | no | - | Только ссылки и короткие сниппеты |

\* Either `--query` or `--file` is required.

Results saved to `cache/results/<hash>.md` (пак с выдержками), `cache/results/<hash>.json` (parsed) и `cache/results/<hash>.raw` — исходное тело ответа: JSON с инфоконтекстами, XML без них.

web_search_async.sh

Asynchronous batch search — submit many queries, poll for results.

# Submit batch and wait
bash scripts/web_search_async.sh \
  --file queries.txt \
  --region-id 213

# Resume after timeout/interrupt
bash scripts/web_search_async.sh --resume

| Param | Required | Default | Values | |-------|----------|---------|--------| | `--file, -f` | yes | - | File with