The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
search
Host policy over the TinySearch module. Provider implementations, tool
schemas, role dispatch, and fallback all live in
vendor/tinysearch. This domain decides the
OpenHuman side: which providers are usable for this process, how a search
response reads to the model and to the chat UI, and how a module call becomes
an agent tool.
Callers are the tool registry (tools/ops.rs), the settings RPC
(config/ops/search.rs), the MCP server catalog, and the module adapter in
modules/search/ that loads and talks to TinySearch over
the bus.
How it works
Providers, routes, and roles
TinySearch knows ten providers (tinysearch_bus::PROVIDERS): exa, gemini,
gemini_deep_research, tinyfish, parallel, brave, querit, tavily,
seltz, and searxng. Each provider the user enables has a route:
managed: called through the TinyHumans backend, billed to the session or API key. Onlyexaandgeminisupport it (tinysearch_bus::BACKEND_PROVIDERS, re-exported asMANAGED_SEARCH_PROVIDERS). The backend does not proxytinyfishorparallel.direct: the user's own key, or a base URL for SearXNG. Seltz reads its key from[seltz], SearXNG from[searxng].base_url, everyone else from[search]credentials.gemini_deep_researchuses the direct Gemini key.
There are three roles, each with an ordered provider list:
| Role | Routed tool | What it returns |
|---|---|---|
search |
web_search_tool |
Ranked results. |
answer |
web_answer_tool |
A grounded answer with citations. depth: "deep" uses Gemini Deep Research when a key is set. |
contents |
web_contents_tool |
Page contents for a list of URLs. |
The first usable provider in a role's order serves the call. TinySearch falls
back to the next one on balance, rate-limit, and availability errors, and the
response lists the providers it skipped in fallback_from.
Resolving what is usable
providers::resolve walks the catalog and produces one ResolvedProvider per
provider: whether the user enabled it, its route, whether it can be managed,
whether a backend credential exists (managed_available, from
resolve_backend_credential), whether the direct route is configured
(key_configured), and the result, usable. A provider is usable when search
is on, the provider is enabled, and its chosen route is reachable.
ResolvedProvider::status turns that into the settings badge
(Ready, Disabled, NeedsKey, SignInRequired, SearchOff).
role_order returns the configured order for a role, or TinySearch's default
(default_role_providers), filtered to providers that can serve the role.
effective_role_providers intersects that with the usable set.
modules::search::module_config turns the same view into the configuration
the module receives.
A tool call
tools/ops.rs
build_search_tools(config)
modules::search::configured_tool_specs(config) (sync, from config)
-> one TinySearchTool per ToolSpec
|
v (agent calls e.g. web_search_tool)
TinySearchTool::execute_with_options
1. live config (spawn-time copy, or reload for a recorded tool)
2. provider_signature(config); refuse if already exhausted under it
3. local_only_search_block (egress policy) -> error if blocked
4. modules::search::execute_tool(config, ExecuteToolRequest)
| (bus call to TinySearch)
ok | err
v | v
render::render | user_facing_error(code)
text + markdown UNAVAILABLE -> mark_exhausted_for(signature)
+ metadata
Declarations are computed synchronously from config, so a turn's tool list is stable and needs no module round-trip. Each call re-reads the live config, so a key added or a provider switched mid-session takes effect on the next call without rebuilding the session.
The exhaustion latch
A backend credential alone makes the managed route look reachable. On a
deployment that is offline, firewalled, out of balance, or holding a dead key,
the tool is offered every turn and fails every call. To stop the agent burning
turns on it, TinySearchTool records a hash of its own provider view
(provider_signature: its role order plus every provider's resolved state)
when the module answers "every provider is unavailable". A repeat call under
the same signature is refused with SEARCH_EXHAUSTED_MESSAGE, which tells the
model to stop and answer from what it has. Any change a user could make (a
key, a route, a selection, a login) changes the signature and lets the call
through again. Rate limits, low balance, and rejected arguments do not latch;
each has its own message from user_facing_error.
Rendering
render::render builds three things from an ExecuteToolResponse:
- Model-facing text with a heading such as
Search results for: <q> (via Exa)or(via Exa, after Brave)after a fallback, then the answer, numbered results with URL, date, and excerpt (capped at 500 chars), and aSources:list. The chat UI'sextractSearchProviderreads the(via ...)marker. - Optional markdown when the caller prefers it.
- Host-only metadata in
ToolResult::metadata:{"kind":"web_search", "query", "provider", "role"?, "answer"?, "citations"?, "fallback_from"?, "results":[...]}, with excerpts capped at 300 chars, which the chat UI renders as a search card.
Configuration and presentation
Config lives in [search] (config/schema/tools/search.rs): providers,
roles, and presentation. Presentation modes are roles (the default),
all_tools, router, and one_provider. Files from the single-engine era are
migrated on load by config/schema/tools/search_migrate.rs. Parallel is kept
as a direct-only provider, and a keyless managed-Parallel selection is dropped.
Layout
| Path | What it does |
|---|---|
mod.rs |
Module declarations. Without the modules feature it provides a stub build_search_tools that returns nothing. |
providers.rs |
ResolvedProvider, ProviderStatus, resolve, role_order, effective_role_providers, and role key helpers (ROLES, role_key, parse_role). |
render.rs |
render, subject, provider_label, and the text, markdown, and metadata builders. |
tools.rs |
TinySearchTool (the tinytools::Tool bridge), build_search_tools, user_facing_error, the exhaustion latch, and the egress check. modules feature only. |
bus.rs |
CredentialRefreshSubscriber (search::credential_refresh). modules feature only. |
Key types and entry points
build_search_tools(&Config)(tools.rs, stub inmod.rs) is what the tool registry calls. It returns an empty list when search is off or nothing is usable.TinySearchTool(tools.rs) wraps oneToolSpec.TinySearchTool::newtakes the spawn-time config;TinySearchTool::recordedbuilds a deferred instance for a resumed thread that resolves config on each call.providers::resolveandproviders::effective_role_providersare the policy view the settings RPC, MCP catalog, RPC precheck, and module config share.render::renderis the single place a response becomes aToolResult.user_facing_errormaps a module error prefixedtinysearch.<code>:to a message the model can act on. The detail after the prefix may echo the query, so it is not logged.
RPC / CLI surface
This module registers no controllers itself. The search controllers live in
the tools domain (tools/schemas/web_search.rs) and call into this policy:
| Method | What it does |
|---|---|
openhuman.tools_web_search |
Run the search role. |
openhuman.tools_web_answer |
Run the answer role. |
openhuman.tools_web_contents |
Run the contents role. |
openhuman.tools_searxng_search |
Provider-pinned SearXNG search. |
The MCP server lists web_search, web_answer, and searxng_search only when
a provider can serve them (mcp/server/tools/specs.rs). Search settings are
read and written through config/ops/search.rs.
Boundaries
- Provider HTTP clients, tool schemas, role dispatch, and fallback belong to
TinySearch (
vendor/tinysearch, upstreamtinyhumansai/tinysearch). The wire types (ToolSpec,ExecuteToolRequest,ExecuteToolResponse,Role,errors) come fromtinysearch-bus. Do not redeclare them here. - Loading the module, its bus proxy, and reinitialization belong to
modules/search/. - Resumed threads keep their recorded search role tools even when no provider
is usable now. That rehydration is in
integrations/recorded_tools.rs. - The user-facing description is in
docs/gitbooks/en/features/native-tools/web-search.md.
Gotchas
- Keep
rolesas the presentation agents run on. Agent tool scopes allowlist the routedweb_search_tool,web_answer_tool, andweb_contents_tool, and TinySearch advertises and executes only the current mode's tools. Underall_toolsthose agents have no web search at all. Schema v3 moves files the v2 migration had put onall_toolsback torolesonce; a later explicit choice is kept. managed_availableonly means a credential exists, not that the backend will answer. The exhaustion latch is the runtime correction for that.- The
modulesfeature gates everything that calls the module. Without it the domain still compilesprovidersandrender, but no search tools exist. CredentialRefreshSubscriberis meant to refresh a loaded module onDomainEvent::CredentialChanged(domainauth) so a login or logout reaches managed routes before the next call. At the time of writing nothing registers it on the bus, so the refresh only happens on the next search call (which reinitializes the module when its config fingerprint changes).
Tests
Tests sit beside each file (providers_tests.rs, render_tests.rs,
tools_tests.rs, bus_tests.rs). Module config tests are in
modules/search/config_tests.rs.
cargo test -p openhuman search::
pnpm debug rust search::