Activation Reference

This page is the single place to look for the question "why is engine/reader X (not) showing up in the Spaces UI?" and "how do I turn the whole Web Search tool off?".

The key principle to internalise:

The env var puts the option in the UI; the API key in the env makes it actually work.

There are two independent gates:

1. Visibility gate — ACTIVE_SEARCH_ENGINES and ACTIVE_INHOUSE_CRAWLERS (plus API-key auto-activation) decide which entries appear in the Search Engine and Web Page Reader dropdowns in the Spaces UI.

2. Functional gate — for an engine or reader to actually run, its specific credentials (API key, Azure identity, GCP credentials, etc.) must also be configured. An engine can be visible but non-functional, in which case it appears in the dropdown but fails at runtime.

This page covers the visibility gate plus the platform-wide tool kill switch and the default-mode selector. For the functional gate (per-engine and per-reader credentials), see Search Engine Setup and Web Page Reader Setup.

Activation flow at startup

At runtime, the executor fetches credentials lazily and any engine or reader with missing credentials raises a configuration error before its first call.

Search Engine Activation

ACTIVE_SEARCH_ENGINES is a comma-separated list of engine identifiers. Each identifier appears in the engine selector if and only if it is on this list.

Default: ["google"].

Each Space can pick any one of the visible engines via its Search Engine setting.

Web Page Reader Activation

Reader activation has two layers:

1. Built-in readers — ACTIVE_INHOUSE_CRAWLERS is the explicit list. Defaults to ["basic", "crawl4ai"]. Drop one of those names from the env var to hide it from the UI.

2. Third-party readers — auto-activate when the matching API key is present. There is no separate env var to enable them.

The platform composes the active reader list at startup as:

active_inhouse_crawlers + ("firecrawl" if FIRECRAWL_API_KEY) + ("jina" if JINA_API_KEY) + ("tavily" if TAVILY_API_KEY)

Each Space can pick any one of the visible readers via its Web Page Reader setting.

Note: Firecrawl, Jina, and Tavily are also search engines. The same API key is used for both their search and reader integrations.

Tool-wide controls

DISABLE_WEB_SEARCH_TOOL

Platform-wide kill switch managed by assistants-core. When set to true, the Web Search tool is removed from the orchestrator's tool list before any conversation starts; no Web Search activity is possible regardless of per-Space configuration.

For the conceptual placement of this kill switch alongside the Web Search-specific feature flags, see the Feature Flags page.

WEB_SEARCH_MODE

Default search mode for Spaces that have not overridden it. Values:

Space admins can override this per Space via the Search Mode setting in the Spaces UI; see Search Mode Configuration.

Recommendation: only set WEB_SEARCH_MODE=v3 after internal validation. V3 changes the orchestrator's interaction model and can produce different cost and quality profiles than V1/V2 for the same workload.

Worked examples

• "Bing is in the dropdown but searches fail" — the engine is on ACTIVE_SEARCH_ENGINES (visibility gate passes) but Azure identity or the project endpoint isn't configured (functional gate fails). See Search Engine Setup.

• "I want clients to only see Google and Brave" — set ACTIVE_SEARCH_ENGINES=["google","brave"]. Drop everything else.

• "I want to disable web search entirely for a customer" — set DISABLE_WEB_SEARCH_TOOL=true.

• "I want every new Space to default to V3" — set WEB_SEARCH_MODE=v3. Space admins can still pick V1 or V2 explicitly.

• "I added FIRECRAWL_API_KEY but Firecrawl Reader doesn't appear" — the env-var name must be exactly FIRECRAWL_API_KEY. Restart the assistants-core pods so they pick up the new env.