用 Exa API 构建搜索与研究应用时如何选端点…

在集成 Exa 的搜索、内容提取、答案生成、Agent 研究或监控工作流时，按任务形态选对端点并写出最小化、正确的请求。

适用场景

解决思路

1. 安装最新 SDK：Python 用 `pip install exa-py`，TypeScript/JavaScript 用 `npm install exa-js`，让包管理器解析最新版本以启用全部 SDK 能力。
2. 设置认证：`export EXA_API_KEY="your_api_key_here"`；Exa 接受 `x-api-key` 头或 `Authorization: Bearer <key>`。
3. 默认使用推荐搜索请求：只写 `query` 加 token 高效的内容提取，例如 `{"query": "latest developments in LLMs", "type": "auto", "contents": { "highlights": true }}`；内容提取是推荐项而非服务端默认，省略 `contents` 时结果只含元数据（标题、URL、日期），没有页面内容。
4. 把其他所有请求字段视为受控项：仅在用户任务明确需要时才添加，不要复述服务端默认值，也不要因为看起来有用就加控制项。
5. `type` 默认 `auto`，显式写 `type: "auto"` 可以，但除非任务需要（如延迟敏感的 UX 或深度综合）不要换其他模式。
6. `numResults` 默认 10，除非任务需要不同数量否则省略；只在有意的产品决策时设置，不要当模板。
7. 省略 `category`，仅在用户明确要求按类别约束检索时使用。
8. `includeDomains` 和 `excludeDomains` 仅在用户明确要求硬性允许/阻止列表并提供或批准内容时设置；来源偏好应通过查询措辞或 `systemPrompt` 表达。
9. `maxAgeHours` 仅在提取的页面内容必须最新时设置；它限制实时抓取前的缓存年龄，不是发布时效过滤器。
10. 对于“近期故事”类任务，把时效性写进查询（如 "latest"、"recent"）；`startPublishedDate` / `endPublishedDate` 是硬过滤器，会丢弃无日期和日期错误的页面，仅在任务明确要求必须强制的时间窗口（如 "from the last seven days"、"published in 2026"）时添加，不要用 `maxAgeHours`。
11. `highlights` 默认对所有任务设为 `true`，除非另有说明；没有明确预算要求不要加 `maxCharacters` 或其他 highlight 选项。
12. 按工作流形态选端点：需要原始网页内容给自己的 LLM 或 agent 用 `/search` 加推荐请求；需要特定输出结构或必须从页面提取/综合的字段用 `/search` 加 `outputSchema`（必要时加 `systemPrompt`）；长时间多步研究、列表构建或带结构化输出的信息丰富用 Agent API（`/agent`）。
13. 判断结构化输出请求：用户不必说 "JSON" 或 "schema"，像 "the funding amount each article reports"、"name, title, and company for each person"、或结果元数据只偶尔有的必需字段（如必需作者）都属于结构化输出请求；每个结果本来就有的字段（标题、URL、发布日期）不算，"10 articles with title and URL" 就是推荐请求加 `numResults`。紧凑 schema（每篇文章的作者和 URL）留在 `auto`；schema 宽或字段需要多次搜索填充时用 `type: "deep"`。
14. 默认优先搜索端点：大多数新集成用 `/search`，只有任务形态明确需要时才转向更专门的 Exa 表面。
15. 需要通用语义网页检索、综合输出或从搜索结果提取内容：用搜索端点 `/search`。
16. 已知 URL 且需要干净页面提取或新鲜度控制：用内容端点 `/contents`。
17. 需要与已知种子 URL 相关的页面：用搜索端点 `/search`，查询从该页面派生（如标题、主题或来自 `/contents` 的文本）。
18. 需要带引用的有依据答案且自己不做 LLM 生成：用答案端点 `/answer`；如果产品已有聊天 LLM，则把 `/search` 作为工具给它。
19. 需要 OpenAI SDK 直接替换兼容聊天或响应客户端：用 OpenAI 兼容端点（`/chat/completions`、`/responses`）。
20. 需要异步多步研究、列表构建、信息丰富或对先前研究的追问：用 Agent API（`/agent`）。
21. 需要带 webhook 投递的定时循环搜索：用 Monitors API（`/monitors`）。
22. 维护现有 Websets 集成：看迁移指南（`references/migrate-websets-to-agent.md`）并过渡到 Agent API（`references/agent.md`）；新工作不要用 Websets，改用 Agent API。
23. 需要页面在过去某时刻的内容（回测 agent、可复现评估、比较早期版本的文档、定价页、政策或文件）：用 Exa Snapshot，即 `/contents` 顶层或 `/search` 的 `contents` 内的 `snapshotAsOf` 字段，见 `references/snapshot.md`。
24. 避免装饰推荐请求：无明确任务需求就加 `category`、域名过滤、模板化 `numResults` 或新鲜度控制是最常见的集成错误。
25. 不要用裸搜索回答提取请求：必须从页面出来的字段，或用户要求每个结果都有的元数据字段，放进 `outputSchema`；保留/丢弃规则放进 `systemPrompt`；`query` 只表达检索意图。如果查询子句说 `only`、`include`、`exclude`、`drop` 或 `return`，它就放错了字段。每个结果本来就有的字段（标题、URL、发布日期）不要加 `outputSchema`。
26. 在搜索端点上，`text`、`highlights`、`summary` 属于 `contents` 内部，不是顶层。
27. 在内容端点上，`text`、`highlights`、`summary` 是顶层字段，不嵌套在 `contents` 内。
28. 在 `highlights`、`text`、`summary` 中只选一个，不要叠加；`summary` 需要用户明确要求 Exa 侧逐结果综合。
29. 几乎所有任务都用裸 `highlights: true`；`numSentences` 和 `highlightsPerUrl` 已弃用，`maxCharacters` 需要明确预算要求。
30. 列表构建和信息丰富工作流属于 Agent API（`/agent`），不要用 `/search` 加 `category: "people"` 或 `category: "company"`；这些类别只用于检索原始人物或公司文档。
31. `maxAgeHours` 控制抓取/缓存新鲜度（提取页面内容在实时抓取前可有多旧），不是发布时效；不要用它做“近期结果”控制，时效性属于查询措辞。`startPublishedDate` / `endPublishedDate` 用于任务明确说明且必须强制的时间窗口（"the last seven days"、"in 2026"），不单独用于 "recent" 或 "latest"。
32. 不要发明类别值如 `github`、`documentation`、`qa` 或 `pdf`；用户确实要求按类别约束检索时先查搜索参考：`people` 和 `company` 等专门类别会限制哪些过滤器有效。
33. OpenAI 兼容端点用于兼容优先场景；新集成想要更清晰的请求语义时优先用原生 Exa 端点。
34. 不要把 `/agent` 当作 `/search` 的直接替代；它延迟更高且异步，当工作流形态真正匹配时用专门的 Agent 参考。新集合构建工作优先用它而非 Websets。
35. Agent 请求应始终显式设置 `effort`，通过轮询或 SSE 等待终态并在读取 `output` 前检查运行如何结束，产品中相关时暴露 `output.grounding`。
36. 把 `/findSimilar` 视为已弃用；相关页面发现优先用 `/search`（可选先对种子 URL 用 `/contents`）。
37. 参考文件按主题查阅：`references/search.md`（搜索端点请求/响应、搜索类型、过滤器、嵌套 contents、结构化输出）、`references/contents.md`（内容端点提取、新鲜度、状态、顶层内容字段）、`references/snapshot.md`（Exa Snapshot 历史页面版本、限制、快照 vs 新鲜度）、`references/answer.md`（带引用和结构化输出的有依据答案生成）、`references/agent.md`（Agent API 异步多步研究、信息丰富、结构化输出、轮询和事件）、`references/openai-compat.md`（OpenAI 兼容端点、模型路由、`extra_body` 用法）、`references/monitors.md`（独立 Monitors API 定时循环搜索）、`references/migrate-websets-to-agent.md`（Websets 迁移到 Agent API）、`references/sdks.md`（Python 和 TypeScript SDK 命名、方法、形态差异）、`references/http-requests.md`（各主要 Exa 表面的最小原始 HTTP 示例）、`references/models-and-modes.md`（搜索类型选择、答案/研究模型路由、延迟权衡）、`references/prompting-and-patterns.md`（持久查询、提示、新鲜度和输出 schema 模式）、`references/common-mistakes.md`（过度指定和参数形态修正）。
38. 查阅权威文档：文档首页 `https://exa.ai/docs`、文档索引 `https://exa.ai/docs/llms.txt`、搜索参考 `https://exa.ai/docs/reference/search`、Agent API 指南 `https://exa.ai/docs/reference/agent-api-guide`、Exa Connect 概览 `https://exa.ai/docs/reference/agent-api/connect/overview`、Exa Snapshot `https://exa.ai/docs/search/snapshot`、Python SDK 规范 `https://exa.ai/docs/sdks/python-sdk-specification`、TypeScript SDK 规范 `https://exa.ai/docs/sdks/typescript-sdk-specification`。

适用边界 · 注意事项

• 不依赖 Exa API 或不想使用其付费服务时。
• 需要 Zero Data Retention 但工作流必须用 Websets 或 Monitors 时（它们不支持 ZDR）。
• 只是做通用 LLM 聊天而不需要网页检索、内容提取或研究能力时。