Os blocos de conteúdo de resultados de pesquisa estão atualmente em beta. Use o cabeçalho beta search-results-2025-06-09 para habilitar este recurso.

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 (Geração Aumentada por Recuperação) onde você precisa que Claude cite fontes com precisão.

​
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, 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.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam,
    BetaToolResultBlockParam
)

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 [
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Guia de Configuração do Produto",
            content=[
                BetaTextBlockParam(
                    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}
        ),
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Guia de Solução de Problemas",
            content=[
                BetaTextBlockParam(
                    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.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    tools=[knowledge_base_tool],
    messages=[
        BetaMessageParam(
            role="user",
            content="Como configuro as configurações de timeout?"
        )
    ]
)

# Quando 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.beta.messages.create(
        model="claude-opus-4-20250514",
        max_tokens=1024,
        betas=["search-results-2025-06-09"],
        messages=[
            BetaMessageParam(role="user", content="Como configuro as configurações de timeout?"),
            BetaMessageParam(role="assistant", content=response.content),
            BetaMessageParam(
                role="user",
                content=[
                    BetaToolResultBlockParam(
                        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.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam
)

client = Anthropic()

# Fornecer resultados de pesquisa diretamente na mensagem do usuário
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    messages=[
        BetaMessageParam(
            role="user",
            content=[
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="Referência da API - Autenticação",
                    content=[
                        BetaTextBlockParam(
                            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}
                ),
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Guia de Início Rápido",
                    content=[
                        BetaTextBlockParam(
                            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}
                ),
                BetaTextBlockParam(
                    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, 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."
    }
  ]
}

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:

# Primeira mensagem com resultados de pesquisa de nível superior
messages = [
    BetaMessageParam(
        role="user",
        content=[
            BetaSearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Visão Geral do Produto",
                content=[
                    BetaTextBlockParam(type="text", text="Nosso produto ajuda equipes a colaborar...")
                ],
                citations={"enabled": True}
            ),
            BetaTextBlockParam(
                type="text",
                text="Me conte sobre este produto e pesquise informações de preços"
            )
        ]
    )
]

# 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ú

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

# Em resultados de ferramentas
tool_result = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Guia do Usuário",
        content=[BetaTextBlockParam(type="text", text="Detalhes de configuração...")],
        citations={"enabled": True}
    ),
    BetaTextBlockParam(
        type="text",
        text="Contexto adicional: Isso se aplica à versão 2.0 e posteriores."
    )
]

# Em conteúdo de nível superior
user_content = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Artigo de Pesquisa",
        content=[BetaTextBlockParam(type="text", text="Principais descobertas...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    BetaTextBlockParam(
        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, 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
    • Garanta 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 apenas com o cabeçalho beta
  • 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