Pydantic AI、You.com の検索機能を新機能として追加

Pydantic AI Harness に、You.com 由来の新しい Web 検索機能「YouSearch」と「YouResearch」が追加されました。両方ともリアルタイムで LLM が直接ウェブにアクセスできる API を提供し、エージェントワークフローのための深掘り調査を可能にします。

5 つの API で 2 つの主要機能を担います。「YouSearch」は情報収集と読解に、「YouResearch」は単一の検索では答えられない複雑な問いに対応します。

• Capability：API / What it does
• YouSearch()：Web Search / リアルタイムのウェブおよびニュース結果を返す。各結果にはクエリに関連する抜粋や、全文の Markdown が付随します。
• YouSearch()：Contents / URL から HTML または Markdown 形式で、きれいに整形された全文コンテンツを取得します。
• YouResearch()：Answer / 1 つの呼び出しで、出典に基づいた統合された回答を返します。すべての引用元は回答が返される前にソーステキストと照合され検証されます。You.com の SimpleQA ベンチマークでは p50 が 2.67 秒、精度は 93.48% を記録しています。
• YouResearch()：Research / ステップを跨ぐ調査を実行し、出典付きの明確な回答を返します。軽量から徹底的まで、作業レベルを選択可能です。
• YouResearch()：Finance Research / 提出書類、議事録、アナリストレポート、財務諸表など、専用の金融インデックスを対象にした多段階調査を行います。

各機能の詳細と、エージェントがユーザーに代わってウェブ閲覧を開始する前に設定すべき内容について解説します。

#2 つのエージェント、同じ質問、入力トークン数は 8 倍

両者の違いを比較するため、2 つのエージェントに同一のプロンプトを実行しました。その問いとは「トロイオンスあたりの銀の最新価格はいくらか」です。

以下のコードを含む gist があります。実行するには、以下の手順に従ってください。本記事では、この gist に示されたコードの解説を行います。

今回の例では、軽量エージェントは 3 つの結果を取得する単一の検索を実行し、文字数は 2,000 字に制限されます。コストは約 0.01 ドルです。一方、徹底型エージェントは 8 つの結果を取得し、full_page を使用します。これは PrefixTools でラップされた 2 回目の検索で、ユーザーが指定した 2 つのドメインに固定されています。また、YouResearch は構造化された要約を返します。コストは約 0.13 ドルです。両者とも「価格」と「日付」の 2 つのフィールドを返し、これらは 1 つの Logfire スパンの下にネストされるため、請求書はトレースツリーからそのまま読み取ることができます。

始め方

必要なライブラリをインストールすることから始めましょう。ここではエージェントフレームワークとして Pydantic AI を、観測層として Pydantic Logfire を、モデルプロバイダーとして Anthropic を使用しています。

uv add "pydantic-ai-harness[youdotcom,anthropic]" "pydantic-ai-slim[logfire]"

you.com/platform でアクセスキーを、モデルプロバイダーのキーを作成してください。両方を以下のようにエクスポートします。

export YDC_API_KEY='your-you-com-api-key'

export PYDANTIC_AI_GATEWAY_API_KEY='your-gateway-api-key'

今回の例では、モデルプロバイダーとして Pydantic AI Gateway を使用し、PYDANTIC_AI_GATEWAY_API_KEY を設定しています。キーを設定するには、Logfire でゲートウェイを有効にし、以下の動画に示されているように「API Keys」タブをクリックしてください。独自のキー（BYOK: Bring Your Own Key）を使用してカスタムプロバイダーを設定することもできますし、Logfire の組み込みプロバイダーからキーを作成することも可能です。これにより、モデルのシームレスな切り替えや支出上限の設定、キーまたはプロジェクトごとの予算割り当てなどが可能になります。

また、モデルプロバイダーの API キーを直接使用することも可能です（この場合は ANTHROPIC_API_KEY を利用）。その際、Agent の文字列を 'anthropic:claude-sonnet-5' に置き換えるか、あるいは任意の他のモデルを指定してください。

