Claude Platform Docs
  • Messages
  • Managed Agents
  • 관리자

Search...
⌘K
첫 단계
Claude 소개빠른 시작
Claude로 빌드하기
기능 개요Messages API 사용하기중지 이유 및 폴백거부 및 폴백폴백 크레딧
모델 기능
확장 사고적응형 사고Effort작업 예산 (베타)고속 모드 (리서치 프리뷰)구조화된 출력인용스트리밍 메시지배치 처리검색 결과스트리밍 거부다국어 지원임베딩
도구
개요도구 사용 작동 방식튜토리얼: 도구 사용 에이전트 빌드하기도구 정의도구 호출 처리병렬 도구 사용Tool Runner (SDK)엄격한 도구 사용프롬프트 캐싱과 도구 사용서버 도구문제 해결웹 검색 도구웹 가져오기 도구코드 실행 도구어드바이저 도구메모리 도구Bash 도구컴퓨터 사용 도구텍스트 편집기 도구
도구 인프라
도구 레퍼런스도구 컨텍스트 관리도구 조합도구 검색프로그래밍 방식 도구 호출세분화된 도구 스트리밍
컨텍스트 관리
컨텍스트 윈도우압축컨텍스트 편집프롬프트 캐싱대화 중 시스템 메시지오케스트레이션 모드 빌드하기캐시 진단 (베타)토큰 계산
파일 작업
Files APIPDF 지원이미지 및 비전
스킬
개요빠른 시작모범 사례엔터프라이즈용 스킬API의 스킬
MCP
원격 MCP 서버MCP 커넥터
클라우드 플랫폼의 Claude
Amazon BedrockAmazon Bedrock (레거시)AWS의 Claude PlatformMicrosoft FoundryVertex AI

Log in
검색 결과
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Claude Platform Docs

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Claude on AWS
  • Claude on Google Cloud

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
Messages/모델 기능

검색 결과

소스 출처 표시가 포함된 검색 결과를 제공하여 RAG 애플리케이션에서 자연스러운 인용을 구현하세요


이 기능은 Zero Data Retention (ZDR)의 적용 대상입니다. 조직에 ZDR 계약이 체결되어 있는 경우, 이 기능을 통해 전송된 데이터는 API 응답이 반환된 후 저장되지 않습니다.

검색 결과 콘텐츠 블록은 적절한 소스 출처 표시와 함께 자연스러운 인용을 가능하게 하여, 웹 검색 수준의 인용 품질을 사용자 정의 애플리케이션에 제공합니다. 이 기능은 Claude가 소스를 정확하게 인용해야 하는 "RAG"(검색 증강 생성, Retrieval-Augmented Generation) 애플리케이션에 특히 유용합니다.

검색 결과 기능은 다음 모델에서 사용할 수 있습니다:

  • Claude Opus 4.8 (claude-opus-4-8)
  • Claude Opus 4.7 (claude-opus-4-7)
  • Claude Opus 4.6 (claude-opus-4-6)
  • Claude Sonnet 4.6 (claude-sonnet-4-6)
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
  • Claude Opus 4.5 (claude-opus-4-5-20251101)
  • Claude Opus 4.1 (지원 중단됨) (claude-opus-4-1-20250805)
  • Claude Opus 4 (Vertex AI를 제외하고 종료됨) (claude-opus-4-20250514)
  • Claude Sonnet 4 (Bedrock 및 Vertex AI를 제외하고 종료됨) (claude-sonnet-4-20250514)
  • Claude Haiku 4.5 (claude-haiku-4-5-20251001)
  • Claude Haiku 3.5 (Bedrock 및 Vertex AI를 제외하고 종료됨) (claude-3-5-haiku-20241022)

주요 이점

  • 자연스러운 인용: 모든 콘텐츠에 대해 웹 검색과 동일한 인용 품질 달성
  • 유연한 통합: 동적 RAG를 위한 도구 반환값으로 사용하거나 사전 가져온 데이터를 위한 최상위 콘텐츠로 사용
  • 적절한 소스 출처 표시: 각 결과에는 명확한 출처 표시를 위한 소스 및 제목 정보가 포함됨
  • 문서 기반 우회 방법 불필요: 문서 기반 우회 방법의 필요성 제거
  • 일관된 인용 형식: Claude의 웹 검색 기능과 동일한 인용 품질 및 형식 제공

