Claude Platform Docs
MessagesВозможности модели

Результаты поиска

Включите естественные цитаты для RAG-приложений, предоставляя результаты поиска с указанием источника

Блоки содержимого с результатами поиска позволяют Claude цитировать ваш собственный контент так же, как он цитирует результаты веб-поиска: каждая цитата содержит указанные вами источник и заголовок. Используйте их в приложениях RAG — «Retrieval-Augmented Generation» (генерация, дополненная поиском), — где Claude должен ссылаться на ваши документы при ответах.

Все активные модели поддерживают результаты поиска с цитатами, за исключением Claude Haiku 3. Бета-заголовок не требуется: результаты поиска являются частью стандартного Messages API.

Как это работает

Результаты поиска можно предоставить двумя способами:

  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 или внутренний идентификатор, например kb://article-1234
titlestringОписательный заголовок результата поиска
contentarrayМассив текстовых блоков, содержащих фактическое содержимое

Необязательные поля

ПолеТипОписание
citationsobjectКонфигурация цитат с логическим полем enabled. По умолчанию цитаты отключены; каждый пример на этой странице явно устанавливает "enabled": true. Все результаты поиска в запросе должны использовать одну и ту же настройку (см. Управление цитатами)
cache_controlobjectНастройки управления кэшем (например, {"type": "ephemeral"})

Каждый элемент массива content должен быть текстовым блоком со следующими полями:

  • type: должно быть "text"
  • text: фактическое текстовое содержимое (непустая строка)

Результаты поиска содержат только текст. Изображения и другие медиа внутри массива content не поддерживаются.

Способ 1: результаты поиска из вызовов инструментов

Возврат результатов поиска из ваших пользовательских инструментов позволяет создавать динамические 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)

Способ 2: результаты поиска как содержимое верхнего уровня

Вы также можете предоставлять результаты поиска непосредственно в сообщениях пользователя. Это полезно для:

  • Предварительно полученного контента из вашей поисковой инфраструктуры
  • Кэшированных результатов поиска из предыдущих запросов
  • Контента из внешних поисковых сервисов
  • Тестирования и разработки

Пример: прямые результаты поиска

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 с цитатами

Независимо от того, как предоставлены результаты поиска, 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Индекс (с отсчётом от 0) цитируемого результата поиска среди всех блоков search_result в запросе, в порядке их появления (по всем сообщениям и результатам инструментов).
start_block_indexintegerИндекс (с отсчётом от 0) первого цитируемого блока в массиве content результата поиска.
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."
    }
  ],
  "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 более точные границы цитирования; объединение содержимого в один блок означает, что каждая цитата возвращает полный текст. Это та же модель, что используется документами с пользовательским содержимым в функции цитат.

Расширенное использование

Комбинирование обоих способов

Вы можете сочетать оба способа в одном разговоре. Claude цитирует из любого источника, а search_result_index учитывает все блоки search_result в порядке их следования в запросе, независимо от источника.

Следующий пример воспроизводит полный разговор. Первое сообщение пользователя содержит предварительно полученный результат поиска, ход ассистента вызывает инструмент базы знаний, а результат инструмента возвращает второй результат поиска. Ответ 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"],
    },
}

# Воспроизводим диалог, в котором результаты поиска передаются обоими способами: первое
# сообщение пользователя содержит заранее полученный результат, а результат инструмента возвращает другой
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 прикрепляет ссылки на цитаты к текстовым блокам, опирающимся на результат поиска.

Лучшие практики

Для поиска на основе инструментов (способ 1)

  • Динамический контент: используйте для поиска в реальном времени и динамических RAG-приложений
  • Обработка ошибок: возвращайте соответствующие сообщения при сбоях поиска
  • Ограничение результатов: возвращайте только наиболее релевантные результаты, чтобы избежать переполнения контекста

Для поиска верхнего уровня (способ 2)

  • Предварительно полученный контент: используйте, когда у вас уже есть результаты поиска
  • Пакетная обработка: идеально подходит для обработки нескольких результатов поиска одновременно
  • Тестирование: отлично подходит для проверки поведения цитат на известном контенте

Общие лучшие практики

  1. Эффективно структурируйте результаты:

    • Используйте понятные, постоянные URL источников
    • Предоставляйте описательные заголовки
    • Разбивайте длинный контент на логические текстовые блоки, чтобы дать Claude более точные границы цитирования
  2. Поддерживайте согласованность:

    • Используйте единообразные форматы источников во всём приложении
    • Убедитесь, что заголовки точно отражают содержимое
    • Сохраняйте единообразное форматирование
  3. Корректно обрабатывайте ошибки: когда поиск завершается сбоем или ничего не возвращает, верните простой текстовый блок с описанием результата (например, {"type": "text", "text": "No results found."}) вместо генерации ошибки: Claude объяснит пользователю пустой результат, и разговор продолжится.

Ограничения

  • Блоки содержимого с результатами поиска доступны в Claude API, Amazon Bedrock и Google Cloud.
  • В результатах поиска поддерживается только текстовое содержимое (без изображений и других медиа).
  • Блоки search_result могут появляться только в сообщениях пользователя (в том числе внутри результатов инструментов). Сообщения ассистента с результатами поиска отклоняются.
  • Когда в том же запросе включён инструмент веб-поиска, цитаты должны быть включены для всех блоков search_result.

Следующие шаги

Обнаруживайте и обрабатывайте причины остановки из-за отказа в ответах с потоковой передачей и повторяйте отклонённые запросы на резервной модели.

Обосновывайте ответы Claude вашими исходными документами. Цитаты возвращают точные фрагменты, подтверждающие каждое утверждение, чтобы вы могли проверять ответы и показывать источники своим пользователям.

Предоставьте Claude доступ к актуальному веб-контенту с цитируемыми источниками, опциональной динамической фильтрацией и управлением доменами.

Ознакомьтесь с полной документацией Messages API, включая типы блоков содержимого.

Кэшируйте результаты поиска с помощью cache_control, чтобы снизить стоимость и задержку при повторных запросах.

Was this page helpful?