build-with-exa

使用 Exa 构建

范围

默认包含：

• 核心检索 API：搜索端点、内容端点、答案端点
• 长时间运行的研究工作流：Agent API（/agent）
• 异步和定期工作流：Monitors API
• 旧版功能：Websets API（仅用于现有集成；新的集合构建工作使用 Agent API）
• 历史内容：Exa Snapshot（搜索和内容端点上的 snapshotAsOf）
• SDK 指南：Python exa-py、TypeScript exa-js

数据保留说明：/search、/contents、/answer 和 /agent 支持零数据保留（ZDR）。Websets 和 Monitors API（/monitors）不支持 ZDR。如果用例要求 ZDR，请使用支持 ZDR 的功能，或联系 Exa。

安装

# Python
pip install exa-py

# TypeScript / JavaScript
npm install exa-js

使用包管理器安装最新 SDK 版本，以确保解析到最新版本并使用所有 SDK 功能。

身份验证

export EXA_API_KEY="your_api_key_here"

Exa 接受 x-api-key 标头或 Authorization: Bearer <key>。

推荐的 Exa 搜索请求只包含查询和令牌高效的内容提取，不包含其他内容。内容提取是一项建议，而非服务器默认行为：省略 contents 时，结果仅包含元数据（标题、URL、日期），不包含页面内容。

{
  "query": "latest developments in LLMs",
  "type": "auto",
  "contents": { "highlights": true }
}

其他每个请求字段都需要按需启用：只有当用户的任务明确要求时，才添加该字段。 不要重复声明服务器默认值，也不要因为某些控制项看起来可能有用就添加它们。具体来说：

• type 默认为 auto；可以显式指定 type: "auto"，但除非任务有要求（例如对延迟敏感的 UX 或深度综合），否则不要发送其他模式。
• numResults 默认为 10；除非任务要求不同的结果数量，否则省略 numResults。只有在明确的产品决策下才设置该字段，不要将其作为样板配置。
• 省略 category。只有当用户明确要求按类别限制检索时才使用它。
• 只有当用户明确要求设置硬性允许列表或阻止列表，并提供或批准其内容时，才设置 includeDomains 和 excludeDomains。应通过查询措辞或 systemPrompt 表达来源偏好。
• 只有当提取的页面内容必须是最新内容时，才设置 maxAgeHours。它会在实时抓取前限制缓存时长；它不是发布日期过滤器。
• 对于“近期新闻”任务，应在查询中注明时效要求（“最新”“近期”）。startPublishedDate / endPublishedDate 是硬性过滤条件，会排除未标注日期和日期不准确的页面；只有当任务要求强制限定时间范围（“过去七天内”“于 2026 年发布”）时才添加。不要随意使用 maxAgeHours。
• 除非另有说明，所有任务默认都应将 highlights 设为 true。除非任务明确要求限制预算，否则不要添加 maxCharacters 或其他摘要选项。

API 工作流选择

选择端点前，先确定适合的工作流形式：

• 为自己的大模型或 Agent 获取原始网页内容：使用 /search，并采用上面的推荐请求
• 需要特定输出格式，或需要从页面中提取或综合字段：使用 /search 并添加 outputSchema（如果需要行为指导，也添加 systemPrompt）。用户不必明确说“JSON”或“schema”；“每篇文章报道的融资金额”、“每个人的姓名、头衔和公司”，或结果必须包含但元数据有时才会提供的字段（例如必需的作者）都属于结构化输出请求。每条结果本来就包含的字段（标题、URL、发布日期）则不属于：“10 篇包含标题和 URL 的文章”是使用 numResults 的推荐请求。紧凑的 schema（每篇文章的作者和 URL）使用 auto；如果 schema 较宽，或其字段需要多次搜索才能填充，则使用 type: "deep"，因为它会运行多次搜索。参见 references/search.md 中的结构化输出。
• 需要长时间运行的多步骤研究、列表构建或结构化输出的丰富处理：使用 Agent API（/agent），其字段遵循相同的 outputSchema 规则

默认使用搜索端点。 对于大多数新的集成，请使用搜索端点（/search），只有当任务形式明显需要时，才改用更专业的 Exa 接口。

1. 需要通用语义网页检索、综合输出或从搜索结果中提取内容：使用搜索端点（/search）
2. 已知 URL，需要提取清晰的页面内容或控制内容时效性：使用内容端点（/contents）
3. 需要查找与已知种子 URL 相关的页面：使用搜索端点（/search），并根据页面内容构造查询（例如标题、主题或 /contents 中的文本）
4. 需要带引用的可靠答案，且不使用自己的大模型生成内容：使用答案端点（/answer）。如果产品已有聊天大模型，则将 /search 作为工具提供给它。
5. 需要从代码仓库、文档和 Stack Overflow 中进行代码检索：使用搜索端点（/search）
6. 需要与 OpenAI SDK 即插即用地兼容聊天或响应客户端：使用 OpenAI 兼容端点（/chat/completions、/responses）
7. 需要异步多步骤研究、列表构建、丰富处理，或针对先前研究进行后续提问：使用 Agent API（/agent）
8. 需要通过 webhook 定时执行重复搜索：使用 Monitors API（/monitors）
9. 维护现有的 Websets 集成：参见迁移指南（references/migrate-websets-to-agent.md），并迁移至 Agent API（references/agent.md）。新项目不要使用 Websets；请改用 Agent API。
10. 需要获取某个过去时间点的页面内容（用于回测 Agent、可复现评估、比较文档、定价页面、政策或申报文件的早期版本）：使用 Exa Snapshot，即 /contents（顶层）或 /search（在 contents 内）中的 snapshotAsOf 字段。参见 references/snapshot.md。

