Resultados de pesquisa

Os blocos de conteúdo de resultados de pesquisa permitem citações naturais com atribuição adequada de fonte, trazendo citações de qualidade de pesquisa na web para suas aplicações personalizadas. Este recurso é particularmente poderoso para aplicações RAG (Retrieval-Augmented Generation) onde você precisa que Claude cite fontes com precisão.

O recurso de resultados de pesquisa está disponível nos seguintes modelos:

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.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (descontinuado) (claude-3-7-sonnet-20250219)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Haiku 3.5 (descontinuado) (claude-3-5-haiku-20241022)

Principais benefícios

Citações naturais - Alcance a mesma qualidade de citação que a pesquisa na web para qualquer conteúdo
Integração flexível - Use em retornos de ferramentas para RAG dinâmico ou como conteúdo de nível superior para dados pré-buscados
Atribuição adequada de fonte - Cada resultado inclui informações de fonte e título para atribuição clara
Sem necessidade de soluções alternativas de documentos - Elimina a necessidade de soluções alternativas baseadas em documentos
Formato de citação consistente - Corresponde à qualidade e formato de citação da funcionalidade de pesquisa na web do Claude

Como funciona

Os resultados de pesquisa podem ser fornecidos de duas maneiras:

De chamadas de ferramentas - Suas ferramentas personalizadas retornam resultados de pesquisa, permitindo aplicações RAG dinâmicas
Como conteúdo de nível superior - Você fornece resultados de pesquisa diretamente em mensagens de usuário para conteúdo pré-buscado ou em cache

Em ambos os casos, Claude pode citar automaticamente informações dos resultados de pesquisa com atribuição adequada de fonte.

Esquema de resultado de pesquisa

Os resultados de pesquisa usam a seguinte estrutura:

{
  "type": "search_result",
  "source": "https://example.com/article",  // Obrigatório: URL de fonte ou identificador
  "title": "Article Title",                  // Obrigatório: Título do resultado
  "content": [                               // Obrigatório: Array de blocos de texto
    {
      "type": "text",
      "text": "The actual content of the search result..."
    }
  ],
  "citations": {                             // Opcional: Configuração de citação
    "enabled": true                          // Ativar/desativar citações para este resultado
  }
}

Campos obrigatórios

Campo	Tipo	Descrição
`type`	string	Deve ser `"search_result"`
`source`	string	A URL de fonte ou identificador do conteúdo
`title`	string	Um título descritivo para o resultado de pesquisa
`content`	array	Um array de blocos de texto contendo o conteúdo real

Campos opcionais

Campo	Tipo	Descrição
`citations`	object	Configuração de citação com campo booleano `enabled`
`cache_control`	object	Configurações de controle de cache (por exemplo, `{"type": "ephemeral"}`)

Cada item no array content deve ser um bloco de texto com:

type: Deve ser "text"
text: O conteúdo de texto real (string não vazia)

Método 1: Resultados de pesquisa de chamadas de ferramentas

O caso de uso mais poderoso é retornar resultados de pesquisa de suas ferramentas personalizadas. Isso permite aplicações RAG dinâmicas onde ferramentas buscam e retornam conteúdo relevante com citações automáticas.

Exemplo: Ferramenta de base de conhecimento

Método 2: Resultados de pesquisa como conteúdo de nível superior

Você também pode fornecer resultados de pesquisa diretamente em mensagens de usuário. Isso é útil para:

Conteúdo pré-buscado de sua infraestrutura de pesquisa
Resultados de pesquisa em cache de consultas anteriores
Conteúdo de serviços de pesquisa externos
Testes e desenvolvimento

Exemplo: Resultados de pesquisa diretos

Resposta do Claude com citações

Independentemente de como os resultados de pesquisa são fornecidos, Claude inclui automaticamente citações ao usar informações deles:

{
  "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
        }
      ]
    }
  ]
}

Campos de citação

Cada citação inclui:

Campo	Tipo	Descrição
`type`	string	Sempre `"search_result_location"` para citações de resultado de pesquisa
`source`	string	A fonte do resultado de pesquisa original
`title`	string ou null	O título do resultado de pesquisa original
`cited_text`	string	O texto exato sendo citado
`search_result_index`	integer	Índice do resultado de pesquisa (baseado em 0)
`start_block_index`	integer

Nota: O search_result_index refere-se ao índice do bloco de conteúdo do resultado de pesquisa (baseado em 0), independentemente de como os resultados de pesquisa foram fornecidos (chamada de ferramenta ou conteúdo de nível superior).

Múltiplos blocos de conteúdo

Os resultados de pesquisa podem conter múltiplos blocos de texto no array 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 pode citar blocos específicos usando os campos start_block_index e end_block_index.

Uso avançado

Combinando ambos os métodos

Você pode usar resultados de pesquisa baseados em ferramentas e de nível superior na mesma conversa:

# 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

Combinando com outros tipos de conteúdo

Ambos os métodos suportam misturar resultados de pesquisa com outro conteúdo:

# 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?"
    )
]

Controle de cache

Adicione controle de cache para melhor desempenho:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

Controle de citação

Por padrão, as citações são desativadas para resultados de pesquisa. Você pode ativar citações definindo explicitamente a configuração 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
  }
}

Quando citations.enabled é definido como true, Claude incluirá referências de citação ao usar informações do resultado de pesquisa. Isso permite:

Citações naturais para suas aplicações RAG personalizadas
Atribuição de fonte ao interfacear com bases de conhecimento proprietárias
Citações de qualidade de pesquisa na web para qualquer ferramenta personalizada que retorna resultados de pesquisa

Se o campo citations for omitido, as citações serão desativadas por padrão.

As citações são tudo ou nada: ou todos os resultados de pesquisa em uma solicitação devem ter citações ativadas, ou todos devem tê-las desativadas. Misturar resultados de pesquisa com diferentes configurações de citação resultará em um erro. Se você precisar desativar citações para algumas fontes, você deve desativá-las para todos os resultados de pesquisa nessa solicitação.

Melhores práticas

Para pesquisa baseada em ferramentas (Método 1)

Conteúdo dinâmico: Use para pesquisas em tempo real e aplicações RAG dinâmicas
Tratamento de erros: Retorne mensagens apropriadas quando as pesquisas falharem
Limites de resultado: Retorne apenas os resultados mais relevantes para evitar estouro de contexto

Para pesquisa de nível superior (Método 2)

Conteúdo pré-buscado: Use quando você já tem resultados de pesquisa
Processamento em lote: Ideal para processar múltiplos resultados de pesquisa de uma vez
Testes: Ótimo para testar comportamento de citação com conteúdo conhecido

Melhores práticas gerais

Estruture resultados efetivamente
- Use URLs de fonte claras e permanentes
- Forneça títulos descritivos
- Divida conteúdo longo em blocos de texto lógicos
Mantenha consistência
- Use formatos de fonte consistentes em sua aplicação
- Garanta que os títulos reflitam com precisão o conteúdo
- Mantenha a formatação consistente

Trate erros graciosamente

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)}"}

Limitações

Os blocos de conteúdo de resultado de pesquisa estão disponíveis na Claude API, Amazon Bedrock e Google Cloud's Vertex AI
Apenas conteúdo de texto é suportado dentro de resultados de pesquisa (sem imagens ou outras mídias)
O array content deve conter pelo menos um bloco de texto

from anthropic import Anthropic
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-sonnet-4-5",  # 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-sonnet-4-5",  # 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 import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam
)

client = Anthropic()

# Provide search results directly in the user message
response = client.messages.create(
    model="claude-sonnet-4-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.model_dump_json(indent=2))