検索結果
検索結果コンテンツブロックは、適切なソース属性を持つ自然な引用を有効にし、Webサーチの品質の引用をカスタムアプリケーションにもたらします。この機能は、Claude がソースを正確に引用する必要がある RAG(検索拡張生成)アプリケーションに特に強力です。
検索結果機能は、以下のモデルで利用可能です:
- Claude Opus 4.1 (
claude-opus-4-1-20250805) - Claude Opus 4 (
claude-opus-4-20250514) - Claude Sonnet 4.5 (
claude-sonnet-4-5-20250929) - Claude Sonnet 4 (
claude-sonnet-4-20250514) - Claude Sonnet 3.7 (非推奨) (
claude-3-7-sonnet-20250219) - Claude 3.5 Haiku (
claude-3-5-haiku-20241022)
主な利点
- 自然な引用 - あらゆるコンテンツに対して Web サーチと同じ品質の引用を実現
- 柔軟な統合 - 動的 RAG のためのツール戻り値での使用、または事前取得データのトップレベルコンテンツとしての使用
- 適切なソース属性 - 各結果には、明確な属性のためのソースとタイトル情報が含まれます
- ドキュメント回避策は不要 - ドキュメントベースの回避策の必要性を排除
- 一貫した引用形式 - Claude の Web サーチ機能の引用品質と形式に一致
仕組み
検索結果は 2 つの方法で提供できます:
- ツール呼び出しから - カスタムツールが検索結果を返し、動的 RAG アプリケーションを有効にします
- トップレベルコンテンツとして - 事前取得またはキャッシュされたコンテンツのために、ユーザーメッセージで直接検索結果を提供します
どちらの場合でも、Claude は適切なソース属性を持つ検索結果から情報を自動的に引用できます。
検索結果スキーマ
検索結果は以下の構造を使用します:
{
"type": "search_result",
"source": "https://example.com/article", // 必須: ソース URL または識別子
"title": "Article Title", // 必須: 結果のタイトル
"content": [ // 必須: テキストブロックの配列
{
"type": "text",
"text": "The actual content of the search result..."
}
],
"citations": { // オプション: 引用設定
"enabled": true // この結果の引用を有効/無効にする
}
}必須フィールド
| フィールド | 型 | 説明 |
|---|---|---|
type | string | "search_result" である必要があります |
source | string | コンテンツのソース URL または識別子 |
title | string | 検索結果の説明的なタイトル |
content | array | 実際のコンテンツを含むテキストブロックの配列 |
オプションフィールド
| フィールド | 型 | 説明 |
|---|---|---|
citations | object | enabled ブール値フィールドを持つ引用設定 |
cache_control | object | キャッシュ制御設定(例:{"type": "ephemeral"}) |
content 配列内の各項目は、以下を含むテキストブロックである必要があります:
type:"text"である必要がありますtext: 実際のテキストコンテンツ(空でない文字列)
方法 1: ツール呼び出しからの検索結果
最も強力なユースケースは、カスタムツールから検索結果を返すことです。これにより、ツールが関連コンテンツを取得して自動引用で返す動的 RAG アプリケーションが可能になります。
例: ナレッジベースツール
from anthropic import Anthropic
from anthropic.types import (
MessageParam,
TextBlockParam,
SearchResultBlockParam,
ToolResultBlockParam
)
client = Anthropic()
# ナレッジベース検索ツールを定義
knowledge_base_tool = {
"name": "search_knowledge_base",
"description": "Search the company knowledge base for information",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query"
}
},
"required": ["query"]
}
}
# ツール呼び出しを処理する関数
def search_knowledge_base(query):
# ここに検索ロジックを記述
# 正しい形式で検索結果を返す
return [
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/product-guide",
title="Product Configuration Guide",
content=[
TextBlockParam(
type="text",
text="To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."
)
],
citations={"enabled": True}
),
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/troubleshooting",
title="Troubleshooting Guide",
content=[
TextBlockParam(
type="text",
text="If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."
)
],
citations={"enabled": True}
)
]
# ツールを使用してメッセージを作成
response = client.messages.create(
model="claude-sonnet-4-5", # すべてのサポートされているモデルで動作
max_tokens=1024,
tools=[knowledge_base_tool],
messages=[
MessageParam(
role="user",
content="How do I configure the timeout settings?"
)
]
)
# Claude がツールを呼び出すとき、検索結果を提供
if response.content[0].type == "tool_use":
tool_result = search_knowledge_base(response.content[0].input["query"])
# ツール結果を返す
final_response = client.messages.create(
model="claude-sonnet-4-5", # すべてのサポートされているモデルで動作
max_tokens=1024,
messages=[
MessageParam(role="user", content="How do I configure the timeout settings?"),
MessageParam(role="assistant", content=response.content),
MessageParam(
role="user",
content=[
ToolResultBlockParam(
type="tool_result",
tool_use_id=response.content[0].id,
content=tool_result # 検索結果がここに入ります
)
]
)
]
)方法 2: トップレベルコンテンツとしての検索結果
ユーザーメッセージで直接検索結果を提供することもできます。これは以下の場合に便利です:
- 検索インフラストラクチャから事前取得されたコンテンツ
- 前のクエリからキャッシュされた検索結果
- 外部検索サービスからのコンテンツ
- テストと開発
例: 直接検索結果
from anthropic import Anthropic
from anthropic.types import (
MessageParam,
TextBlockParam,
SearchResultBlockParam
)
client = Anthropic()
# ユーザーメッセージで直接検索結果を提供
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[
MessageParam(
role="user",
content=[
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/api-reference",
title="API Reference - Authentication",
content=[
TextBlockParam(
type="text",
text="All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
)
],
citations={"enabled": True}
),
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/quickstart",
title="Getting Started Guide",
content=[
TextBlockParam(
type="text",
text="To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
)
],
citations={"enabled": True}
),
TextBlockParam(
type="text",
text="Based on these search results, how do I authenticate API requests and what are the rate limits?"
)
]
)
]
)
print(response.model_dump_json(indent=2))引用を含む Claude の応答
検索結果がどのように提供されるかに関わらず、Claude は自動的に情報を使用するときに引用を含めます:
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "To authenticate API requests, you need to include an API key in the Authorization header",
"citations": [
{
"type": "search_result_location",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"cited_text": "All API requests must include an API key in the Authorization header",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 0
}
]
},
{
"type": "text",
"text": ". You can generate API keys from your dashboard",
"citations": [
{
"type": "search_result_location",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"cited_text": "Keys can be generated from the dashboard",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 0
}
]
},
{
"type": "text",
"text": ". The rate limits are 1,000 requests per hour for the standard tier and 10,000 requests per hour for the premium tier.",
"citations": [
{
"type": "search_result_location",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"cited_text": "Rate limits: 1000 requests per hour for standard tier, 10000 for premium",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 0
}
]
}
]
}引用フィールド
各引用には以下が含まれます:
| フィールド | 型 | 説明 |
|---|---|---|
type | string | 検索結果引用の場合は常に "search_result_location" |
source | string | 元の検索結果からのソース |
title | string または null | 元の検索結果からのタイトル |
cited_text | string | 引用されている正確なテキスト |
search_result_index | integer | 検索結果のインデックス(0 ベース) |
start_block_index | integer | コンテンツ配列内の開始位置 |
end_block_index | integer | コンテンツ配列内の終了位置 |
注:search_result_index は、検索結果がどのように提供されたか(ツール呼び出しまたはトップレベルコンテンツ)に関わらず、検索結果コンテンツブロックのインデックス(0 ベース)を指します。
複数のコンテンツブロック
検索結果は content 配列に複数のテキストブロックを含めることができます:
{
"type": "search_result",
"source": "https://docs.company.com/api-guide",
"title": "API Documentation",
"content": [
{
"type": "text",
"text": "Authentication: All API requests require an API key."
},
{
"type": "text",
"text": "Rate Limits: The API allows 1000 requests per hour per key."
},
{
"type": "text",
"text": "Error Handling: The API returns standard HTTP status codes."
}
]
}Claude は start_block_index と end_block_index フィールドを使用して特定のブロックを引用できます。
高度な使用法
両方の方法を組み合わせる
同じ会話で、ツールベースとトップレベルの両方の検索結果を使用できます:
# トップレベル検索結果を含む最初のメッセージ
messages = [
MessageParam(
role="user",
content=[
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/overview",
title="Product Overview",
content=[
TextBlockParam(type="text", text="Our product helps teams collaborate...")
],
citations={"enabled": True}
),
TextBlockParam(
type="text",
text="Tell me about this product and search for pricing information"
)
]
)
]
# Claude は応答して、価格情報を検索するためにツールを呼び出す可能性があります
# その後、より多くの検索結果を含むツール結果を提供します他のコンテンツタイプと組み合わせる
両方の方法は、検索結果を他のコンテンツと混ぜることをサポートします:
# ツール結果内
tool_result = [
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/guide",
title="User Guide",
content=[TextBlockParam(type="text", text="Configuration details...")],
citations={"enabled": True}
),
TextBlockParam(
type="text",
text="Additional context: This applies to version 2.0 and later."
)
]
# トップレベルコンテンツ内
user_content = [
SearchResultBlockParam(
type="search_result",
source="https://research.com/paper",
title="Research Paper",
content=[TextBlockParam(type="text", text="Key findings...")],
citations={"enabled": True}
),
{
"type": "image",
"source": {"type": "url", "url": "https://example.com/chart.png"}
},
TextBlockParam(
type="text",
text="How does the chart relate to the research findings?"
)
]キャッシュ制御
パフォーマンスを向上させるためにキャッシュ制御を追加します:
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{"type": "text", "text": "..."}],
"cache_control": {
"type": "ephemeral"
}
}引用制御
デフォルトでは、検索結果の引用は無効になっています。citations 設定を明示的に設定することで、引用を有効にできます:
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{"type": "text", "text": "Important documentation..."}],
"citations": {
"enabled": true // この結果の引用を有効にする
}
}citations.enabled が true に設定されている場合、Claude は検索結果から情報を使用するときに引用参照を含めます。これにより以下が可能になります:
- カスタム RAG アプリケーション向けの自然な引用
- 独自のナレッジベースとインターフェースするときのソース属性
- 検索結果を返すカスタムツール向けの Web サーチ品質の引用
citations フィールドが省略されている場合、引用はデフォルトで無効になります。
引用はすべてか無かです:リクエスト内のすべての検索結果で引用を有効にするか、すべてで無効にする必要があります。異なる引用設定を持つ検索結果を混ぜるとエラーが発生します。一部のソースの引用を無効にする必要がある場合は、そのリクエスト内のすべての検索結果で無効にする必要があります。
ベストプラクティス
ツールベースの検索用(方法 1)
- 動的コンテンツ: リアルタイム検索と動的 RAG アプリケーション用に使用
- エラー処理: 検索が失敗したときに適切なメッセージを返す
- 結果制限: コンテキストオーバーフローを避けるために、最も関連性の高い結果のみを返す
トップレベル検索用(方法 2)
- 事前取得コンテンツ: 既に検索結果がある場合に使用
- バッチ処理: 複数の検索結果を一度に処理するのに理想的
- テスト: 既知のコンテンツで引用動作をテストするのに最適
一般的なベストプラクティス
-
結果を効果的に構造化する
- 明確で永続的なソース URL を使用
- 説明的なタイトルを提供
- 長いコンテンツを論理的なテキストブロックに分割
-
一貫性を保つ
- アプリケーション全体でソース形式を一貫させる
- タイトルがコンテンツを正確に反映していることを確認
- フォーマットを一貫させる
-
エラーを適切に処理する
def search_with_fallback(query): try: results = perform_search(query) if not results: return {"type": "text", "text": "No results found."} return format_as_search_results(results) except Exception as e: return {"type": "text", "text": f"Search error: {str(e)}"}
制限事項
- 検索結果コンテンツブロックは Claude API と Google Cloud の Vertex AI で利用可能です
- 検索結果内でサポートされるのはテキストコンテンツのみです(画像やその他のメディアはサポートされていません)
content配列には少なくとも 1 つのテキストブロックが含まれている必要があります