Add Exa as a BYOK search provider option alongside Parallel, Brave, and Querit #5137

Summary

Exa is already the default provider powering OpenHuman Managed search (~95% of traffic). The next step is to expose Exa as a bring-your-own-key (BYOK) option in Connections → Search engine, so users who have their own Exa API key can route search calls directly from their machine — the same pattern as Parallel, Brave Search, and Querit.

Current state

Required changes

UI (Connections → Search engine)

Add Exa as a selectable provider with NEEDS API KEY badge, alongside Parallel, Brave, and Querit:

Exa  [NEEDS API KEY]
Neural search powered by Exa. Requires your own Exa API key.

Add an Exa API key input field below the existing API key fields:

Exa API key        [Get API key ↗]
[ EXA-...                        ] [Show] [Save]

"Get API key" links to: https://exa.ai

Backend / search routing

When user has an Exa API key saved and selects Exa as their provider:

• Route search calls directly to https://api.exa.ai using the user's key
• Do not route through the OpenHuman managed backend
• Support Exa's core search tools: neural search, keyword search, find similar, contents retrieval

Search tool set for Exa BYOK

Map Exa API capabilities to agent tool calls:

• exa_search — neural / keyword web search
• exa_find_similar — find pages similar to a URL
• exa_get_contents — retrieve full page contents for a list of URLs

These should be available in the agent's tool list when Exa BYOK is the active provider.

Acceptance criteria

• Exa appears as a selectable option in Connections → Search engine with NEEDS API KEY badge
• Exa API key field present with "Get API key" link to exa.ai
• Saving a valid Exa API key and selecting Exa routes search tool calls directly to Exa API (not managed backend)
• Agent tool list includes exa_search, exa_find_similar, exa_get_contents when Exa BYOK is active
• Invalid or missing key shows a clear error on first search attempt
• OpenHuman Managed remains the default and is unaffected by this addition

Related

• Exa attribution issue (companion: surface Exa in tool calls for managed path)
• Exa docs issue (companion: document Exa in GitBook and README)
• Connections → Search engine (Parallel, Brave, Querit as reference implementations)
• tinyhumansai/backend — managed search routing

Implementation Plan

Triage Assessment

• Valid feature request: Add Exa as a BYOK search provider alongside existing Parallel, Brave, and Querit options.
• Follows the same pattern as existing BYOK search providers; reference implementations available in the codebase.

Proposed Scope

• In-scope: UI for Exa provider selection + API key field; search tool set (exa_search, exa_find_similar, exa_get_contents); direct routing to https://api.exa.ai when Exa BYOK is active.
• Non-goal: Changes to the managed search routing backend. Exa BYOK should route directly, not through the OpenHuman managed backend.

Implementation Steps

1. Frontend (app/src/): Add Exa as a search provider option in Connections → Search engine. Copy Parallel/Brave/Querit pattern for the selection card, API key input, and NEEDS API KEY badge.
2. Rust search tool layer (src/openhuman/tools/impl/search/): Implement Exa search tools. Exa API docs: https://api.exa.ai/search (neural/keyword), https://api.exa.ai/findSimilar, https://api.exa.ai/contents. Register them in src/openhuman/tools/ops.rs alongside existing search tools, gated on Exa being the active provider.
3. Search routing (src/openhuman/tools/impl/search/): When Exa BYOK is active and a search tool is called, route directly to Exa API with the user's key. Do not proxy through the managed backend.
4. Error handling: Invalid/missing key shows a specific error on first use.
5. Ensure OpenHuman Managed remains the default and is unaffected.

Verification

• Configure a valid Exa API key, select Exa as search provider, run a web search query in Chat.
• exa_search, exa_find_similar, exa_get_contents tools appear in agent tool list.
• cargo test -p openhuman and pnpm test pass.

Risks and Open Questions

• Exa API rate limits and pricing: the user's own key means they manage quota directly.
• Exa BYOK must coexist cleanly with the managed Exa path — the managed path still routes through the backend, BYOK routes directly.

Acceptance Criteria

• Exa appears as a selectable option in Connections → Search engine with API key field
• Valid Exa API key routes search calls directly to Exa API
• Agent tool list includes Exa-specific tools when Exa BYOK is active
• Invalid/missing key shows clear error
• OpenHuman Managed remains default and unaffected