import logfire
from pydantic_ai import Agent
from pydantic_ai_harness import YouResearch, YouSearch

logfire.configure()
logfire.instrument_pydantic_ai()

lean_agent = Agent('gateway/anthropic:claude-sonnet-5', capabilities=[YouSearch(), YouResearch()])

result = lean_agent.run_sync('What is the latest price of silver?')
print(result.output)

この例ではリストの 1 つのエントリが返され、エージェントはウェブ検索を実行できます。capabilities=[YouSearch(), YouResearch()] を指定するだけで、ツールや指示、設定が自動的に連携して構成されています。

次に、これをアンケート形式に変換するための設定を追加します。

import logfire
from pydantic import BaseModel, ConfigDict, Field
from pydantic_ai import Agent
from pydantic_ai_harness import YouSearch

logfire.configure()
logfire.instrument_pydantic_ai()

class SilverBrief(BaseModel):
    model_config = ConfigDict(extra='forbid')

spot_price_usd_per_oz: float
    as_of: str = Field(description='The date and source the quoted price is from.')

lean_agent = Agent(

'gateway/anthropic:claude-sonnet-5',

instructions='Answer with the spot price and its date only. Do not explain what moved it.',

output_type=SilverBrief,

capabilities=[

YouSearch(

num_results=3,

extraction_mode='highlights',

max_text_chars=2_000,

freshness='week',

)

],

)

result = lean_agent.run_sync('What is the latest price of silver per troy ounce?')

print(result.output.spot_price_usd_per_oz)

このエージェントが読み込める情報の量は、3 つの設定によって制限されています。num_results=3 はデフォルトの 10 から検索結果数を減らし、extraction_mode='highlights' はページ全体ではなくクエリに関連する抜粋のみを返します。また、max_text_chars=2_000 は戻ってきたテキストを 2,000 文字に切り捨てます（デフォルトは 10,000 文字）。これらの設定により、どんな質問であっても 1 回の呼び出しで読み込めるウェブテキストの上限は 6,000 文字（3 × 2,000）となります。さらに freshness='week' を指定することで、1 週間前の価格情報は結果から除外されます。

output_type=SilverBrief は、返答の形式を Pydantic の BaseModel に設定します。これにより、指定された内容に基づいて浮動小数点数と日付文字列が得られます。ただし、これは読み込み処理の量そのものを変えるものではありません。両方のケースで返されるフィールドは同じ 2 つですが、詳細な実行ではより多くの入力が必要となり、コストも高くなります。

#Setting that decides how much text comes back

web_search のデフォルトは extraction_mode='highlights' に設定されており、各結果が抜粋として届くため、8 つのソースを確認してもコストを抑えられます。その後、モデルは get_page を使用してどのページを読むかを選択します。もし最初からマークダウン形式で全文を取得したい場合は、extraction_mode='full_page' に切り替えてください。

どちらのツールから取得したフルページのテキストも、max_text_chars で上限が設定されています。この制限により、文書の先頭部分が保持され、通常はページ冒頭に重要な情報が含まれるためです。また、モデルがページの一部しか持っていないことを認識できるよう、[... page text truncated at N characters] というマーカーが付加されます。num_results は、You.com へのリクエスト時とレスポンス時の両方で適用されます。

結果が空であることは失敗ではありません。一致するクエリがない場合、モデルは「{query!r}」に対して「No results found for {query!r}.」というメッセージをユーザーに返すか、検索の再試行のためにクエリを書き換えるために使用します。実際に問題となるのは ModelRetry です。これはレート制限、空の結果となった URL、You.com が拒否したパラメータ、一時的なネットワーク障害などが原因で発生します。この場合、実行は継続され、モデルは再度挑戦する機会を得ます。一方、認証エラー、課金エラー、権限エラーは即座に停止されます。これらはユーザー側で修正すべき問題であり、再試行しても解決しないからです。

検索と、その難易度について

1 回の呼び出しで回答が得られると予想される質問には answer を使用し、複数の検索が必要でそれらを統合する必要がある場合は research を使用します。finance_research は、金融分析に特化して調整された同じループです。

