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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

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

Функция результатов поиска доступна на следующих моделях:

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 (claude-opus-4-20250514)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (устарела) (claude-3-7-sonnet-20250219)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Haiku 3.5 (устарела) (claude-3-5-haiku-20241022)

Ключевые преимущества

Естественные цитирования - Достигните того же качества цитирования, что и веб-поиск, для любого содержимого
Гибкая интеграция - Используйте в возвращаемых значениях инструментов для динамического RAG или как содержимое верхнего уровня для предварительно загруженных данных
Надлежащее указание источника - Каждый результат включает информацию об источнике и названии для четкого указания авторства
Не требуются обходные решения на основе документов - Исключает необходимость в обходных решениях на основе документов
Согласованный формат цитирования - Соответствует качеству и формату цитирования функции веб-поиска Claude

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

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

Из вызовов инструментов - Ваши пользовательские инструменты возвращают результаты поиска, обеспечивая динамические приложения RAG
Как содержимое верхнего уровня - Вы предоставляете результаты поиска непосредственно в сообщениях пользователя для предварительно загруженного или кэшированного содержимого

В обоих случаях Claude может автоматически цитировать информацию из результатов поиска с надлежащим указанием источника.

Схема результата поиска

Результаты поиска используют следующую структуру:

{
  "type": "search_result",
  "source": "https://example.com/article", // Обязательно: URL источника или идентификатор
  "title": "Article Title", // Обязательно: Название результата
  "content": [
    // Обязательно: Массив текстовых блоков
    {
      "type": "text",
      "text": "The actual content of the search result..."
    }
  ],
  "citations": {
    // Опционально: Конфигурация цитирования
    "enabled": true // Включить/отключить цитирования для этого результата
  }
}

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

Поле	Тип	Описание
`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": "To authenticate API requests, you need to include an API key in the Authorization header",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "All API requests must include an API key in the Authorization header",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". You can generate API keys from your dashboard",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Keys can be generated from the dashboard",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". The rate limits are 1,000 requests per hour for the standard tier and 10,000 requests per hour for the premium tier.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Rate limits: 1000 requests per hour for standard tier, 10000 for premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

Поля цитат

Каждая цитата включает:

Поле	Тип	Описание
`type`	строка	Всегда `"search_result_location"` для цитат результатов поиска
`source`	строка	Источник из исходного результата поиска
`title`	строка или null	Название из исходного результата поиска
`cited_text`	строка	Точный цитируемый текст
`search_result_index`	целое число	Индекс результата поиска (начиная с 0)
`start_block_index`	целое число

Примечание: search_result_index относится к индексу блока содержимого результата поиска (начиная с 0), независимо от того, как были предоставлены результаты поиска (вызов инструмента или содержимое верхнего уровня).

Несколько блоков содержимого

Результаты поиска могут содержать несколько текстовых блоков в массиве 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."
    }
  ]
}

Claude может цитировать конкретные блоки, используя поля start_block_index и end_block_index.

Продвинутое использование

Объединение обоих методов

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

from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam

# First message with top-level search results
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 might respond and call a tool to search for pricing
# Then you provide tool results with more search results

Объединение с другими типами содержимого

Оба метода поддерживают смешивание результатов поиска с другим содержимым:

from anthropic.types import SearchResultBlockParam, TextBlockParam

# In tool results
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."
    ),
]

# In top-level content
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
Атрибуция источника при работе с собственными базами знаний
Цитаты качества веб-поиска для любого пользовательского инструмента, который возвращает результаты поиска

Если поле citations опущено, цитаты отключены по умолчанию.

Цитаты — это всё или ничего: либо все результаты поиска в запросе должны иметь включённые цитаты, либо все должны иметь отключённые. Смешивание результатов поиска с разными параметрами цитат приводит к ошибке. Если вам нужно отключить цитаты для некоторых источников, вы должны отключить их для всех результатов поиска в этом запросе.

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

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

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

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

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

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

Эффективно структурируйте результаты
- Используйте чёткие, постоянные URL-адреса источников
- Предоставляйте описательные названия
- Разбивайте длинное содержимое на логические текстовые блоки
Поддерживайте согласованность
- Используйте согласованные форматы источников в вашем приложении
- Убедитесь, что названия точно отражают содержимое
- Сохраняйте форматирование согласованным

Обрабатывайте ошибки корректно

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's Vertex AI
Внутри результатов поиска поддерживается только текстовое содержимое (без изображений или других медиа)
Массив content должен содержать по крайней мере один текстовый блок

from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam,
    ToolResultBlockParam,
)

client = Anthropic()

# Define a knowledge base search tool
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"],
    },
}


# Function to handle the tool call
def search_knowledge_base(query):
    # Your search logic here
    # Returns search results in the correct format
    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},
        ),
    ]


# Create a message with the tool
response = client.messages.create(
    model="claude-opus-4-6",  # Works with all supported models
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(role="user", content="How do I configure the timeout settings?")
    ],
)

# When Claude calls the tool, provide the search results
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])

    # Send the tool result back
    final_response = client.messages.create(
        model="claude-opus-4-6",  # 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
                    )
                ],
            ),
        ],
    )

#!/bin/sh
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "search_result",
                    "source": "https://docs.company.com/api-reference",
                    "title": "API Reference - Authentication",
                    "content": [
                        {
                            "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
                    }
                },
                {
                    "type": "search_result",
                    "source": "https://docs.company.com/quickstart",
                    "title": "Getting Started Guide",
                    "content": [
                        {
                            "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
                    }
                },
                {
                    "type": "text",
                    "text": "Based on these search results, how do I authenticate API requests and what are the rate limits?"
                }
            ]
        }
    ]
}'