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 com qualidade de pesquisa na web para suas aplicações personalizadas. Esse recurso é particularmente poderoso para aplicações "RAG" (Retrieval-Augmented Generation, ou geração aumentada por recuperação), nas quais você precisa que o Claude cite fontes com precisão.

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

• Claude Opus 4.8 (claude-opus-4-8)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 5 (claude-sonnet-5)
• 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 (descontinuado) (claude-opus-4-1-20250805)
• Claude Opus 4 (desativado, exceto no Google Cloud) (claude-opus-4-20250514)
• Claude Sonnet 4 (desativado, exceto no Bedrock e Google Cloud) (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (desativado, exceto no Bedrock e Google Cloud) (claude-3-5-haiku-20241022)



Principais benefícios

• Citações naturais: Obtenha a mesma qualidade de citação da 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é-carregados
• 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 com documentos: Elimina a necessidade de soluções alternativas baseadas em documentos
• Formato de citação consistente: Corresponde à qualidade e ao formato de citação da funcionalidade de pesquisa na 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, permitindo 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é-carregado 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", // 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
  }
}



Campos obrigatórios



Campos opcionais

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 a partir de chamadas de ferramentas

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



Exemplo: Ferramenta de base de conhecimento

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

client = Anthropic()

# Defina uma ferramenta de busca na base de conhecimento
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"],
    },
}


# Função para tratar a chamada da ferramenta
def search_knowledge_base(query):
    # Sua lógica de busca aqui
    # Retorna os resultados da busca no formato correto
    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},
        ),
    ]


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

# Quando o Claude chamar a ferramenta, forneça os resultados da busca
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])

    # Envie o resultado da ferramenta de volta
    final_response = client.messages.create(
        model="claude-opus-4-8",  # 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
                    )
                ],
            ),
        ],
    )



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é-carregado da 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

from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam

client = Anthropic()

# Forneça os resultados da pesquisa diretamente na mensagem do usuário
response = client.messages.create(
    model="claude-opus-4-8",
    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)



Resposta do Claude com citações

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

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



Campos de citação

Cada citação inclui:

Os índices de bloco identificam uma fatia do array content do resultado de pesquisa, e cited_text é o texto completo dessa fatia. O bloco de texto é a unidade mínima citável: o Claude cita blocos inteiros, não substrings dentro de um bloco. Para obter citações mais granulares, divida o conteúdo do seu resultado de pesquisa em blocos menores (consulte Múltiplos blocos de conteúdo).



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

Uma citação referenciando o bloco de limites de taxa tem a seguinte aparência:

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

Quando esse resultado de pesquisa é citado, start_block_index e end_block_index identificam quais desses blocos a citação abrange, e cited_text contém exatamente o texto desses blocos. Dividir o conteúdo em blocos menores e focados dá ao Claude limites de citação mais precisos; combinar o conteúdo em um único bloco significa que cada citação retorna o texto completo. Esse é o mesmo modelo usado por documentos de conteúdo personalizado no recurso de Citações.



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:

from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam

# Primeira mensagem com resultados de pesquisa no nível superior
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",
            ),
        ],
    )
]

# O Claude pode responder e chamar uma ferramenta para pesquisar preços
# Em seguida, você fornece resultados da ferramenta com mais resultados de pesquisa



Combinando com outros tipos de conteúdo

Ambos os métodos suportam a combinação de resultados de pesquisa com outros conteúdos:

from anthropic.types import SearchResultBlockParam, TextBlockParam

# Em resultados de ferramentas
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."
    ),
]

# Em conteúdo de nível superior
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 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": "User Guide",
  "content": [{ "type": "text", "text": "Important documentation..." }],
  "citations": {
    "enabled": true // Enable citations for this result
  }
}

Quando citations.enabled está definido como true, o Claude inclui 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 interagir com bases de conhecimento proprietárias
• Citações com qualidade de pesquisa na web para qualquer ferramenta personalizada que retorne resultados de pesquisa



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 estouro de contexto



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

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



Melhores práticas gerais

1. Estruture os resultados de forma eficaz:

   • Use URLs de fonte claras e permanentes
   • Forneça títulos descritivos
   • Divida conteúdo longo em blocos de texto lógicos para dar ao Claude limites de citação mais precisos

2. Mantenha a consistência:

   • Use formatos de fonte consistentes em toda a sua aplicação
   • Garanta que os títulos reflitam o conteúdo com precisão
   • Mantenha a formatação consistente

3. Trate erros de forma adequada:

   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 resultados de pesquisa estão disponíveis na API do Claude, Amazon Bedrock e Google Cloud
• 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



Próximos passos