研究タスクは結果を待機するのではなくジョブとして返却され、ポーリングを行うため、デフォルトのタイムアウトは 10 分（timeout_ms）に設定されています。リソース投入量は「lite」「standard」「deep」「exhaustive」から選べる research_effort で各機能ごとに個別に指定できます。

You.com にはさらにフロンティアレベルの機能もありますが、これはバックグラウンドジョブとしてのみ動作するため、本稿では対象外としています。金融分野の研究（finance_research）については独自の finance_effort（「deep」または「exhaustive」）を指定します。

構造化されたレポート出力を得るには、研究機能に JSON スキーマを渡す必要があります：

from pydantic import BaseModel, ConfigDict
from pydantic_ai_harness import YouResearch

class SupplierRisk(BaseModel):
    model_config = ConfigDict(extra='forbid')

supplier: str
exposure: str
sources: list[str]

YouResearch(
    research_effort='deep',
    output_schema=SupplierRisk.model_json_schema(),
)

extra='forbid' を指定しないと、You.com はスキーマを拒否します。同様に、余分なキーを受け付けないように閉じたスキーマのみが許可されます。この設定により、生成される JSON に additionalProperties: false が追加されます。これを省略すると、数分後に最初の研究呼び出しでモデル側からバリデーションエラーが返されます。

もう一つのルールはより早期にチェックされ、You.com は「lite」の努力レベルに対してスキーマを拒否します。この組み合わせは、構築時に機能側で検出・捕捉されます。

#Citations your application can render

5 つのツールはいずれも ToolReturn を返します。モデルは return_value（テキスト）を確認し、引用元がある場合は末尾に「Sources:」ブロックが付加された状態を受け取ります。アプリケーション側では、YouSource が記録するソースと同じ情報を metadata['sources'] から読み取ることができます。

Pydantic AI のメッセージ処理では、ToolReturnPart を用いてメタデータを抽出できます。以下のように実装します。

from pydantic_ai.messages import ToolReturnPart

for message in result.all_messages():
    for part in message.parts:
        if isinstance(part, ToolReturnPart) and part.metadata:
            for source in part.metadata.get('sources', []):
                print(source['url'], source['title'])

モデルはメタデータにアクセスできないため、コンテキスト競合は発生しません。また、UI 上の脚注も、モデルが URL を正確に繰り返す必要がありません。

web_search では、レスポンスの search_uuid とレイテンシもメタデータに含まれます。これは、実行が失敗した際のトレーシングや、特定のクエリについて You.com に問い合わせる際に役立ちます。

読み込み範囲の制御

両方の機能は同じ設定項目を共有し、web_search、answer、research を対象とします。ただし finance_research は例外で、入力として domain_filter と finance_effort のみを必要とし、ドメインフィルタの設定は適用されません。

• include_domains：許可リストであり、他の設定と併用できません。
• exclude_domains と boost_domains：両方を組み合わせることで、除外リストと再ランク付けを同時に適用できます。
• freshness：day、week、month、year、または YYYY-MM-DD から YYYY-MM-DD までの範囲を指定可能です。
• country：2 文字の国コードを入力します。

不適切な値を指定すると、構築時にエラーが発生します。

一つのエージェントで二つの検索設定を行うケースはよくあります。例えば、文脈取得にはオープンウェブを利用し、引用元には信頼できるドメインのみを使用するといった場合です。同じ機能のインスタンスを二つ作成するとツール名が重複するため、2 つ目のインスタンスは core.PrefixTools でラップする必要があります。

You.com が Pydantic AI の機能として利用可能に

以下は、Pydantic AI を用いた高度なエージェントの実装例です。

import logfire
from pydantic_ai import Agent
from pydantic_ai.capabilities import PrefixTools
from pydantic_ai_harness import YouSearch

logfire.configure()
logfire.instrument_pydantic_ai()

