검색 결과 콘텐츠 블록은 적절한 소스 속성을 포함한 자연스러운 인용을 활성화하여 웹 검색 품질의 인용을 사용자 정의 애플리케이션에 제공합니다. 이 기능은 Claude가 소스를 정확하게 인용해야 하는 RAG(검색 증강 생성) 애플리케이션에 특히 강력합니다.
검색 결과 기능은 다음 모델에서 사용할 수 있습니다:
claude-opus-4-5-20251101)claude-opus-4-1-20250805)claude-opus-4-20250514)claude-sonnet-4-5-20250929)claude-sonnet-4-20250514)claude-3-7-sonnet-20250219)claude-haiku-4-5-20251001)claude-3-5-haiku-20241022)검색 결과는 두 가지 방식으로 제공할 수 있습니다:
두 경우 모두 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: 실제 텍스트 콘텐츠 (비어있지 않은 문자열)가장 강력한 사용 사례는 사용자 정의 도구에서 검색 결과를 반환하는 것입니다. 이를 통해 도구가 자동 인용으로 관련 콘텐츠를 가져오고 반환하는 동적 RAG 애플리케이션을 활성화합니다.
사용자 메시지에 직접 검색 결과를 제공할 수도 있습니다. 이는 다음의 경우에 유용합니다:
검색 결과가 어떻게 제공되든 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 or null | 원본 검색 결과의 제목 |
cited_text | string | 인용되는 정확한 텍스트 |
search_result_index | integer | 검색 결과의 인덱스 (0 기반) |
start_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는 검색 결과의 정보를 사용할 때 인용 참조를 포함합니다. 이를 통해 다음이 가능합니다:
citations 필드를 생략하면 기본적으로 인용이 비활성화됩니다.
인용은 전부 아니면 무(all-or-nothing)입니다: 요청의 모든 검색 결과에 인용이 활성화되거나 모두 비활성화되어야 합니다. 다른 인용 설정을 가진 검색 결과를 혼합하면 오류가 발생합니다. 일부 소스에 대해 인용을 비활성화해야 하는 경우 해당 요청의 모든 검색 결과에 대해 인용을 비활성화해야 합니다.
결과를 효과적으로 구조화
일관성 유지
오류를 우아하게 처리
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)}"}content 배열은 최소 하나의 텍스트 블록을 포함해야 합니다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 # 검색 결과가 여기에 들어갑니다
)
]
)
]
)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))end_block_index |
| integer |
| 콘텐츠 배열의 끝 위치 |