Web search providers

Web search and page reading in DataMind Oda run through a provider: the service that answers a search or fetches a page. This page covers the provider layer for deployments and developers: where its settings live, how Oda chooses a provider, the keys it uses, and what its failures mean. The tools themselves are on Web search and page fetch, and the everyday side is on Chat with Oda.

Where the web search settings live

• Where to change it. The provider's settings live on the Plugins page in the sidebar: select Web Search Provider and edit its Endpoint field. The page stays hidden until Plugins page is on under Settings > Developer > Advanced features (Built-in plugins). A failed search points you to the endpoint setting, and the recovery text ends Only the user should choose or change the endpoint.
• The plugin entry. The provider's plugin entry is titled Web Search Provider.
• No reload needed. Saving the endpoint serves the next search under the same registration. Keys work the same way: they resolve for each search, so a stored or rotated key applies without a restart.
• Separate from chat. The search endpoint is deliberately independent of the endpoint your chat models use; changing one does not move the other. The endpoint can also come from the environment Oda starts in.
• Per-target settings. A search target that runs a model call for each search carries settings for its base address and model, its API version, a token limit and a search-use limit (4,096 and 5 by default). Targets can also carry a result count and, on some, a recency filter. Limit fields take whole numbers of at least 1.

The providers behind the web tools

• One provider per side. Search and page reading each resolve their own provider from the registered ones, so the two sides can use different ones.
• Ids name providers. A provider is known by a short id, and the settings and the messages below refer to providers by that id.
• The set belongs to your deployment. The two above ship with the app, and a deployment can register others. Set up company web search covers the company path's own setup, and Anonymous web fetch safety covers the rules the anonymous path keeps.

How Oda chooses a provider

• A pin wins. A provider pinned in the provider settings (one for search, one for page reading) is used whenever it is registered and available.
• With no pin, exactly one usable provider must be registered. None usable, or several, fails the call with a selection error instead of guessing; the order in which providers were registered never changes the outcome.
• Unusable providers are ignored. When Oda chooses on its own, a provider that is registered but not usable does not count.
• Both pins are unset by default, so Oda chooses at call time. When a pin is left unset in the settings, a value from the environment Oda starts in fills it.
• Availability is a local check. Asking whether a provider is usable makes no network call, and nothing in the app reports a provider's health on its own; whether it truly works appears when a call runs.
• Tools stay put. The web tools stay visible when their provider is missing or misconfigured; the failure arrives with the call, not in the tool list.

The selection errors read:

Keys and signing in

• Where a key can come from. A non-empty key set directly in the target's configuration wins. Otherwise Oda looks in its stored credentials, where a key saved on Settings > Models lives; see Set up models and providers and Stored credentials. Last, a key can come from the environment Oda starts in. The missing-key message points at these three places and never prints a key.
• Keyless fixes need no restart. A key resolves for each search, so a key you store or replace applies to the next one. A value set in the launch environment is read when Oda starts.
• Signed out. While you are signed out, web search and page reading on the platform path fail with a key error before any network request is made.
• Signed in. The platform path follows your session: Oda refreshes an expired session once and retries, and when the server needs a newer app than you run it raises the Update DataMind Oda notice.
• No redirects on credentialed requests. A request that carries your credentials never follows an HTTP redirect; the redirect's target is never contacted.
• Proxies are honoured. Web search and page reads respect the proxy settings of the environment Oda starts in.

What a search and a page read return

• Sources. A search returns the sources it found: an address and a title for each, with a snippet and a date when the target supplies them. Entries without an address are skipped, and duplicate addresses are kept once, first one wins. Search results never carry page content; open the page to read it.
• A written answer, on some targets. Depending on the target, a search can also carry a short written answer beside its sources. One kind of target runs a full model call for every search, which spends time and tokens; others answer from their own index.
• Request shape. A search asks the target with the query; a page read hands the target a single address. A result count sent along is only a cost and latency optimisation, never something the model controls.
• Page reads. A read returns the page's readable text, its address, and the status the page answered with. Content is cut at the target's character cap (100,000 characters by default) and marked as truncated when it is cut.
• A 404 can be a success. A page that answers 404 to the platform was still read, and the result reports status 404. A 404 from the platform itself is a provider failure.

