Результаты поиска
Получайте естественные цитаты для RAG-приложений, предоставляя результаты поиска с указанием источников
Использование зависит от продукта
search_result в результате инструмента или прямо в сообщении пользователя.user.custom_tool_result, но не в событиях user.message.Блоки содержимого с результатами поиска («search result content blocks») позволяют Claude цитировать ваш собственный контент так же, как он цитирует результаты веб-поиска: каждая «citation» (цитата) содержит указанные вами источник и заголовок. Используйте их в приложениях «Retrieval-Augmented Generation» (генерация, дополненная поиском), или RAG, где Claude должен указывать, на каких ваших документах основаны ответы.
Как это работает
Результаты поиска можно предоставить двумя способами:
- Из вызовов инструментов: ваши пользовательские инструменты возвращают результаты поиска, что позволяет создавать динамические RAG-приложения.
- Как содержимое верхнего уровня: вы предоставляете результаты поиска непосредственно в сообщениях пользователя для заранее полученного или кэшированного контента.
В обоих случаях Claude автоматически цитирует результаты поиска, когда цитирование включено. Никаких специальных подсказок не требуется: задайте свой вопрос, и цитаты появятся в текстовых блоках, которые опираются на ваш контент. Однако если ваша подсказка требует только JSON, ответ может содержать мало цитат или не содержать их вовсе. Чтобы извлечь структурированные данные с цитатой для каждого значения, см. Получение структурированных данных с цитатами.
Схема результата поиска
Результаты поиска имеют следующую структуру:
{
"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 или внутренний идентификатор, например kb://article-1234 |
title | string | Описательный заголовок результата поиска |
content | array | Массив текстовых блоков, содержащих собственно контент |
Необязательные поля
| Поле | Тип | Описание |
|---|---|---|
citations | object | Конфигурация цитирования с логическим полем enabled. По умолчанию цитирование отключено; каждый пример на этой странице явно задаёт "enabled": true. Все результаты поиска в запросе должны использовать одинаковую настройку (см. Управление цитированием) |
cache_control | object | Настройки управления кэшем (например, {"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: list[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",
"disable_parallel_tool_use": True,
},
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({"role": "assistant", "content": response.content})
messages.append(
{
"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 TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Передайте результаты поиска непосредственно в сообщении пользователя
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"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]. Не учитывается в выходных токенах. |
search_result_index | integer | Индекс (начиная с 0) процитированного результата поиска среди всех блоков search_result в запросе в порядке их появления (во всех сообщениях и результатах инструментов). |
start_block_index | integer | Индекс (начиная с 0) первого процитированного блока в массиве content результата поиска. |
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."
}
],
"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 (
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-5",
max_tokens=1024,
tools=[knowledge_base_tool],
messages=[
{
"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?",
),
],
},
{
"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"},
),
],
},
{
"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)
- Заранее полученный контент: используйте, когда у вас уже есть результаты поиска
- Пакетная обработка: используйте для обработки нескольких результатов поиска одновременно
- Тестирование: используйте для проверки поведения цитирования на известном контенте
Общие рекомендации
-
Эффективно структурируйте результаты:
- Используйте понятные, постоянные URL-адреса источников
- Указывайте описательные заголовки
- Разбивайте длинный контент на логические текстовые блоки, чтобы дать Claude более точные границы цитирования
-
Соблюдайте единообразие:
- Используйте единый формат источников во всём приложении
- Следите, чтобы заголовки точно отражали содержимое
- Поддерживайте единообразное форматирование
-
Корректно обрабатывайте ошибки: если поиск завершился неудачей или ничего не вернул, возвращайте простой текстовый блок с описанием результата (например,
{"type": "text", "text": "No results found."}) вместо генерации ошибки: Claude объяснит пользователю отсутствие результатов, и диалог продолжится.
Ограничения
- Внутри результатов поиска поддерживается только текстовое содержимое (без изображений и других медиафайлов).
- Блоки
search_resultмогут находиться только в сообщениях пользователя (в том числе внутри результатов инструментов). Сообщения ассистента с результатами поиска отклоняются. - Если в том же запросе включён инструмент веб-поиска, цитирование должно быть включено во всех блоках
search_result.
Следующие шаги
Обнаруживайте и обрабатывайте причины остановки из-за отказа в ответах с потоковой передачей и повторяйте отклонённые запросы на резервной модели.
Основывайте ответы Claude на ваших исходных документах. Цитаты возвращают точные фрагменты, подтверждающие каждое утверждение, чтобы вы могли проверять ответы и показывать источники пользователям.
Предоставьте Claude доступ к актуальному веб-контенту с цитируемыми источниками, необязательной динамической фильтрацией и управлением доменами.
Ознакомьтесь с полной документацией по Messages API, включая типы блоков содержимого.
Кэшируйте результаты поиска с помощью cache_control, чтобы снизить стоимость и задержку при повторных запросах.
Доступность
Claude API
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Amazon Bedrock
- API
- Messages API
- Модели
- Все модели
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Модели
- Все модели
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Модели
- Все модели
Microsoft Foundry
- API
- Messages API
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/messagesс источникомsearch_results
Кроме Охватываемые модели
Эта страница была полезной?