thorough_agent = Agent(
    'gateway/anthropic:claude-sonnet-5',
    instructions=(
        '`research` ツールは必ず 1 回だけ呼び出し、その結果に基づいて要約を作成してください。検索結果のみで回答してはいけません。引用する数値の信頼性を確認するには `trusted_web_search` を使用し、研究フェーズ前の文脈を把握するには `web_search` を活用してください。'
    ),
    output_type=SilverBrief,
    capabilities=[
        YouSearch(
            num_results=8,
            extraction_mode='full_page',
            max_text_chars=20_000,
            freshness='week',
        ),
        PrefixTools(
            wrapped=YouSearch(
                num_results=3,
                include_domains=['lbma.org.uk', 'kitco.com'],
                guidance='',
            ),
            prefix='trusted',
        ),
        YouResearch(
            research_effort='deep',
            output_schema=SilverBrief.model_json_schema(),
        ),
    ],
)

上記のエージェントは、従来の軽量型エージェントの制限を解消し、2 つのドメインに固定された追加の検索機能を備えています。また、執筆プロセス全体を研究フェーズを通じて処理します。

ラップされたインスタンスには guidance='' を設定するか、プレフィックス付きツールが適用される条件を説明するテキストに置き換えてください。これを怠ると、両方のインスタンスが同じデフォルトの段落を生成してしまい、意図した制御が効かなくなります。 （原文の技術表記: research、trusted_web_search、web_search）

同じ命名規則のため、エージェントには Web 検索機能は一つしか割り当てられません。もし web_search ツールを複数登録すると、YouSearch と競合してしまい、最初の呼び出しではなく構築段階で失敗します。両方の機能を同時に使いたい場合は、そのうちの一つを PrefixTools でラップしてください。

ツールのコストについて

フルページモードで 8 件、各 20,000 文字の検索結果を取得すると、最大 160,000 文字になります。一方、軽量版（lean）エージェントは 6,000 文字です。両方の実行は 1 つの Logfire スパンの下にネストされるため、トークン数はトレースツリー上で隣り合って表示されます。

両者の機能と指示には違いがあり、具体的な機能差は以下の通りです。

lean

thorough

survey

ハイライト付き 3 件（各 2,000 文字）

フルページ 8 件（各 20,000 文字）

信頼できるソース

なし

trusted_web_search を lbma.org.uk と kitco.com に適用

リサーチパス

なし

YouResearch(research_effort='deep')

両方のエージェントに同じ質問を連続して実行するため、軽量版と詳細版のデータは同一の 1 分間の Web 検索から得られています。以下の数値は 5 回のランニング結果であり、ヘッドライン（見出し）となるのはその比率の中央値です。

lean

thorough

入力トークン数

7,937

65,987

出力トークン数

159

358

実時間

5.5 秒

26.3 秒

実行あたりのコスト

$0.01

$0.13

ツール呼び出し回数

1

3

入力トークンは同じ 2 つのフィールドで 8 倍になっています。5 回のランニング全体を通じたペアの比率は 5.4 倍から 11.8 倍の間で変動し、中央値は 8.2 倍でした。

この差の大部分を占めるのは 1 つのツール呼び出しです。research の実行には中央値で 16.3 秒かかり、詳細版の実行時間の 62% を占め、トークン数の違いのほとんどを説明しています。

ツールを実行するかどうかを決定するのは「指示」であり、実行された場合の継続時間は「研究努力度（research_effort）」が決めます。上記の記述に基づき、5 回の試行すべてで研究機能が呼び出され、徹底的なエージェントの入力トークン数は 65,075 から 67,698 の範囲で 1.4% 変動しました。

一方、軽量型（lean）エージェントの入力トークンは、同じ 5 回の試行で 5,581 から 12,160 にまで幅広に変動しました。これは、検索結果の出力を固定する要因が、エージェントが呼び出した際にウェブから提供されたデータ以外にないためです。

7 分以内に 5 回実行した結果は、設定の有効性を測る指標にはなりますが、銀価格が実際に動いているような実戦環境での各エージェントの振る舞いを評価するものではありません。

