MessagesCapacidades do modelo

Resultados de pesquisa

Habilite citações naturais para aplicações RAG fornecendo resultados de pesquisa com atribuição de fonte

Os blocos de conteúdo de resultados de pesquisa permitem que o Claude cite seu próprio conteúdo da mesma forma que cita resultados de pesquisa na web: cada citação carrega a fonte e o título que você forneceu. Use-os em aplicações de "Retrieval-Augmented Generation" (geração aumentada por recuperação), ou RAG, nas quais o Claude precisa atribuir respostas aos seus documentos.

Todos os modelos ativos suportam resultados de pesquisa com citações, com exceção do Claude Haiku 3. Nenhum cabeçalho beta é necessário: os resultados de pesquisa fazem parte da Messages API padrão.

Como funciona

Os resultados de pesquisa podem ser fornecidos de duas maneiras:

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

Em ambos os casos, o Claude cita os resultados de pesquisa automaticamente quando as citações estão habilitadas. Nenhum prompt especial é necessário: faça sua pergunta, e as citações aparecem nos blocos de texto que se baseiam no seu conteúdo.

Esquema do 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

Campo	Tipo	Descrição
`type`	string	Deve ser `"search_result"`
`source`	string	A fonte do conteúdo. Qualquer string estável funciona: uma URL ou um identificador interno como `kb://article-1234`
`title`	string	Um título descritivo para o resultado de pesquisa
`content`	array	Um array de blocos de texto contendo o conteúdo propriamente dito

Campos opcionais

