Module `searchers` — web search

🟢 The module gives agents access to web search through a provider (FireCrawl by default) and ships a ready-made demo agent. The module is dual-transport: the same code works as a linked crate and as a native DLL.

What it ships

What	Identifier	Description
Tool	`kind: web_search`	internet search: `title`, `url`, `description`
Agent	`searchers-demo`	demo agent with `web_search` connected
Providers	8 backends	see the table below
Settings	`searchers/*`	provider keys (secrets), projected into env

The module is part of the default set (server.yaml → modules.enabled or config/modules.enabled). The core registers its engine web_search in the tool factory, so YAML tools with kind: web_search become available automatically.

Providers

`provider`	Type	Key (env)	Default base
`firecrawl` (default)	search+scrape	`FIRECRAWL_API_KEY`	`https://api.firecrawl.dev`
`tavily`	search	`TAVILY_API_KEY`	`https://api.tavily.com`
`brave`	search	`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`	semantic	`EXA_API_KEY`	`https://api.exa.ai`
`google`	Google CSE	`GOOGLE_API_KEY` + `cx`	`https://www.googleapis.com`
`searxng`	self-hosted, no key	— (`base_url` required)	your installation

All providers normalize the response into { title, url, description }. base_url can be overridden (self-hosted/proxy). The provider can also be selected per call: the provider parameter in the tool arguments overrides the config.

`web_search` — call parameters (set by the LLM)

query (required) — the search query.
limit (1–20, default 5) — how many results to return.
provider (default firecrawl) — one of the list above.

The result is JSON:

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

Tool config

# 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 key

The key is resolved in the order: api_key from the config → environment variable api_key_env (by default — its own for each provider, see the table). The searxng provider requires no key. The key can also be set via the settings module (the Settings page): the value is saved to the DB and projected into the corresponding env variable without a restart. A manual value in .env/env.overrides.yaml takes priority.

Demo agent

searchers-demo is shipped by the module as a config bundle and is loaded automatically alongside config/agents/ (if the names match, the agent from config/agents wins). The agent declares tool_files: [tools/web_search.yaml], and the tool is added to its list automatically.

Agent example

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

Module searchers — web search