WebSearch

一行サマリ

Agent(..., builtin_tools=[WebSearchTool()]) を渡すだけで、Gemini が 必要に応じて Google 検索を実行し、結果を踏まえた回答 を返すようになる。LLM の "知識のカットオフ" を超えた最新情報を扱える。

ヒーロー: 知識カットオフ vs リアルタイム検索

学習データには「カットオフ日付」があり、それ以降の出来事を LLM 単体は知りません。WebSearchTool を有効化すると、Gemini が 「この問いには検索が必要」と判断したときに自動で Google を叩き、結果を踏まえて答えてくれます。

概念: 何ができて、何ができないか

WebSearchTool は provider 共通の builtin tool で、各プロバイダ (Google / OpenAI / Anthropic) が ネイティブの検索機能を持っていれば 自動で使われます。Gemini なら Google Search Grounding に解決されます。

Gemini の WebSearch は "細かい設定なしで丸ごと使う" 設計。細やかな制御が必要な場合は OpenAI/Anthropic を選ぶか、自前の @agent.tool で httpx から検索 API を叩く方針を検討します。

コード: 3 つのパターン

パターン 1: 最小コード — 1 行で有効化

from pydantic_ai import Agent, WebSearchTool
 
agent = Agent(
    'google-gla:gemini-3-flash-preview',
    builtin_tools=[WebSearchTool()],
    instructions='短い日本語で答えてください。情報源があれば末尾に併記してください。',
)
 
# LLM は「これは最新情報が要る」と判断したら検索を実行する
result = agent.run_sync('2026 年 5 月時点の最新の Python 安定版バージョンは?')
print(result.output)

ポイント:

• builtin_tools=[WebSearchTool()] を渡すだけ。インスタンス化に引数は不要
• LLM は 問いを見て検索が要るか自動判断。「日本の首都は?」のような知識ベースで答えられる質問では検索を呼ばない
• instructions で「情報源を併記」と促すと、LLM が出典 URL を文末に書いてくれることがある

パターン 2: 検索結果を踏まえた構造化出力

output_type と組み合わせて、検索結果を 後続処理に使える構造化データ に整形できます。

from pydantic import BaseModel
from pydantic_ai import Agent, WebSearchTool
 
class TechSummary(BaseModel):
    topic: str
    key_points: list[str]
    sources: list[str]  # URL
 
agent_t = Agent(
    'google-gla:gemini-3-flash-preview',
    builtin_tools=[WebSearchTool()],
    output_type=TechSummary,
    instructions=(
        'ユーザーの問いを検索で調べ、要点と出典 URL を構造化してください。'
        'sources は実際の URL のみ (推測を含めない)。'
    ),
)
 
result = agent_t.run_sync('FastAPI の最新バージョンの主な変更点を教えて')
print(f'topic: {result.output.topic}')
for p in result.output.key_points:
    print(f'  - {p}')
print('\nsources:')
for url in result.output.sources:
    print(f'  {url}')

注意: 仕様上、Gemini で WebSearchTool を使うとき @agent.tool で定義した自作 function tools は併用できません。複合的な処理が必要な場面では、検索専用 Agent + 別 Agent の Multi-Agent (Ch8) で分割するのが定石。

パターン 3: いつ検索が呼ばれたかを履歴で確認

メッセージ履歴から「LLM が検索を実行したか」を観察できます。

result = agent.run_sync('Gemini 3 のリリース日はいつ?')
print('--- メッセージ履歴 ---')
for msg in result.all_messages():
    print(f'kind: {msg.kind}')
    for part in msg.parts:
        # builtin tool の呼び出し痕跡が含まれる
        kind = type(part).__name__
        print(f'  {kind}')

builtin tool の呼び出しは内部的に発生するため、all_messages() にその痕跡が残ります。

いつ WebSearch を使うか

まとめ

• Agent(..., builtin_tools=[WebSearchTool()]) 1 行で Google Search grounding が有効化
• LLM が検索が必要と判断したときだけ呼ばれる (静的な知識では呼ばれない)
• Gemini では function tools と併用不可 + 検索パラメタ非対応
• 時事情報・最新版の質問に強くなるが、コスト増 / 結果の正確性は別途検証必要

次レッスンでは Gemini 3 固有の Thinking (thinking_level) — 推論ステップの深さを制御する設定を扱います。