작동 방식

검색 결과는 두 가지 방법으로 제공할 수 있습니다:

  1. 도구 호출에서: 사용자 정의 도구가 검색 결과를 반환하여 동적 RAG 애플리케이션 구현
  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
  }
}

필수 필드

필드타입설명
typestring"search_result"여야 함
sourcestring콘텐츠의 소스 URL 또는 식별자
titlestring검색 결과를 설명하는 제목
contentarray실제 콘텐츠를 포함하는 텍스트 블록 배열

선택적 필드

필드타입설명
citationsobjectenabled 불리언 필드가 포함된 인용 구성
cache_controlobject캐시 제어 설정 (예: {"type": "ephemeral"})

content 배열의 각 항목은 다음을 포함하는 텍스트 블록이어야 합니다:

  • type: "text"여야 함
  • text: 실제 텍스트 콘텐츠 (비어 있지 않은 문자열)

방법 1: 도구 호출에서 검색 결과 반환

가장 강력한 사용 사례는 사용자 정의 도구에서 검색 결과를 반환하는 것입니다. 이를 통해 도구가 관련 콘텐츠를 가져와 자동 인용과 함께 반환하는 동적 RAG 애플리케이션을 구현할 수 있습니다.

예시: 지식 베이스 도구

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-opus-4-8",  # Works with all supported models
    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-opus-4-8",  # Works with all supported models
        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,  # Search results go here
                    )
                ],
            ),
        ],
    )

방법 2: 최상위 콘텐츠로 검색 결과 제공

사용자 메시지에 검색 결과를 직접 제공할 수도 있습니다. 이는 다음과 같은 경우에 유용합니다:

  • 검색 인프라에서 사전 가져온 콘텐츠
  • 이전 쿼리에서 캐시된 검색 결과
  • 외부 검색 서비스의 콘텐츠
  • 테스트 및 개발

예시: 직접 검색 결과 제공

from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam

client = Anthropic()

# 사용자 메시지에 검색 결과를 직접 제공
response = client.messages.create(
    model="claude-opus-4-8",
    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의 응답

검색 결과가 어떤 방식으로 제공되든, 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
        }
      ]
    }
  ]
}

인용 필드

각 인용에는 다음이 포함됩니다:

필드타입설명
typestring검색 결과 인용의 경우 항상 "search_result_location"
sourcestring원본 검색 결과의 소스
titlestring 또는 null원본 검색 결과의 제목
cited_textstring인용된 블록의 전체 텍스트를 연결한 값. content[start_block_index:end_block_index]의 내용을 이어 붙인 것과 동일합니다. 출력 토큰에 포함되지 않습니다.
search_result_indexinteger요청 내 모든 search_result 블록 중 인용된 검색 결과의 0부터 시작하는 인덱스. 모든 메시지 및 도구 결과에 걸쳐 나타나는 순서를 따릅니다.
start_block_indexinteger검색 결과의 content 배열에서 인용된 첫 번째 블록의 0부터 시작하는 인덱스.
end_block_indexinteger검색 결과의 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."
    }
  ]
}

속도 제한 블록을 참조하는 인용은 다음과 같습니다:

{
  "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가 더 세밀한 인용 경계를 사용할 수 있으며, 콘텐츠를 하나의 블록으로 결합하면 모든 인용이 전체 텍스트를 반환합니다. 이는 Citations 기능의 사용자 정의 콘텐츠 문서에서 사용하는 것과 동일한 모델입니다.

고급 사용법

두 방법 결합하기

동일한 대화에서 도구 기반 검색 결과와 최상위 검색 결과를 모두 사용할 수 있습니다:

from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam

# 최상위 검색 결과가 포함된 첫 번째 메시지
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가 응답하고 가격 정보를 검색하기 위해 도구를 호출할 수 있습니다
# 그런 다음 추가 검색 결과와 함께 도구 결과를 제공합니다

다른 콘텐츠 타입과 결합하기

두 방법 모두 검색 결과를 다른 콘텐츠와 혼합하는 것을 지원합니다:

from anthropic.types import SearchResultBlockParam, TextBlockParam

# 도구 결과에서
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 // Enable citations for this result
  }
}

