「zero data retention」(ゼロデータ保持)、すなわちZDRがこの機能にどのように適用されるかについては、APIとデータ保持を参照してください。
検索結果コンテンツブロックを使用すると、Claudeがウェブ検索結果を引用するのと同じ方法で、お客様自身のコンテンツを引用できます。各引用には、お客様が提供したソースとタイトルが含まれます。Claudeがドキュメントに回答を帰属させる必要があるRAG(Retrieval-Augmented Generation、検索拡張生成)アプリケーションで使用してください。
Claude Haiku 3を除くすべてのアクティブなモデルが、引用付きの検索結果をサポートしています。ベータヘッダーは不要です。検索結果は標準のMessages APIの一部です。
検索結果は2つの方法で提供できます。
どちらの場合も、引用が有効になっていれば、Claudeは検索結果を自動的に引用します。特別なプロンプトは必要ありません。質問をすれば、お客様のコンテンツを利用したテキストブロックに引用が表示されます。
検索結果は次の構造を使用します。
{
"type": "search_result",
"source": "https://example.com/article", // Required: Source URL or identifier
"title": "Article Title", // Required: Title of the result
"content": [
// Required: Array of text blocks
{
"type": "text",
"text": "The actual content of the search result..."
}
],
"citations": {
// Optional: Citation configuration
"enabled": true // Enable/disable citations for this result
}
}| フィールド | 型 | 説明 |
|---|---|---|
type | string | "search_result"である必要があります |
source | string | コンテンツのソース。安定した文字列であれば何でも使用できます。URL、またはkb://article-1234のような内部識別子など |
title | string | 検索結果のわかりやすいタイトル |
content | array | 実際のコンテンツを含むテキストブロックの配列 |
| フィールド | 型 | 説明 |
|---|---|---|
citations | object | enabledブール値フィールドを持つ引用設定。引用はデフォルトで無効です。このページのすべての例では"enabled": trueを明示的に設定しています。リクエスト内のすべての検索結果は同じ設定を使用する必要があります(引用の制御を参照) |
cache_control | object | キャッシュ制御設定(例: {"type": "ephemeral"}) |
content配列の各項目は、次の内容を持つテキストブロックである必要があります。
type: "text"である必要がありますtext: 実際のテキストコンテンツ(空でない文字列)検索結果はテキストのみを保持します。content配列内では画像やその他のメディアはサポートされていません。
カスタムツールから検索結果を返すことで、動的なRAGアプリケーションが可能になります。ツールが実行時にコンテンツを取得し、Claudeがレスポンスでそれを引用します。次の例では、tool_choiceでツール呼び出しを強制しているため、検索ステップが毎回実行されます。
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},
),
]
# ユーザーの質問を先頭に、会話をリストとして構築する
messages = [
MessageParam(role="user", content="How do I configure the timeout settings?")
]
# ツールを指定してメッセージを作成する
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=[knowledge_base_tool],
tool_choice={"type": "tool", "name": "search_knowledge_base"},
messages=messages,
)
# Claudeがツールを呼び出したら、検索結果を提供します。
# tool_useブロックは常に先頭にあるとは限らないため、反復処理で見つけます。
tool_use = next((block for block in response.content if block.type == "tool_use"), None)
if tool_use is not None:
tool_result = search_knowledge_base(tool_use.input["query"])
# Claudeのターン、次にツール結果を進行中の会話に追加する
messages.append(MessageParam(role="assistant", content=response.content))
messages.append(
MessageParam(
role="user",
content=[
ToolResultBlockParam(
type="tool_result",
tool_use_id=tool_use.id,
content=tool_result, # Search results go here
)
],
)
)
# ツール結果を送り返す
final_response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
)
print(final_response)ユーザーメッセージで検索結果を直接提供することもできます。これは次のような場合に便利です。
from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam
client = Anthropic()
# 検索結果をユーザーメッセージに直接提供します
response = client.messages.create(
model="claude-opus-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)検索結果の提供方法にかかわらず、Claudeは検索結果の情報を使用する際に自動的に引用を含めます。
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard.",
"citations": [
{
"type": "search_result_location",
"cited_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.",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 1
}
]
},
{
"type": "text",
"text": "\n\nTo set this up from scratch, you'll need to "
},
{
"type": "text",
"text": "sign up for an account, generate an API key from the dashboard, install the SDK using `pip install company-sdk`, and initialize the client with your API key.",
"citations": [
{
"type": "search_result_location",
"cited_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.",
"source": "https://docs.company.com/quickstart",
"title": "Getting Started Guide",
"search_result_index": 1,
"start_block_index": 0,
"end_block_index": 1
}
]
}
]
}各引用には次の内容が含まれます。
| フィールド | 型 | 説明 |
|---|---|---|
type | string | 検索結果の引用では常に"search_result_location" |
source | string | 元の検索結果のソース |
title | string または null | 元の検索結果のタイトル |
cited_text | string | 引用されたブロックの全文を連結したもの。content[start_block_index:end_block_index]の内容を結合したものと等しくなります。output tokensにはカウントされません。 |
search_result_index | integer | リクエスト内のすべてのsearch_resultブロックの中で、引用された検索結果の0始まりのインデックス。出現順(すべてのメッセージとツール結果にわたる)です。 |
start_block_index | integer | 検索結果のcontent配列内で最初に引用されたブロックの0始まりのインデックス。 |
end_block_index | integer | 検索結果のcontent配列内で引用されたブロック範囲の排他的な終了インデックス。常にstart_block_indexより大きくなります。 |
ブロックインデックスは検索結果のcontent配列のスライスを特定し、cited_textはそのスライスの全文です。テキストブロックは引用可能な最小単位です。Claudeはブロック全体を引用し、ブロック内の部分文字列は引用しません。より細かい粒度の引用を得るには、検索結果のコンテンツをより小さなブロックに分割してください(複数のコンテンツブロックを参照)。
検索結果は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."
}
],
"citations": { "enabled": true }
}レート制限のブロックを参照する引用は次のようになります。
{
"type": "search_result_location",
"cited_text": "Rate Limits: The API allows 1000 requests per hour per key.",
"source": "https://docs.company.com/api-guide",
"title": "API Documentation",
"search_result_index": 0,
"start_block_index": 1,
"end_block_index": 2
}この検索結果が引用されると、start_block_indexとend_block_indexが引用の対象となるブロックを特定し、cited_textにはそれらのブロックのテキストが正確に含まれます。コンテンツをより小さく焦点を絞ったブロックに分割すると、Claudeはより細かい引用境界を得られます。コンテンツを1つのブロックにまとめると、すべての引用が全文を返すことになります。これは、Citations機能のカスタムコンテンツドキュメントで使用されているのと同じモデルです。
同じ会話で両方の方法を混在させることができます。Claudeはどちらのソースからも引用し、search_result_indexはソースに関係なく、リクエスト順にすべてのsearch_resultブロックをカウントします。
次の例は完全な会話を再現しています。最初のユーザーメッセージには事前取得した検索結果が含まれ、アシスタントのターンでナレッジベースツールを呼び出し、ツール結果が2番目の検索結果を返します。Claudeの回答は両方のソースを引用します。
from anthropic.types import (
MessageParam,
SearchResultBlockParam,
TextBlockParam,
ToolResultBlockParam,
ToolUseBlockParam,
)
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"],
},
}
# 検索結果を2つの方法で提供する会話を再現します。最初の
# ユーザーメッセージには事前取得した結果が含まれ、ツール結果は別の結果を返します
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=[knowledge_base_tool],
messages=[
MessageParam(
role="user",
content=[
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/overview",
title="Product Overview",
content=[
TextBlockParam(
type="text",
text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
)
],
citations={"enabled": True},
),
TextBlockParam(
type="text",
text="What does Acme Dashboard do, and what plans is it available on?",
),
],
),
MessageParam(
role="assistant",
content=[
TextBlockParam(
type="text", text="Let me check the pricing information."
),
ToolUseBlockParam(
type="tool_use",
id="toolu_01A09q90qw90lq917835lq9",
name="search_knowledge_base",
input={"query": "Acme Dashboard pricing plans"},
),
],
),
MessageParam(
role="user",
content=[
ToolResultBlockParam(
type="tool_result",
tool_use_id="toolu_01A09q90qw90lq917835lq9",
content=[
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/pricing",
title="Pricing Plans",
content=[
TextBlockParam(
type="text",
text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
)
],
citations={"enabled": True},
)
],
)
],
),
],
)
print(response)レスポンスは両方のソースを引用します。事前取得した結果はsearch_result_index: 0、ツールが返した結果はsearch_result_index: 1となり、会話内でsearch_resultブロックが出現する順序と一致します。
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "Here's what I found about Acme Dashboard:\n\n**What it does:** "
},
{
"type": "text",
"text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
"citations": [
{
"type": "search_result_location",
"cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
"source": "https://docs.company.com/overview",
"title": "Product Overview",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 1
}
]
},
{
"type": "text",
"text": "\n\n**Available plans:** "
},
{
"type": "text",
"text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
"citations": [
{
"type": "search_result_location",
"cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
"source": "https://docs.company.com/pricing",
"title": "Pricing Plans",
"search_result_index": 1,
"start_block_index": 0,
"end_block_index": 1
}
]
}
]
}ユーザーメッセージでは、search_resultブロックは他のあらゆるコンテンツブロックと並べて配置できます。方法2の例では検索結果をtextの質問と組み合わせていますが、画像やドキュメントブロックも同じように組み合わせることができます。
ツール結果はより厳格です。tool_resultのコンテンツ配列内のいずれかのブロックがsearch_resultである場合、そのすべてのブロックがsearch_resultである必要があります。同じツール結果内で検索結果を他のブロックタイプと混在させると、検証エラーが返されます。ツール由来の検索結果と一緒に補足テキストを返すには、いずれかの検索結果のcontent配列内にテキストブロックとして含めてください。そうすることで、そのテキストも引用可能になります。
検索結果ブロックにcache_controlを追加すると、リクエスト間で再利用するためにキャッシュできます。同じブロック上でcitationsと並べて配置します。
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "..." }],
"citations": { "enabled": true },
"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 // Enable citations for this result
}
}citations.enabledがtrueに設定されている場合、Claudeは検索結果を利用したテキストブロックに引用参照を付加します。
引用はオール・オア・ナッシングです。リクエスト内のすべての検索結果で引用を有効にするか、すべてで無効にする必要があります。異なる引用設定の検索結果を混在させるとエラーになります。
結果を効果的に構造化する:
一貫性を維持する:
エラーを適切に処理する: 検索が失敗したり何も返さなかったりした場合は、エラーを発生させる代わりに、結果を説明するプレーンテキストブロック(例: {"type": "text", "text": "No results found."})を返します。Claudeが空の結果をユーザーに説明し、会話が継続します。
search_resultブロックはユーザーメッセージ(ツール結果内を含む)にのみ出現できます。検索結果を含むアシスタントメッセージは拒否されます。search_resultブロックで引用を有効にする必要があります。ストリーミングレスポンスでの拒否停止理由を検出して処理し、拒否されたリクエストをフォールバックモデルで再試行します。
Claudeのレスポンスをソースドキュメントに基づかせます。引用は各主張を裏付ける正確な箇所を返すため、回答を検証し、ユーザーにソースを提示できます。
引用されたソース、オプションの動的フィルタリング、ドメイン制御を備えた最新のウェブコンテンツへのアクセスをClaudeに提供します。
コンテンツブロックタイプを含む、Messages APIの完全なドキュメントを参照してください。
cache_controlで検索結果をキャッシュし、繰り返しのリクエストにおけるコストとレイテンシを削減します。
Was this page helpful?