Live now · Get your API key

Provider routing

Ambient orders search, fetch, browser, vision, and local-model providers by your preference and task fit, with policy checks and visible fallback evidence when one is skipped.

Provider routing is how Ambient Desktop decides which capability handles a given step: which search provider, which fetch or scraping path, when to open a real browser, and when local models or vision runtimes are the right fit. Ambient can prioritize and fall back through providers for search, fetch, browser, media, and model-adjacent work.

Ambient Desktop settings and workspace.
Settings and chat preferences guide provider choice while policy, task fit, and evidence determine fallback.

Agent success often depends on selecting the right capability for the job. Search, scraping, browser content, vision, local runtimes, and model providers have different strengths, privacy boundaries, costs, and failure modes.

Provider Preference And Fallback diagram. A four-node decision chain runs left to right. User preference (Settings order, or a chat override) leads to Task fit (search, fetch, browser; or vision or a local runtime), then to Policy check (privacy and URL scope; secrets and cost), then to Provider attempt (success or timeout; blocked or a weak result). A fallback evidence chip records the skip reason, retry path, and final source attribution.

Provider Preference And Fallback: Settings and chat preferences guide provider choice while policy, task fit, and evidence determine fallback.

How a routing decision flows#

Provider choice is a user preference plus a runtime decision. Each attempt passes through four checks:

  1. User preference: your Settings ordering, or a chat override for this task.
  2. Task fit: search, fetch, browser, vision, or a local runtime, depending on what the step needs.
  3. Policy check: privacy posture, URL scope, secrets, and cost.
  4. Provider attempt: success, timeout, blocked, or a weak result that triggers the next provider in line.

When a fallback happens, Ambient preserves the evidence: the attempted provider, the reason for the fallback, the next provider tried, the final source attribution, and any confidence limits.

Where preferences live#

  • Settings (durable) holds provider priority, local-first posture, privacy boundaries, disabled providers, API key setup, runtime repair, and default fallback behavior. The provider ordering persists until you change it. Settings search keeps provider, permission, and runtime configuration discoverable.
  • Chat (task-local) steers one run without touching Settings: "prefer local research for this task", "try Exa first", "use browser content only if search is insufficient", "avoid cloud vision for this screenshot". A chat preference overrides ordering for that run only, and it cannot bypass policy or missing setup.
  • Welcome Core Setup is where you go when the provider is not ready. It routes you to ToolHive, Scrapling, Local Research, voice, vision, document, or access setup before a task depends on that provider.

For web-heavy tasks, configure search, ToolHive, and Scrapling first. For local-first tasks, configure Local Research and the local model runtimes. For screenshot work, configure visual analysis or browser paths.

Provider roles#

  • Search returns links and snippets; it does not replace full source inspection.
  • Scraping and fetch extract page content. Scrapling, the reviewed default for public web extraction, runs through ToolHive when you need isolated extraction.
  • The browser is for when rendering, login state, screenshots, or page interaction matters; browser runs preserve evidence and respect URL policy.
  • Local models and vision cover privacy-sensitive, latency-sensitive, low-cost, image-analysis, and local-first work when the selected runtime is ready.

Reading a skip#

When a provider is skipped, the recorded reason comes from a small taxonomy: disabled, missing credentials, blocked by policy, unavailable, timed out, or not suited to the task. That skip reason plus the retry path and final source attribution is the troubleshooting trail. It tells you whether to fix credentials, enable a provider, adjust policy, or confirm that the router picked a better-fitting path.

Example prompts#

Three task-local steering prompts you can paste into chat:

Prefer local-first research#

For this task, prefer local research and local models where possible. Use public web providers only if local sources are insufficient, and tell me when fallback happens.

Use search then browser#

Search first. If the result pages need rendering or screenshots, fall back to browser content. Keep citations and explain any blocked pages.

Use Scrapling for public pages#

Use the reviewed Scrapling capability for public web extraction if it is installed. If ToolHive or Scrapling is not ready, tell me exactly which setup step is missing.

Keep going#

  • Ambient Desktop overview: Core Setup and the first-run flow where providers get configured
  • Workflow Recorder: workflows record their provider prerequisites and fallback expectations
  • Symphony: the local/cloud model split as an orchestration pattern