Os blocos de conteúdo de resultados de pesquisa habilitam citações naturais com atribuição adequada de fonte, trazendo citações de qualidade de pesquisa web para suas aplicações personalizadas. Este recurso é particularmente poderoso para aplicações RAG (Retrieval-Augmented Generation) onde você precisa que o Claude cite fontes com precisão. O recurso de resultados de pesquisa está disponível nos seguintes modelos:
  • Claude 3.5 Haiku (claude-3-5-haiku-20241022)
  • Claude 3.5 Sonnet (claude-3-5-sonnet-20241022)
  • Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)

​
Principais benefícios

  • Citações naturais - Alcance a mesma qualidade de citação da pesquisa 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
  • Não são necessárias soluções alternativas de documento - 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 web do Claude

​
Como funciona

Os resultados de pesquisa podem ser fornecidos de duas maneiras:
  1. A partir de chamadas de ferramentas - Suas ferramentas personalizadas retornam resultados de pesquisa, habilitando aplicações RAG dinâmicas
  2. Como conteúdo de nível superior - Você fornece resultados de pesquisa diretamente em mensagens do usuário para conteúdo pré-buscado ou em cache
Em ambos os casos, o 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 ou identificador da fonte
  "title": "Título do Artigo",                  // Obrigatório: Título do resultado
  "content": [ // Obrigatório: Array de blocos de texto
    {
      "type": "text",
      "text": "O conteúdo real do resultado de pesquisa..."
    }
  ],
  "citations": {                             // Opcional: Configuração de citação
    "enabled": true                          // Habilitar/desabilitar citações para este resultado
  }
}

​
Campos obrigatórios

CampoTipoDescrição
typestringDeve ser "search_result"
sourcestringA URL ou identificador da fonte para o conteúdo
titlestringUm título descritivo para o resultado de pesquisa
contentarrayUm array de blocos de texto contendo o conteúdo real

​
Campos opcionais

CampoTipoDescrição
citationsobjectConfiguração de citação com campo booleano enabled
cache_controlobjectConfigurações de controle de cache (ex: {"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 habilita aplicações RAG dinâmicas onde as ferramentas buscam e retornam conteúdo relevante com citações automáticas.

​
Exemplo: Ferramenta de base de conhecimento

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

client = Anthropic()

# Definir uma ferramenta de pesquisa de base de conhecimento
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Pesquisar a base de conhecimento da empresa por informações",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "A consulta de pesquisa"
            }
        },
        "required": ["query"]
    }
}

# Função para lidar com a chamada da ferramenta
def search_knowledge_base(query):
    # Sua lógica de pesquisa aqui
    # Retorna resultados de pesquisa no formato correto
    return [
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Guia de Configuração do Produto",
            content=[
                TextBlockParam(
                    type="text",
                    text="Para configurar o produto, navegue até Configurações > Configuração. O timeout padrão é de 30 segundos, mas pode ser ajustado entre 10-120 segundos com base em suas necessidades."
                )
            ],
            citations={"enabled": True}
        ),
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Guia de Solução de Problemas",
            content=[
                TextBlockParam(
                    type="text",
                    text="Se você encontrar erros de timeout, primeiro verifique as configurações. Causas comuns incluem latência de rede e valores de timeout incorretos."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Criar uma mensagem com a ferramenta
response = client.messages.create(
    model="claude-sonnet-4-20250514",  # Funciona com todos os modelos suportados
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content="Como configuro as configurações de timeout?"
        )
    ]
)

# Quando o Claude chama a ferramenta, forneça os resultados de pesquisa
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Enviar o resultado da ferramenta de volta
    final_response = client.messages.create(
        model="claude-sonnet-4-20250514",  # Funciona com todos os modelos suportados
        max_tokens=1024,
        messages=[
            MessageParam(role="user", content="Como configuro as configurações de timeout?"),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Resultados de pesquisa vão aqui
                    )
                ]
            )
        ]
    )

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

Você também pode fornecer resultados de pesquisa diretamente em mensagens do 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
  • Teste e desenvolvimento

​
Exemplo: Resultados de pesquisa diretos

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

client = Anthropic()

