搜索结果 - Claude Platform Docs

此功能符合零数据保留（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 应用程序，其中工具获取并返回相关内容，并自动生成引用。

示例：知识库工具

方法 2：作为顶层内容的搜索结果

您也可以直接在用户消息中提供搜索结果。这适用于：

来自您的搜索基础设施的预取内容
来自先前查询的缓存搜索结果
来自外部搜索服务的内容
测试和开发

示例：直接提供搜索结果

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]` 的内容连接在一起。不计入输出令牌。
`search_result_index`	integer	被引用的搜索结果在请求中所有 `search_result` 块中的索引（从 0 开始），按其出现顺序排列（跨所有消息和工具结果）。

块索引标识了搜索结果 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 文档，包括内容块类型。

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
                    )
                ],
            ),
        ],
    )

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)

主要优势

工作原理

搜索结果架构

必填字段

可选字段

方法 1：来自工具调用的搜索结果

示例：知识库工具

方法 2：作为顶层内容的搜索结果

示例：直接提供搜索结果

Claude 带引用的响应

引用字段

多个内容块

高级用法

结合两种方法

与其他内容类型结合

缓存控制

引用控制

最佳实践

基于工具的搜索（方法 1）

顶层搜索（方法 2）

通用最佳实践

限制

后续步骤

主要优势

工作原理

搜索结果架构

必填字段

可选字段

方法 1：来自工具调用的搜索结果

示例：知识库工具

方法 2：作为顶层内容的搜索结果

示例：直接提供搜索结果

Claude 带引用的响应

引用字段

多个内容块

高级用法

结合两种方法

与其他内容类型结合

缓存控制

引用控制

最佳实践

基于工具的搜索（方法 1）

顶层搜索（方法 2）

通用最佳实践

限制

后续步骤