Skip to content

feat(exa): add optional direct REST backend - #647

Draft
wuyak wants to merge 1 commit into
Panniantong:mainfrom
wuyak:codex/exa-rest-backend
Draft

feat(exa): add optional direct REST backend#647
wuyak wants to merge 1 commit into
Panniantong:mainfrom
wuyak:codex/exa-rest-backend

Conversation

@wuyak

@wuyak wuyak commented Aug 23, 2026

Copy link
Copy Markdown

Summary

Closes #646.

为已有个人 EXA_API_KEY 的用户增加一个可选 Exa REST 直连后端,同时完整保留当前免 Key 的 mcporter + Exa MCP 路径。

What changed

  • 新增 agent-reach-exa search / contents / status
    • search 直连 POST https://api.exa.ai/search
    • contents 直连 POST https://api.exa.ai/contents
    • status 只检查本地凭据,不发起计费请求。
  • 新增 agent-reach configure exa-key
    • 默认隐藏输入,也支持 --stdin
    • 明确拒绝把 Key 作为位置参数传入;
    • Key 只放在 x-api-key 请求头,不进入 URL、请求体或错误文本。
  • Exa channel 后端顺序调整为:
    1. Exa REST API(仅当个人 Key 已配置);
    2. Exa via mcporter(现有免 Key 回退)。
  • Doctor 不用一次计费搜索验证 Key,因此 REST 配置存在时诚实返回 warn / active_backend: null,首次真实只读调用再验证网络、额度与限流。
  • 更新中英文 Skill、安装指南和 README,说明两条路径及费用边界。

Semantics preserved

REST 客户端按当前官方 Exa MCP 实现固定了相同默认行为:

  • search type: auto
  • 省略数量时 numResults: 10
  • contents: { highlights: true }
  • 相同的首个内联 category: 解析;
  • fetch 默认 maxCharacters: 3000
  • 60 秒总超时;
  • 只对 500/502/503/504 重试两次,退避 1 秒、2 秒;
  • 可见搜索与正文输出形状保持一致。

对应上游实现:

没有改成 instant,没有把默认条数改成 5,也没有取消 Highlights 或正文抓取。

Compatibility and non-goals

  • 无 Key 用户的安装与 MCP 调用方式不变;
  • 不删除 mcporter,也不影响它服务其他 MCP channel;
  • 不自动注册 Exa 账号、创建 Key 或触发计费搜索;
  • 不包含本机路径、私有凭据库约定或其他 channel 改动。

Verification (current head d8a6b3e)

  • ruff check agent_reach tests — passed
  • mypy agent_reach — passed
  • pytest -q — 603 passed, 16 subtests passed
  • git diff --check upstream/main...HEAD — passed
  • built sdist + wheel, installed the wheel into a clean venv, then verified:
    • agent-reach version works;
    • agent-reach-exa status --json works without a network request;
    • the wheel contains agent_reach/exa_api.py.

The one-run latency observation is documented in #646 as bounded evidence, not as a performance guarantee.

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.

feat(exa): 支持有 API Key 时直连 Exa REST,并保留 MCP 回退

1 participant