citations.enabled가 true로 설정되면, Claude는 검색 결과의 정보를 사용할 때 인용 참조를 포함합니다. 이를 통해 다음이 가능합니다:

  • 사용자 정의 RAG 애플리케이션을 위한 자연스러운 인용
  • 독점 지식 베이스와 연동할 때의 소스 출처 표시
  • 검색 결과를 반환하는 모든 사용자 정의 도구에 대한 웹 검색 수준의 인용


인용은 전부 아니면 전무 방식입니다. 요청 내의 모든 검색 결과에서 인용이 활성화되어 있거나, 모두 비활성화되어 있어야 합니다. 서로 다른 인용 설정을 가진 검색 결과를 혼합하면 오류가 발생합니다.

모범 사례

도구 기반 검색 (방법 1)

  • 동적 콘텐츠: 실시간 검색 및 동적 RAG 애플리케이션에 사용
  • 오류 처리: 검색이 실패할 때 적절한 메시지 반환
  • 결과 제한: 컨텍스트 오버플로를 방지하기 위해 가장 관련성 높은 결과만 반환

최상위 검색 (방법 2)

  • 사전 가져온 콘텐츠: 이미 검색 결과가 있는 경우 사용
  • 일괄 처리: 여러 검색 결과를 한 번에 처리하는 데 이상적
  • 테스트: 알려진 콘텐츠로 인용 동작을 테스트하는 데 적합

일반적인 모범 사례

  1. 결과를 효과적으로 구조화하기:

    • 명확하고 영구적인 소스 URL 사용
    • 설명적인 제목 제공
    • 긴 콘텐츠를 논리적인 텍스트 블록으로 분할하여 Claude가 더 세밀한 인용 경계를 사용할 수 있도록 함
  2. 일관성 유지하기:

    • 애플리케이션 전반에 걸쳐 일관된 소스 형식 사용
    • 제목이 콘텐츠를 정확하게 반영하도록 보장
    • 형식을 일관되게 유지
  3. 오류를 적절하게 처리하기:

    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, Amazon Bedrock 및 Google Cloud의 Vertex AI에서 사용할 수 있습니다
  • 검색 결과 내에서는 텍스트 콘텐츠만 지원됩니다(이미지 또는 기타 미디어는 지원되지 않음)
  • content 배열에는 최소 하나의 텍스트 블록이 포함되어야 합니다

다음 단계


인용

문서, 사용자 정의 콘텐츠 및 검색 결과 전반에서 인용이 작동하는 방식을 알아보세요.

웹 검색 도구

서버 도구를 사용하여 Claude가 웹을 검색하고 소스를 자동으로 인용하도록 하세요.


Messages API 레퍼런스

콘텐츠 블록 타입을 포함한 전체 Messages API 문서를 확인하세요.

프롬프트 캐싱

cache_control로 검색 결과를 캐시하여 반복 요청 시 비용과 지연 시간을 줄이세요.

Was this page helpful?

  • 주요 이점
  • 작동 방식
  • 검색 결과 스키마
  • 필수 필드
  • 선택적 필드
  • 방법 1: 도구 호출에서 검색 결과 반환
  • 예시: 지식 베이스 도구
  • 방법 2: 최상위 콘텐츠로 검색 결과 제공
  • 예시: 직접 검색 결과 제공
  • 인용이 포함된 Claude의 응답
  • 인용 필드
  • 여러 콘텐츠 블록
  • 고급 사용법
  • 두 방법 결합하기
  • 다른 콘텐츠 타입과 결합하기
  • 캐시 제어
  • 인용 제어
  • 모범 사례
  • 도구 기반 검색 (방법 1)
  • 최상위 검색 (방법 2)
  • 일반적인 모범 사례
  • 제한 사항
  • 다음 단계