Messages模型能力

搜尋結果

透過提供具有來源歸屬的搜尋結果，為 RAG 應用程式啟用自然引用

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

搜尋結果內容區塊可實現具有適當來源歸屬的自然引用，為您的自訂應用程式帶來網頁搜尋品質的引用功能。此功能對於「RAG」（Retrieval-Augmented Generation，檢索增強生成）應用程式特別強大，因為您需要 Claude 準確地引用來源。

搜尋結果功能可在以下模型上使用：

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 網頁搜尋功能的引用品質和格式相符

運作方式

搜尋結果可以透過兩種方式提供：

來自工具呼叫： 您的自訂工具回傳搜尋結果，實現動態 RAG 應用程式
作為頂層內容： 您直接在使用者訊息中提供搜尋結果，用於預先擷取或快取的內容

在這兩種情況下，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 或識別碼
`title`	string	搜尋結果的描述性標題
`content`	array	包含實際內容的文字區塊陣列

選填欄位

欄位	類型	說明
`citations`	object	引用設定，包含 `enabled` 布林欄位
`cache_control`	object	快取控制設定（例如 `{"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
        }
      ]
    }
  ]
}

引用欄位

每個引用包含：

欄位	類型	說明
`type`	string	對於搜尋結果引用，一律為 `"search_result_location"`
`source`	string	來自原始搜尋結果的來源
`title`	string 或 null	來自原始搜尋結果的標題
`cited_text`	string	被引用區塊的完整文字，串接在一起。等於 `content[start_block_index:end_block_index]` 的內容連接在一起。不計入輸出 token。
`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."
    }
  ]
}

參照速率限制區塊的引用如下所示：

{
  "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 擁有更精細的引用邊界；將內容合併成一個區塊則意味著每個引用都會回傳完整文字。這與引用功能中自訂內容文件所使用的模型相同。

進階用法

結合兩種方法

您可以在同一個對話中同時使用基於工具和頂層的搜尋結果：

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）

預先擷取的內容： 當您已經擁有搜尋結果時使用
批次處理： 適合一次處理多個搜尋結果
測試： 非常適合使用已知內容測試引用行為

一般最佳實務

有效地建構結果：
- 使用清晰、永久的來源 URL
- 提供描述性標題
- 將長內容分割成邏輯文字區塊，以讓 Claude 擁有更精細的引用邊界
保持一致性：
- 在您的應用程式中使用一致的來源格式
- 確保標題準確反映內容
- 保持格式一致

優雅地處理錯誤：

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?

Messages模型能力

搜尋結果

透過提供具有來源歸屬的搜尋結果，為 RAG 應用程式啟用自然引用

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

搜尋結果功能可在以下模型上使用：

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 網頁搜尋功能的引用品質和格式相符

運作方式

搜尋結果可以透過兩種方式提供：

來自工具呼叫： 您的自訂工具回傳搜尋結果，實現動態 RAG 應用程式
作為頂層內容： 您直接在使用者訊息中提供搜尋結果，用於預先擷取或快取的內容

在這兩種情況下，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 或識別碼
`title`	string	搜尋結果的描述性標題
`content`	array	包含實際內容的文字區塊陣列

選填欄位

欄位	類型	說明
`citations`	object	引用設定，包含 `enabled` 布林欄位
`cache_control`	object	快取控制設定（例如 `{"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
        }
      ]
    }
  ]
}

引用欄位

每個引用包含：

欄位	類型	說明
`type`	string	對於搜尋結果引用，一律為 `"search_result_location"`
`source`	string	來自原始搜尋結果的來源
`title`	string 或 null	來自原始搜尋結果的標題
`cited_text`	string	被引用區塊的完整文字，串接在一起。等於 `content[start_block_index:end_block_index]` 的內容連接在一起。不計入輸出 token。
`search_result_index`	integer	被引用的搜尋結果在請求中所有 `search_result` 區塊中的索引（從 0 開始），依其出現順序排列（跨所有訊息和工具結果）。
`start_block_index`	integer	搜尋結果的 `content` 陣列中第一個被引用區塊的索引（從 0 開始）。
`end_block_index`	integer	搜尋結果的 `content` 陣列中被引用區塊範圍的排他性結束索引。一律大於 `start_block_index`。

多個內容區塊

搜尋結果可以在 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
}

進階用法

結合兩種方法

您可以在同一個對話中同時使用基於工具和頂層的搜尋結果：

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）

預先擷取的內容： 當您已經擁有搜尋結果時使用
批次處理： 適合一次處理多個搜尋結果
測試： 非常適合使用已知內容測試引用行為

一般最佳實務

有效地建構結果：
- 使用清晰、永久的來源 URL
- 提供描述性標題
- 將長內容分割成邏輯文字區塊，以讓 Claude 擁有更精細的引用邊界
保持一致性：
- 在您的應用程式中使用一致的來源格式
- 確保標題準確反映內容
- 保持格式一致

優雅地處理錯誤：

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）

一般最佳實務

限制

後續步驟

主要優點

運作方式

搜尋結果結構描述

必填欄位

選填欄位

方法 1：來自工具呼叫的搜尋結果

範例：知識庫工具

方法 2：搜尋結果作為頂層內容

範例：直接搜尋結果

Claude 帶有引用的回應

引用欄位

多個內容區塊

進階用法

結合兩種方法

與其他內容類型結合

快取控制

引用控制

最佳實務

針對基於工具的搜尋（方法 1）

針對頂層搜尋（方法 2）

一般最佳實務

限制

後續步驟

主要優點

運作方式

搜尋結果結構描述

必填欄位

選填欄位

方法 1：來自工具呼叫的搜尋結果

範例：知識庫工具

方法 2：搜尋結果作為頂層內容

範例：直接搜尋結果

Claude 帶有引用的回應

引用欄位

多個內容區塊

進階用法

結合兩種方法

與其他內容類型結合

快取控制

引用控制

最佳實務

針對基於工具的搜尋（方法 1）

針對頂層搜尋（方法 2）

一般最佳實務

限制

後續步驟

主要優點

運作方式

搜尋結果結構描述

必填欄位

選填欄位

方法 1：來自工具呼叫的搜尋結果

範例：知識庫工具

方法 2：搜尋結果作為頂層內容

範例：直接搜尋結果

Claude 帶有引用的回應

引用欄位

多個內容區塊

進階用法

結合兩種方法

與其他內容類型結合

快取控制

引用控制

最佳實務

針對基於工具的搜尋（方法 1）

針對頂層搜尋（方法 2）

一般最佳實務

限制

後續步驟