快速开始

更多示例请参见下表中的相关参考文件。

Python（/search）：

from exa_py import Exa

exa = Exa(api_key="YOUR_EXA_API_KEY")
result = exa.search(
    "latest developments in LLMs",
    type="auto",
    contents={"highlights": True}
)

for item in result.results:
    print(item.title, item.url)

TypeScript（/search）：

import Exa from "exa-js";

const exa = new Exa();
const result = await exa.search("latest developments in LLMs", {
  type: "auto",
  contents: { highlights: true }
});

for (const item of result.results) {
  console.log(item.title, item.url);
}

原始 HTTP（/search）：

curl -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "contents": {
      "highlights": true
    }
  }'

关键注意事项

• 不要无故修饰推荐请求。添加 category、域名筛选条件、模板化的 numResults 或时效性控制，是最常见的集成错误。
• 不要用单纯搜索来回答信息提取请求。必须从页面中提取的字段，或用户要求每条结果都包含的元数据字段，应放在 outputSchema 中；保留或剔除规则应放在 systemPrompt 中；query 仅表示检索意图。如果查询中的某个条款包含 only、include、exclude、drop 或 return，说明它放错了字段。对于每条结果都已包含的字段（标题、URL、发布日期），不要添加 outputSchema。
• 在搜索端点中，text、highlights 和 summary 应放在 contents 内，而不是顶层。
• 在内容端点中，text、highlights 和 summary 是顶层字段，不应嵌套在 contents 内。
• 在 highlights、text 或 summary 中任选一个，不要叠加使用。summary 仅适用于用户明确要求由 Exa 对每条结果进行综合摘要的情况。
• 几乎所有任务都应使用简单的 highlights: true。numSentences 和 highlightsPerUrl 已弃用；只有在明确要求字符数预算时，才使用 maxCharacters。
• 构建列表和信息补充工作流应使用 Agent API（/agent），而不是在 /search 中使用 category: "people" 或 category: "company"。这些类别仅用于检索原始人物或公司文档。
• maxAgeHours 控制抓取/缓存的新鲜度（提取的页面内容在实时抓取前可以有多旧），不控制发布日期的新近程度。不要将它用作“近期结果”控制项；新近程度应通过查询措辞表达。startPublishedDate / endPublishedDate 用于任务明确规定且必须强制执行的时间范围（如“过去七天”“在 2026 年”），而不是单独用于“近期”或“最新”。
• 切勿臆造 github、documentation、qa 或 pdf 等类别值。如果用户确实要求按类别限制检索，请先查看搜索参考：people 和 company 等专用类别会限制哪些筛选条件有效。
• OpenAI 兼容端点适用于优先考虑兼容性的用例。对于希望请求语义更清晰的新集成，优先使用 Exa 原生端点。
• 不要将 /agent 视为 /search 的直接替代品。它的延迟更高且采用异步模式，因此只有当工作流形态确实适合时才使用，并参阅专门的 Agent 文档。对于新的集合构建工作，优先使用它而非 Websets。
• Agent 请求应始终显式设置 effort；通过轮询或 SSE 等待终止状态，并在读取 output 前检查运行结果；在产品中适用时，应展示 output.grounding。
• 将 /findSimilar 视为已弃用。对于相关页面发现，优先使用 /search（可选在种子 URL 上先调用 /contents）。

参考文件

文件	主题
references/search.md	搜索端点的请求/响应结构、搜索类型、筛选条件、嵌套内容、结构化输出
references/contents.md	Contents 端点的提取、时效性、状态、顶层内容字段
references/snapshot.md	Exa Snapshot：snapshotAsOf 在 /contents 和 /search 上用于获取历史页面版本、限制、快照与时效性
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	经久适用的查询、提示词、时效性和输出模式
references/common-mistakes.md	过度指定和参数结构修正

权威文档

• 文档主页：https://exa.ai/docs
• 文档索引：https://exa.ai/docs/llms.txt
• 搜索参考：https://exa.ai/docs/reference/search
• Agent API 指南：https://exa.ai/docs/agent/quickstart
• Exa Snapshot：https://exa.ai/docs/search/snapshot
• Exa Connect 概览：https://exa.ai/docs/agent/connect/quickstart
• Python SDK 规范：https://exa.ai/docs/sdks/quickstart
• TypeScript SDK 规范：https://exa.ai/docs/sdks/quickstart