Fix a failed search

1. Read the message. The platform path reports its failures with the texts below; the selection errors above cover provider problems.
2. Open Plugins in the sidebar, select Web Search Provider and check its Endpoint field; only you should choose or change the endpoint.
3. If the failure is about a key, store it (the Models settings page writes keys into Oda's credentials), set it in the environment Oda starts in, or set it directly in the target's configuration.
4. The change applies to the next search; no restart is needed. If the failure repeats, keep the message and contact your administrator; the section's collected messages are on Troubleshooting.

Questions, answered

How do I change the web search endpoint?

Open Plugins in the sidebar, select Web Search Provider and edit its Endpoint field. If Plugins is not in the sidebar, turn on Plugins page under Settings > Developer > Advanced features first. Only you should choose or change it. The change serves the next search, with no restart; a failed search points you to the same place.

Do I need to restart Oda after changing the endpoint or a key?

No. The endpoint is read afresh for each search under the same registration, and keys resolve for each search, so a stored or replaced key applies to the next one. Keys and endpoints that come from the environment Oda starts in are the one exception: that environment is read when Oda starts.

Why does web search fail with a key error?

No usable key reached the provider. If you are signed out, the platform path fails this way before making any network request. Otherwise save the key on Settings > Models (see Set up models and providers), set it in the environment Oda starts in, or set it directly in the target's configuration, where a non-empty value wins. The next search can then succeed with no restart. The message points at these places and never prints the key, and Oda never shows a stored key back.

Which provider does Oda use when several are registered?

A pinned provider wins whenever it is registered and available. With nothing pinned, exactly one usable provider must be registered for the side. If several are usable, the call fails with multiple usable web providers are registered (<ids>); configure one explicitly, listing their ids; pin one in the provider settings. The order in which providers registered never changes the outcome.

Do search and page reading have to use the same provider?

No. Each side resolves its own provider and has its own setting, so a deployment can use one provider for search and another for page reading. The anonymous fetch path only reads pages, so it never answers a search.

What do the configured web provider and no usable web provider messages mean?

configured web provider "<id>" is not registered means the pinned id is not registered on this deployment; configured web provider "<id>" is registered but unavailable means the provider is there but not usable. Fix the pin or the provider's own setup; Set up company web search covers the company path's side. no usable web provider is registered means nothing is pinned and no usable provider is registered for that side; keep the message for the person who set up your deployment.

Why is the web tool still available when no provider is configured?

The tools follow the product's configuration, not provider availability. A missing or misconfigured provider does not remove the tool; the failure appears when a search or a read runs, with one of the messages above.

Can I see whether a provider is working before I search?

No. Oda's check for whether a provider is usable is a local one that makes no network call, and nothing in the app reports a provider's health on its own. Whether a provider truly works shows when a call runs: if it fails, the message on the step says why.

Is the web search endpoint the same as my chat model's endpoint?

No. The search endpoint is deliberately independent of the endpoint your chat models use. An error about web search therefore points at its own settings path, and changing one endpoint does not move the other.

Why did a page read succeed with status 404?

Because the page itself answered 404. The read completed and reports the page's status, including 404. Only a 404 from the platform itself is a provider failure.

Does web search work while I am signed out?

On the platform path, no: it fails with a key error before any network request. Sign in, or configure a key for a search target that accepts one. Page reading through the anonymous fetcher carries no credentials and does not depend on your DataMind sign-in.

What does each provider return, and what does it cost?

The platform provider returns sources with titles, addresses, snippets and dates, and its page reads return the page's text; its work runs on your company's server. The anonymous fetcher returns page text only, read on this computer, and sends no credentials (Anonymous web fetch safety covers its rules). A deployment can also mount other search targets; one kind runs a full model call for each search, which costs time and tokens, while an index-backed target answers directly.