その取引を行う価値があるかどうかは、最終的に人間が判断すべき問題です。徹底的なレポートでは出典を明記し、引用された価格がドメイン内のものであるかを確認します。一方、軽量型エージェントはオープンウェブから数値を取得し、わずか 5 秒で返答します。

#なぜこの組み合わせが機能するのか

ウェブを読み込むエージェントは、その回答がユーザーの制御範囲外の事象に依存するものです。ページの内容が変わったり、検索結果が不自然なものを返したり、重要な情報源だけが要約から抜け落ちたりすることもあります。しかし、これらはすべて推測で対応する必要はありません。ツール定義は型付けされており、出力も検証されるため、 malformed な結果が発生しても可視化された場所で即座に検知できます。さらに Pydantic Logfire が詳細なログ（レシート）を保持し、どのクエリが実行され、何が返ってきたか、どのページが完全に読み込まれたか、そして全体のランニングコストはいくらだったかを明確に記録します。

You.com の貢献は、検索結果の断片と研究パスを区別する機能を提供することにあります。これにより、エージェントコードは単一の検索エンドポイント上でその区別を新たに発明する必要がなくなります。

本番環境への導入前にいくつか注意点を挙げます。

Harness は 0.x リリース版のため、マイナーバージョン間で API が変更される可能性があります。変更には非推奨警告が含まれ、リリースノートには移行ガイドも記載されています。

研究ブロックはパスの長さによって動作します。深さや完全性の高い設定では、周囲のリクエストタイムアウトを秒単位ではなく分単位で設定してください。

事前構築されたクライアントはそのまま使用されるため、タイムアウトとホストの設定はユーザーが行う必要があります。timeout_ms はデフォルトクライアントにのみ適用されます。

ドメインフィルターはエージェントがアクセスできる範囲を制限しますが、読み込んだページから与えられる情報に対するセキュリティ境界にはなりません。

#Try it

you.com/platform でキーを取得し、モデルプロバイダーのキーも用意してください。その後、Web 検索用の Pydantic AI エージェントに YouSearch() を追加します。Logfire を使用して各ステップを可視化し、プロンプトを検証、パフォーマンスを分析できます。設定には約 2 分程度で、動作する Web 読み取りエージェントが構築可能です。

1 回目の実行以上の機能が必要な場合:

You.com の能力ドキュメントには、YouSearch、YouResearch、およびそれらのツールセットに関する完全なリファレンスが記載されています。

Pydantic AI Harness の能力ドキュメントでは、利用可能なすべての能力がリストされており、各能力の下に例やツール説明が用意されているため、そのまま読んでコピーすることが可能です。

You.com では、それぞれ異なる分野に根ざした 4 つの独自レシピ（cookbooks）を準備しています。具体的には、研究に基づく抗菌薬耐性に関する要約、YouSearch を活用した K-12 教員の定着率調査、finance_research を通じたプライベートクレジットの解説、そしてこれら 3 つを横断する SubAgents を経由して行われるデューデリジェンスデスクです。ご自身のドメインが汎用的な検索エージェントよりもこれらのいずれかに近い場合は、まずはそこから始めてみてください。

上記のエージェントはすべて Pydantic Logfire で追跡されており、各実行結果は SQL でクエリを実行可能なトレースとして保存されます。これには検索履歴、ページ閲覧記録、再試行回数、トークンコストなどが含まれます。デバッグ中は Logfire の MCP サーバーを起動したままにしておけば、エージェント自身が自身のトレースを読み込んであなたにフィードバックすることも可能です。

エージェントが自ら情報源を選択するようになったら、次は Pydantic Evals を活用しましょう。これにより、ある質問の精度を高めるためのプロンプト変更が、他の質問の性能を低下させることを防げます。

もしこの仕組みを使って素晴らしいものを構築された場合は、ぜひ共有してください。ハーン（harness）は GitHub に公開されており、課題（issues）もオープンです。機能リストの充実度は、ユーザーからのフィードバックによって主に支えられています。Pydantic の Slack でぜひお話ししましょう。

これらはすべて Pydantic Stack を構成する一部です。ぜひお試しください！