Campo	Tipo	Descrição
`citations`	object	Configuração de citações com o campo booleano `enabled`. As citações são desabilitadas por padrão; todos os exemplos nesta página definem `"enabled": true` explicitamente. Todos os resultados de pesquisa em uma requisição devem usar a mesma configuração (consulte Controle de citações)
`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 propriamente dito (string não vazia)

Os resultados de pesquisa contêm apenas texto. Imagens e outras mídias não são suportadas dentro do array content.

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

Retornar resultados de pesquisa a partir de suas ferramentas personalizadas possibilita aplicações RAG dinâmicas: as ferramentas buscam conteúdo em tempo de execução, e o Claude o cita na resposta. O exemplo a seguir força a chamada da ferramenta com tool_choice, para que a etapa de recuperação seja executada todas as vezes.

Exemplo: Ferramenta de base de conhecimento

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

client = Anthropic()

# Define 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 lidar com 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},
        ),
    ]


# Constrói a conversa em uma lista, começando com a pergunta do usuário
messages = [
    MessageParam(role="user", content="How do I configure the timeout settings?")
]

# Cria uma mensagem com a ferramenta
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    tool_choice={"type": "tool", "name": "search_knowledge_base"},
    messages=messages,
)

# Quando o Claude chamar a ferramenta, forneça os resultados da busca.
# O bloco tool_use nem sempre é o primeiro: itere para encontrá-lo.
tool_use = next((block for block in response.content if block.type == "tool_use"), None)
if tool_use is not None:
    tool_result = search_knowledge_base(tool_use.input["query"])

    # Adiciona o turno do Claude e, em seguida, o resultado da ferramenta à conversa em andamento
    messages.append(MessageParam(role="assistant", content=response.content))
    messages.append(
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id=tool_use.id,
                    content=tool_result,  # Search results go here
                )
            ],
        )
    )

    # Envia o resultado da ferramenta de volta
    final_response = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        messages=messages,
    )
    print(final_response)

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

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

Conteúdo pré-buscado 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 de pesquisa diretamente na mensagem do usuário
response = client.messages.create(
    model="claude-opus-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)

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:

Campo	Tipo	Descrição
`type`	string	Sempre `"search_result_location"` para citações de resultados 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 completo do(s) bloco(s) citado(s), concatenado. Equivale ao conteúdo de `content[start_block_index:end_block_index]` unido. Não é contabilizado nos tokens de saída.
`search_result_index`	integer	Índice baseado em 0 do resultado de pesquisa citado entre todos os blocos `search_result` na requisição, na ordem em que aparecem (em todas as mensagens e resultados de ferramentas).
`start_block_index`	integer	Índice baseado em 0 do primeiro bloco citado no array `content` do resultado de pesquisa.
`end_block_index`	integer	Índice final exclusivo do intervalo de blocos citados no array `content` do resultado de pesquisa. Sempre maior que `start_block_index`.

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."
    }
  ],
  "citations": { "enabled": true }
}

Uma citação que referencia o bloco de limites de taxa tem esta 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 este 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 toda citação retorna o texto completo. Este é o mesmo modelo usado pelos documentos de conteúdo personalizado no recurso de Citações.

Uso avançado

Combinando ambos os métodos

Você pode misturar ambos os métodos na mesma conversa. O Claude cita a partir de qualquer uma das fontes, e search_result_index conta todos os blocos search_result na ordem da requisição, independentemente da fonte.

O exemplo a seguir reproduz uma conversa completa. A primeira mensagem do usuário carrega um resultado de pesquisa pré-buscado, o turno do assistente chama uma ferramenta de base de conhecimento, e o resultado da ferramenta retorna um segundo resultado de pesquisa. A resposta do Claude cita ambas as fontes:

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

client = Anthropic()

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

# Reproduz uma conversa que fornece resultados de busca das duas formas: a primeira
# mensagem do usuário traz um resultado pré-buscado, o resultado da ferramenta retorna outro
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/overview",
                    title="Product Overview",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
                        )
                    ],
                    citations={"enabled": True},
                ),
                TextBlockParam(
                    type="text",
                    text="What does Acme Dashboard do, and what plans is it available on?",
                ),
            ],
        ),
        MessageParam(
            role="assistant",
            content=[
                TextBlockParam(
                    type="text", text="Let me check the pricing information."
                ),
                ToolUseBlockParam(
                    type="tool_use",
                    id="toolu_01A09q90qw90lq917835lq9",
                    name="search_knowledge_base",
                    input={"query": "Acme Dashboard pricing plans"},
                ),
            ],
        ),
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id="toolu_01A09q90qw90lq917835lq9",
                    content=[
                        SearchResultBlockParam(
                            type="search_result",
                            source="https://docs.company.com/pricing",
                            title="Pricing Plans",
                            content=[
                                TextBlockParam(
                                    type="text",
                                    text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
                                )
                            ],
                            citations={"enabled": True},
                        )
                    ],
                )
            ],
        ),
    ],
)

print(response)

A resposta cita ambas as fontes. O resultado pré-buscado é search_result_index: 0 e o resultado retornado pela ferramenta é search_result_index: 1, correspondendo à ordem em que os blocos search_result aparecem na conversa:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's what I found about Acme Dashboard:\n\n**What it does:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
          "source": "https://docs.company.com/overview",
          "title": "Product Overview",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    },
    {
      "type": "text",
      "text": "\n\n**Available plans:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
          "source": "https://docs.company.com/pricing",
          "title": "Pricing Plans",
          "search_result_index": 1,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Misturando com outros tipos de conteúdo

Nas mensagens do usuário, os blocos search_result podem ficar ao lado de qualquer outro bloco de conteúdo. O exemplo do Método 2 combina resultados de pesquisa com uma pergunta em text, e blocos de imagem ou documento podem se juntar a eles da mesma forma.

Os resultados de ferramentas são mais restritos: se qualquer bloco em um array de conteúdo de tool_result for um search_result, todos os seus blocos devem ser search_result. Misturar resultados de pesquisa com outros tipos de bloco no mesmo resultado de ferramenta retorna um erro de validação. Para retornar texto de apoio junto com resultados de pesquisa provenientes de ferramentas, inclua-o como um bloco de texto dentro do array content de um dos resultados de pesquisa, onde ele também se torna citável.

Controle de cache

Adicione cache_control no bloco do resultado de pesquisa para armazená-lo em cache para reutilização entre requisições. Ele fica ao lado de citations no mesmo bloco:

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

Consulte Cache de prompt para comprimentos mínimos armazenáveis em cache e outros requisitos.

Controle de citações

Por padrão, as citações sã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 é definido como true, o Claude anexa referências de citação aos blocos de texto que se baseiam no resultado 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é-buscado: 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ções com conteúdo conhecido

Melhores práticas gerais

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
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
Trate erros com elegância: quando uma pesquisa falhar ou não retornar nada, retorne um bloco de texto simples descrevendo o resultado (por exemplo, {"type": "text", "text": "No results found."}) em vez de lançar um erro: o Claude explica o resultado vazio ao usuário, e a conversa continua.

Limitações

Os blocos de conteúdo de resultados de pesquisa estão disponíveis na Claude API, no Amazon Bedrock e no Google Cloud.
Apenas conteúdo de texto é suportado dentro dos resultados de pesquisa (sem imagens ou outras mídias).
Os blocos search_result só podem aparecer em mensagens do usuário (inclusive dentro de resultados de ferramentas). Mensagens do assistente com resultados de pesquisa são rejeitadas.
Quando a ferramenta de pesquisa na web está habilitada na mesma requisição, as citações devem estar habilitadas em todos os blocos search_result.

Próximos passos

Recusas em streaming

Detecte e trate motivos de parada por recusa em respostas de streaming, e tente novamente as requisições recusadas em um modelo de fallback.

Citações

Fundamente as respostas do Claude nos seus documentos de origem. As citações retornam as passagens exatas que sustentam cada afirmação, para que você possa verificar as respostas e exibir as fontes aos seus usuários.

Ferramenta de pesquisa na web

Dê ao Claude acesso a conteúdo atual da web com fontes citadas, filtragem dinâmica opcional e controles de domínio.

Referência da Messages API

Consulte a documentação completa da Messages API, incluindo os tipos de blocos de conteúdo.

Cache de prompt

Armazene resultados de pesquisa em cache com cache_control para reduzir custo e latência em requisições repetidas.

Como funciona

Esquema do resultado de pesquisa

Campos obrigatórios

Campos opcionais

Método 1: Resultados de pesquisa a partir de chamadas de ferramentas

Exemplo: Ferramenta de base de conhecimento

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

Exemplo: Resultados de pesquisa diretos

Resposta do Claude com citações

Campos de citação

Múltiplos blocos de conteúdo

Uso avançado

Combinando ambos os métodos

Misturando com outros tipos de conteúdo

Controle de cache

Controle de citações

Melhores práticas

Para pesquisa baseada em ferramentas (Método 1)

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

Melhores práticas gerais

Limitações

Próximos passos