Skip to content

feat: add Exa as an optional search provider#1480

Open
tgonzalezc5 wants to merge 1 commit intoagent0ai:mainfrom
tgonzalezc5:feat/exa-search-provider
Open

feat: add Exa as an optional search provider#1480
tgonzalezc5 wants to merge 1 commit intoagent0ai:mainfrom
tgonzalezc5:feat/exa-search-provider

Conversation

@tgonzalezc5
Copy link
Copy Markdown

Description

Adds Exa as an optional, drop-in search provider for the search_engine tool. When EXA_API_KEY is set in the environment (or usr/.env), the agent automatically uses Exa's neural search instead of SearXNG. If the key is absent or a request fails, it falls back to SearXNG transparently.

Why Exa? Exa is an AI-native search engine built on neural embeddings. It returns semantically relevant results rather than keyword matches, which is a better fit for agent workloads where queries are natural-language questions. Highlights mode keeps token usage efficient.

Changes

  • helpers/exa_search.py (new) — Thin async wrapper around the exa-py SDK. Returns results in the same {title, url, content} format the existing format_result_searxng expects, so no prompt or downstream changes are needed.
  • tools/search_engine.py — Checks exa_search.is_available() at call time. Routes to Exa when configured; falls back to SearXNG on missing key or request error.
  • requirements.txt — Adds exa-py>=1.0.0.

Design decisions

  • Opt-in, zero breaking changes. Existing users who don't set EXA_API_KEY see no difference.
  • Graceful fallback. If Exa errors mid-session, the tool retries with SearXNG rather than failing the agent loop.
  • Uses models.get_api_key("exa") so it picks up API_KEY_EXA, EXA_API_KEY, or EXA_API_TOKEN automatically, consistent with how other API keys are managed in Agent Zero.
  • Includes x-exa-integration: agent-zero header for integration-level usage tracking on Exa's side. (See also: HKUDS/CLI-Anything#205 for the same pattern in another open-source integration.)

Setup

# In usr/.env or your shell environment:
EXA_API_KEY=your-key-here

Get a free key at https://dashboard.exa.ai/api-keys

Test plan

  • Without EXA_API_KEY: search works exactly as before (SearXNG)
  • With EXA_API_KEY: search returns Exa results (title/url/highlight)
  • With invalid EXA_API_KEY: gracefully falls back to SearXNG
  • pip install -r requirements.txt installs exa-py without conflicts

When EXA_API_KEY is set, the search_engine tool uses Exa's neural search
instead of SearXNG. Falls back to SearXNG automatically if the key is
missing or if an Exa request fails.

- Add helpers/exa_search.py with highlights-based content retrieval
- Add exa-py to requirements.txt
- Modify SearchEngine to check for Exa availability at call time

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant