TavilyでAIアプリにWeb検索を組み込む方法

TavilyをAI appへ組み込むときは、Search resultとsource URLを保持し、LLMが根拠を追える形で渡します。基本は「query→検索→結果の絞り込み→LLM回答→source提示」で、API keyはserver側に置きます。

Request設計

表は横にスクロールできます

Field / control	用途	初期判断
query	検索する質問	questionを検索語として明確化
search_depth	basic / advanced等	basicで開始し必要なqueryだけ強化
max_results	取得件数	必要な根拠に絞る
topic / date filter	news、finance、期間等	求める鮮度に合わせる
include_answer	Tavily側のanswerを含める	自前LLMと役割を決める
include_usage	credit使用量	costを記録する

Tavily Search APIはREST、Python SDK、JavaScript SDKから利用でき、既定のmax_resultsは10、0〜20の範囲で指定できると資料にあります。設定可能値は実装時にAPI referenceで確認します。

検索結果をLLMへ渡す

1. User questionから検索queryを作る。

2. 必要ならtopicとdate条件を指定する。

3. result title、content / snippet、URLをひとまとまりで保持する。

4. 重複・無関係なresultを除き、必要なsourceだけLLM contextへ渡す。

5. 回答には使ったsource URLを含める。

6. include_usageでcreditを記録する。

API keyをserver environmentで管理し、browserへ返すresponseや公開repositoryへ混ぜません。productionの検索語に個人情報を含めるか、request logに何を保存するかも確認します。

Failure Path

表は横にスクロールできます

Failure	対応
401	key / permissionを確認し、secretをlogに出さない
429	rate limitとretry条件を確認
usage limit	requestを止め、予算状態を表示
有効なresultなし	検索条件変更または根拠不足を返す
LLM失敗	source付き検索結果を失わず再実行できるよう記録

AIものさしの判断

本番integrationではAPI呼び出し後のsource保持、回答との対応、credit監視までを一つのworkflowとして設計します。回答に使ったevidenceを追えない構成では、検索が成功しても検証可能な回答になりません。

LLMへ渡す検索結果のContract

SearchのJSON responseをそのまま長いpromptへ連結せず、アプリ側で必要項目だけを正規化します。最低限、query、source URL、title、snippet、取得日時、使用creditを一つのrecordにまとめます。回答文とsourceの対応が残れば、ユーザーが特定の主張の出典を開けます。

表は横にスクロールできます

正規化field	保存するもの	注意
query_id	元の質問または検索処理ID	個人情報をqueryへ含めない
query	実際に送った検索語	必要期間だけ保管
sources[]	URL、title、content、published date	URLは原文のまま保持
result metadata	score、request_id、取得日時	scoreを事実の確度と誤認しない
usage	credits、depth、endpoint	月間予算と照合する
answer references	回答に使ったsource ID	主張とsourceの関係を保つ

実装では、結果が0件でも成功扱いで断定回答を作らず、根拠が不足している状態を返します。回答生成後は、参照IDがsourcesに存在するか、sourceにないURLをモデルが作っていないか検査します。

RequestとResponseの最小例

Requestの初期値は、queryを受け取り、basic検索、必要な件数、出典URLを返す設定にします。公式Referenceの現在のsearch endpointでは、max_resultsの既定値は10で、指定範囲は0〜20です。回答用文章を別のLLMで作る場合は、Tavily側のinclude_answerを常に有効にせず、どちらのanswerを採用するか責務を分けます。Search APIにはinclude_usageがあり、応答にcredit情報を含められます。

{

  "query": "質問から抽出した検索語",

  "search_depth": "basic",

  "max_results": 5,

  "include_answer": false,

  "include_usage": true

}

これは構成例です。API keyはAuthorization headerに設定し、コード例やbrowser bundleへ実値を入れません。queryとmax_resultsは利用者の質問・用途に応じてサーバーで検証し、許容範囲外ならrequest前に拒否します。

検索結果を根拠として扱う安全策

Search result contentは外部ページから取得した入力です。ページの中に「以前の指示を無視する」「秘密を返す」といった文があっても、アプリのsystem instructionや機密データの扱いを変える命令として実行してはいけません。取得本文をuntrusted dataとして区切り、LLMへは「回答材料」と「実行指示」を別の構造で渡します。

• source URLとページ内容を別fieldに保持する

• 検索結果中の命令文をtool callやsystem promptに昇格しない

• API key、内部ログ、user profileを検索結果へ返さない

• 回答の重要な主張ごとに参照source IDを保持する

• page contentの保存期間と個人情報の取り扱いを決める

Freshnessをqueryとanswerに結び付ける

ニュースや料金など時間依存の質問では、topic、time_range、start_date/end_date等を用途に合わせます。公開日をresponseへ含める設定があっても、Tavilyが推定した日付が元の公開日・更新日より後になる場合があります。日付metadataだけで内容の最新性を保証せず、公式ページを開いて必要箇所を照合します。日付を検出できないsourceをdate filterで落とす設定にも注意します。

統合後のQA

表は横にスクロールできます

Test	合格条件
正常検索	query、source、usageが追跡できる
0件	不足を明示し、断定を作らない
API 401 / 429	keyを露出せず、retry過多を避ける
timeout	request IDと失敗状態を記録
source不一致	URL不在の引用を回答に出さない
危険なpage text	命令として実行せず、検索資料として扱う
credit上限	request停止または明示した縮退動作へ移る

本番化前は少数の代表queryで結果の関連性、source表示、credit記録を確認し、ログに必要以上の個人情報を残していないかも点検します。

再試行・重複実行を制御する

timeout時に、API側でrequestが完了していたか分からないまま無制限に再送すると、同じ検索のcreditを重ねて消費する可能性があります。最初に設定したtimeout、retry回数、backoff、利用上限を記録し、429や一時的な5xxだけを再試行対象にします。401、入力validation error、上限到達は、同じrequestを繰り返す前に原因を直します。

表は横にスクロールできます

状態	次の処理
400 / 422	queryやparameterを検証し、同じpayloadを再送しない
401	server側のkey設定と権限を確認し、値はlogに出さない
429	Retry-After等の現在の応答条件を確認し、上限付きで待つ
432 / usage limit	dashboardの予算を確認し、勝手に別keyへ逃がさない
timeout	request IDや記録を探し、再実行が必要か判断する

重複queryが多い用途なら、query分類とsource freshnessに応じたcacheを設計できます。料金ページやニュースなど更新が速い情報を長期間cacheせず、cache hitにも取得日を付けます。個人情報を含むqueryを共有cacheへ保存するかは、privacy要件から個別に判断します。

失敗時にユーザーへ返す内容

検索失敗、source不足、LLM失敗を一つの「回答できません」にまとめないでください。検索APIが失敗したのか、検索結果がないのか、結果はあるが根拠の十分性を判定できないのかを分けます。利用者が（新しいタブで開く）次に入力を変えるべきか、時間を置くべ（新しいタブで開く）きか、公式情報を直接見るべきかが分かる案内を（新しいタブで開く）返します。

公開前に、sourceを失わず結果を再表示できるか、予算上限でrequestが止まるか、secretがclientへ流れないかをテストします。検索機能の成功は、引用可能な回答ができたことと同じではありません。