Модуль `searchers` — веб-поиск

🟢 Модуль даёт агентам доступ к веб-поиску через провайдера (по умолчанию FireCrawl) и поставляет готовый демо-агент. Модуль dual-transport: один и тот же код работает как linked-крейт и как нативная DLL.

Что поставляет

Что	Идентификатор	Описание
Инструмент	`kind: web_search`	поиск в интернете: `title`, `url`, `description`
Агент	`searchers-demo`	демо-агент с подключённым `web_search`
Провайдеры	8 бэкендов	см. таблицу ниже
Настройки	`searchers/*`	ключи провайдеров (секреты), проецируются в env

Модуль входит в набор по умолчанию (server.yaml → modules.enabled или config/modules.enabled). Ядро регистрирует его движок web_search в фабрике инструментов, поэтому YAML-инструменты с kind: web_search становятся доступны автоматически.

Провайдеры

`provider`	Тип	Ключ (env)	База по умолчанию
`firecrawl` (default)	поиск+скрап	`FIRECRAWL_API_KEY`	`https://api.firecrawl.dev`
`tavily`	поиск	`TAVILY_API_KEY`	`https://api.tavily.com`
`brave`	поиск	`BRAVE_API_KEY`	`https://api.search.brave.com`
`serper`	Google SERP	`SERPER_API_KEY`	`https://google.serper.dev`
`serpapi`	Google SERP	`SERPAPI_API_KEY`	`https://serpapi.com`
`exa`	семантический	`EXA_API_KEY`	`https://api.exa.ai`
`google`	Google CSE	`GOOGLE_API_KEY` + `cx`	`https://www.googleapis.com`
`searxng`	self-hosted, без ключа	— (`base_url` обязателен)	ваша инсталляция

Все провайдеры нормализуют ответ в { title, url, description }. base_url можно переопределить (self-hosted/прокси). Провайдер можно выбрать и на каждый вызов: параметр provider в аргументах инструмента перекрывает конфиг.

`web_search` — параметры вызова (их задаёт LLM)

query (обязательный) — поисковый запрос.
limit (1–20, по умолчанию 5) — сколько результатов вернуть.
provider (по умолчанию firecrawl) — один из списка выше.

Результат — JSON:

{ "provider": "firecrawl", "query": "…", "count": 3,
  "results": [ { "title": "…", "url": "https://…", "description": "…" } ] }

Конфиг инструмента

# tools/web_search.yaml
kind: web_search
name: web_search
description: Поиск в интернете (title, url, snippet).
# provider: tavily                # по умолчанию firecrawl
# api_key: tvly-...               # явный ключ (не хранить в git)
# api_key_env: TAVILY_API_KEY     # имя переменной окружения (по умолчанию — по провайдеру)
# base_url: https://api.tavily.com
# cx: <google-cse-id>             # только для provider: google
# limit: 5

Ключ API

Ключ резолвится в порядке: api_key из конфига → переменная окружения api_key_env (по умолчанию — своя для каждого провайдера, см. таблицу). Провайдер searxng ключа не требует. Ключ можно задать и через модуль настроек (страница Настройки): значение сохраняется в БД и проецируется в соответствующую env-переменную без перезапуска. Ручное значение в .env/env.overrides.yaml имеет приоритет.

Демо-агент

searchers-demo поставляется модулем в виде config-бандла и загружается автоматически рядом с config/agents/ (при совпадении имени агент из config/agents побеждает). Агент объявляет tool_files: [tools/web_search.yaml], инструмент добавляется в его список автоматически.

Пример агента

# config/agents/my-search-agent/agent.yaml
name: my-search-agent
instructions: |
  Ты — исследовательский ассистент. Для актуальных фактов вызывай web_search,
  возвращай ответ и ссылки с краткими описаниями. Не выдумывай URL.
tool_files:
  - tools/web_search.yaml

Модуль searchers — веб-поиск