# Fornecer resultados de pesquisa diretamente na mensagem do usuário
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="Referência da API - Autenticação",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Todas as solicitações da API devem incluir uma chave de API no cabeçalho Authorization. As chaves podem ser geradas no painel. Limites de taxa: 1000 solicitações por hora para o nível padrão, 10000 para premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Guia de Início Rápido",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Para começar: 1) Inscreva-se para uma conta, 2) Gere uma chave de API no painel, 3) Instale nosso SDK usando pip install company-sdk, 4) Inicialize o cliente com sua chave de API."
                        )
                    ],
                    citations={"enabled": True}
                ),
                TextBlockParam(
                    type="text",
                    text="Com base nestes resultados de pesquisa, como autentico solicitações da API e quais são os limites de taxa?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

​
Resposta do Claude com citações

Independentemente de como os resultados de pesquisa são fornecidos, o Claude inclui automaticamente citações ao usar informações deles: 
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Para autenticar solicitações da API, você precisa incluir uma chave de API no cabeçalho Authorization",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referência da API - Autenticação",
          "cited_text": "Todas as solicitações da API devem incluir uma chave de API no cabeçalho Authorization",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Você pode gerar chaves de API no seu painel",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referência da API - Autenticação",
          "cited_text": "As chaves podem ser geradas no painel",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Os limites de taxa são 1.000 solicitações por hora para o nível padrão e 10.000 solicitações por hora para o nível premium.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referência da API - Autenticação",
          "cited_text": "Limites de taxa: 1000 solicitações por hora para o nível padrão, 10000 para premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

​
Campos de citação

Cada citação inclui:
CampoTipoDescrição
typestringSempre "search_result_location" para citações de resultados de pesquisa
sourcestringA fonte do resultado de pesquisa original
titlestring ou nullO título do resultado de pesquisa original
cited_textstringO texto exato sendo citado
search_result_indexintegerÍndice do resultado de pesquisa (baseado em 0)
start_block_indexintegerPosição inicial no array de conteúdo
end_block_indexintegerPosição final no array de conteúdo
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": "Documentação da API",
  "content": [
    {
      "type": "text",
      "text": "Autenticação: Todas as solicitações da API requerem uma chave de API."
    },
    {
      "type": "text",
      "text": "Limites de Taxa: A API permite 1000 solicitações por hora por chave."
    },
    {
      "type": "text",
      "text": "Tratamento de Erros: A API retorna códigos de status HTTP padrão."
    }
  ]
}
O 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 tanto resultados de pesquisa baseados em ferramentas quanto de nível superior na mesma conversa: 
# Primeira mensagem com resultados de pesquisa de nível superior
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Visão Geral do Produto",
                content=[
                    TextBlockParam(type="text", text="Nosso produto ajuda equipes a colaborar...")
                ],
                citations={"enabled": True}
            ),
            TextBlockParam(
                type="text",
                text="Me fale sobre este produto e pesquise informações de preços"
            )
        ]
    )
]

# O Claude pode responder e chamar uma ferramenta para pesquisar preços
# Então você fornece resultados de ferramentas com mais resultados de pesquisa

​
Combinando com outros tipos de conteúdo

Ambos os métodos suportam misturar resultados de pesquisa com outros conteúdos: 
# Em resultados de ferramentas
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Guia do Usuário",
        content=[TextBlockParam(type="text", text="Detalhes de configuração...")],
        citations={"enabled": True}
    ),
    TextBlockParam(
        type="text",
        text="Contexto adicional: Isso se aplica à versão 2.0 e posteriores."
    )
]

# Em conteúdo de nível superior
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Artigo de Pesquisa",
        content=[TextBlockParam(type="text", text="Principais descobertas...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    TextBlockParam(
        type="text",
        text="Como o gráfico se relaciona com as descobertas da pesquisa?"
    )
]

​
Controle de cache

Adicione controle de cache para melhor desempenho: 
{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Guia do Usuário",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

​
Controle de citação

Por padrão, as citações estão desabilitadas para resultados de pesquisa. Você pode habilitar citações definindo explicitamente a configuração citations: 
{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Guia do Usuário",
  "content": [{"type": "text", "text": "Documentação importante..."}],
  "citations": {
    "enabled": true  // Habilitar citações para este resultado
  }
}
Quando citations.enabled está definido como true, o Claude incluirá referências de citação ao usar informações do resultado de pesquisa. Isso habilita:
  • 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 web para qualquer ferramenta personalizada que retorna resultados de pesquisa
Se o campo citations for omitido, as citações são desabilitadas 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 habilitadas, ou todos devem tê-las desabilitadas. Misturar resultados de pesquisa com diferentes configurações de citação resultará em erro. Se você precisar desabilitar citações para algumas fontes, deve desabilitá-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 resultados: Retorne apenas os resultados mais relevantes para evitar sobrecarga 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
  • Teste: Ótimo para testar comportamento de citação com conteúdo conhecido

​
Melhores práticas gerais

  1. 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
  2. Mantenha consistência
    • Use formatos de fonte consistentes em sua aplicação
    • Certifique-se de que os títulos reflitam com precisão o conteúdo
    • Mantenha formatação consistente
  3. Trate erros graciosamente 
    def search_with_fallback(query):
    try:
        results = perform_search(query)
        if not results:
            return {"type": "text", "text": "Nenhum resultado encontrado."}
        return format_as_search_results(results)
    except Exception as e:
        return {"type": "text", "text": f"Erro de pesquisa: {str(e)}"}

​
Limitações

  • Blocos de conteúdo de resultados de pesquisa estão disponíveis na API da Anthropic e no Vertex AI do Google Cloud
  • Apenas conteúdo de texto é suportado dentro dos resultados de pesquisa (sem imagens ou outras mídias)
  • O array content deve conter pelo menos um bloco de texto