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 は Zero Data Retention（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 は、日付のないページや日付が誤っているページを除外する厳密なフィルターです。「過去 7 日間」「2026 年に公開」のように、適用必須の期間がタスクで指定されている場合にのみ追加してください。maxAgeHours は使用しないでください。
• 特に指定がない限り、すべてのタスクで highlights はデフォルトで true に設定してください。タスクで予算が明示的に必要とされない限り、maxCharacters やその他のハイライトオプションは追加しないでください。

API の選択ワークフロー

エンドポイントを選ぶ前に、どのワークフローの形が適しているか判断してください。

• 独自の LLM やエージェントで使う生のウェブコンテンツ：上記で推奨したリクエストを使って /search を使用します
• 特定の出力形式、またはページから抽出・合成する必要があるフィールド：/search を使用し、outputSchema を追加します（動作の指針が必要な場合は systemPrompt も追加します）。ユーザーが「JSON」や「スキーマ」と言う必要はありません。「各記事が報じている資金調達額」、「各人物の氏名、役職、会社名」、あるいは結果メタデータに時折しか含まれない必須フィールド（必須の著者名）は、いずれも構造化出力のリクエストです。タイトル、URL、公開日など、すべての結果にすでに含まれているフィールドは該当しません。「タイトルと URL を含む記事を 10 件」というリクエストには、推奨される numResults を使ったリクエストを使用します。記事ごとの著者名と URL のような簡潔なスキーマでは auto のままにします。スキーマの幅が広い場合や、フィールドを埋めるのに複数回の検索が必要な場合は、複数回実行されるため、type: "deep" を使用します。references/search.md の「構造化出力」を参照してください。
• 構造化出力を伴う、長時間の複数ステップのリサーチ、リスト作成、または情報拡充：Agent API（/agent）を使用し、フィールドには同じ outputSchema のルールを適用します

デフォルトでは検索エンドポイントを使用してください。 ほとんどの新しい統合では検索エンドポイント（/search）を使用し、タスクの形状から明確に必要だと判断できる場合にのみ、より専門的な Exa の機能へ移行してください。

1. 一般的な意味ベースのウェブ検索、合成された出力、または検索結果からのコンテンツ抽出が必要：検索エンドポイント（/search）を使用します
2. URL がすでにわかっており、ページのクリーンな抽出や鮮度の制御が必要：contents エンドポイント（/contents）を使用します
3. 既知のシード URL に関連するページが必要：ページから取得した情報（たとえば、タイトル、トピック、または /contents のテキスト）を基にクエリを作成し、検索エンドポイント（/search）を使用します
4. 根拠に基づいた回答と引用が必要で、生成を行う独自の LLM がない：answer エンドポイント（/answer）を使用します。製品にチャット用 LLM がすでにある場合は、ツールとして /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. 過去の日時時点のページコンテンツが必要（エージェントのバックテスト、再現可能な評価、ドキュメント、価格ページ、ポリシー、または提出書類の過去バージョンとの比較など）：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);
}

Raw 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内に指定します。
• contentsエンドポイントでは、text、highlights、summaryはcontents内にネストせず、トップレベルに指定します。
• highlights、text、summaryのいずれか1つを選んでください。重ねて指定しないでください。summaryは、結果ごとの要約をExa側で生成するようユーザーが明示的に求めている場合に必要です。
• ほとんどのタスクでは、指定なしのhighlights: trueを使ってください。numSentencesとhighlightsPerUrlは非推奨であり、maxCharactersには明示的な予算要件が必要です。
• リスト作成や情報拡充のワークフローには、category: "people"やcategory: "company"を指定した/searchではなく、Agent API（/agent）を使ってください。これらのカテゴリは、人や企業に関する生のドキュメントを取得する場合にのみ使います。
• maxAgeHoursはクロール／キャッシュの鮮度、つまり抽出されたページコンテンツがライブクロールされるまでの経過時間を制御するもので、公開時期の新しさを制御するものではありません。「最近の結果」を指定するために使わないでください。新しさはクエリの表現で指定します。startPublishedDate／endPublishedDateは、「過去7日間」や「2026年」のように、タスクで指定され、適用が必須の期間を対象とします。「最近」や「最新」だけを指定する場合には使いません。
• github、documentation、qa、pdfなどのカテゴリ値を決して作り出さないでください。ユーザーがカテゴリを指定した検索を求めた場合は、まず検索リファレンスを確認してください。peopleやcompanyなどの特化カテゴリでは、使用できるフィルターが制限されます。
• OpenAI互換エンドポイントは、互換性を最優先するユースケース向けです。新しい統合では、リクエストの意味がより明確なネイティブのExaエンドポイントを優先してください。
• /agentを/searchの単純な置き換えとして扱わないでください。レイテンシーが高く非同期のため、ワークフローの形が本当に適している場合は、専用のAgentリファレンスを使用してください。新しいコレクション作成では、Websetsより/agentを優先してください。
• Agentリクエストでは、常にeffortを明示的に設定してください。ポーリングまたはSSEで終端状態まで待機し、outputを読み取る前に実行の終了状態を確認してください。製品で関連性がある場合は、output.groundingを公開してください。
• /findSimilarは非推奨として扱ってください。関連ページの検索には、（シードURLに対して必要に応じて/contentsを実行した後に）/searchを優先してください。

参考ファイル

ファイル	トピック
references/search.md	Search エンドポイントのリクエスト／レスポンス形式、検索タイプ、フィルター、ネストされたコンテンツ、構造化出力
references/contents.md	Contents エンドポイントによる抽出、鮮度、ステータス、トップレベルのコンテンツフィールド
references/snapshot.md	Exa Snapshot：/contents と /search における snapshotAsOf による過去のページバージョン、制限、スナップショットと鮮度の違い
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
• Search リファレンス：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