Os blocos de conteúdo de resultados de busca permitem que Claude cite seu próprio conteúdo da mesma forma que cita resultados de busca na web: cada citação carrega a fonte e o título que você forneceu. Use-os em aplicações de RAG ("Retrieval-Augmented Generation", geração aumentada por recuperação) onde Claude precisa atribuir respostas aos seus documentos.
Todos os modelos ativos suportam resultados de busca com citações, com exceção do Claude Haiku 3. Nenhum cabeçalho beta é necessário: resultados de busca fazem parte da Messages API padrão.
Resultados de busca podem ser fornecidos de duas maneiras:
Em ambos os casos, Claude cita os resultados de busca 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.
Resultados de busca 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
}
}| 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 busca |
content | array | Um array de blocos de texto contendo o conteúdo real |
| Campo | Tipo | Descrição |
|---|---|---|
citations | object | Configuração de citação com campo booleano enabled. Citações são desabilitadas por padrão; todos os exemplos nesta página definem "enabled": true explicitamente. Todos os resultados de busca em uma solicitação devem usar a mesma configuração (veja 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 real (string não vazia)Resultados de busca contêm apenas texto. Imagens e outras mídias não são suportadas dentro do array content.
Retornar resultados de busca a partir de suas ferramentas personalizadas permite aplicações RAG dinâmicas: as ferramentas buscam conteúdo em tempo de execução, e Claude o cita na resposta. O exemplo a seguir força a chamada da ferramenta com tool_choice, de modo que a etapa de recuperação seja executada todas as vezes.
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},
),
]
# Monte 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?")
]
# Crie 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 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"])
# Adicione o turno de Claude e depois 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
)
],
)
)
# Envie o resultado da ferramenta de volta
final_response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
)
print(final_response)Você também pode fornecer resultados de busca diretamente em mensagens do usuário. Isso é útil para:
from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Forneça os resultados de busca 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)Independentemente de como os resultados de busca são fornecidos, Claude inclui automaticamente citações 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
}
]
}
]
}Cada citação inclui:
| Campo | Tipo | Descrição |
|---|---|---|
type | string | Sempre "search_result_location" para citações de resultados de busca |
source | string | A fonte do resultado de busca original |
title | string ou null | O título do resultado de busca original |
cited_text | string | O texto completo do(s) bloco(s) citado(s), concatenado. Igual 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 busca citado entre todos os blocos search_result na solicitaçã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 busca. |
end_block_index | integer | Índice final exclusivo do intervalo de blocos citados no array content do resultado de busca. Sempre maior que start_block_index. |
Os índices de bloco identificam uma fatia do array content do resultado de busca, e cited_text é o texto completo dessa fatia. O bloco de texto é a unidade citável mínima: 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 busca em blocos menores (veja Múltiplos blocos de conteúdo).
Resultados de busca 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 referenciando o bloco de limites de taxa se parece com:
{
"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 busca é citado, start_block_index e end_block_index identificam quais desses blocos a citação cobre, e cited_text contém exatamente o texto desses blocos. Dividir o conteúdo em blocos menores e focados dá a Claude limites de citação mais precisos; combinar o conteúdo em um único bloco significa que cada citação retorna o texto completo. Este é o mesmo modelo usado por documentos de conteúdo personalizado no recurso de Citações.
Você pode misturar ambos os métodos na mesma conversa. Claude cita de qualquer uma das fontes, e search_result_index conta todos os blocos search_result na ordem da solicitação, independentemente da fonte.
O exemplo a seguir reproduz uma conversa completa. A primeira mensagem do usuário carrega um resultado de busca pré-buscado, o turno do assistente chama uma ferramenta de base de conhecimento, e o resultado da ferramenta retorna um segundo resultado de busca. A resposta de 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é-obtido, 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
}
]
}
]
}Em mensagens do usuário, blocos search_result podem ficar ao lado de qualquer outro bloco de conteúdo. O exemplo do Método 2 combina resultados de busca com uma pergunta em text, e blocos de imagem ou documento podem se juntar a eles da mesma forma.
Resultados de ferramentas são mais rigorosos: 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 busca 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 busca provenientes de ferramentas, inclua-o como um bloco de texto dentro de um dos arrays content dos resultados de busca, onde ele também se torna citável.
Adicione cache_control no bloco de resultado de busca para armazená-lo em cache para reutilização entre solicitaçõ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" }
}Veja Cache de prompt para comprimentos mínimos armazenáveis em cache e outros requisitos.
Por padrão, as citações são desabilitadas para resultados de busca. 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, Claude anexa referências de citação aos blocos de texto que se baseiam no resultado de busca.
Estruture os resultados de forma eficaz:
Mantenha a consistência:
Trate erros com elegância: quando uma busca 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 gerar um erro: Claude explica o resultado vazio ao usuário, e a conversa continua.
search_result só podem aparecer em mensagens do usuário (incluindo dentro de resultados de ferramentas). Mensagens do assistente com resultados de busca são rejeitadas.search_result.Detecte e trate motivos de parada por recusa em respostas com streaming, e repita solicitações recusadas em um modelo alternativo.
Fundamente as respostas de Claude em seus documentos de origem. As citações retornam as passagens exatas que sustentam cada afirmação, para que você possa verificar respostas e exibir fontes aos seus usuários.
Dê a Claude acesso a conteúdo atual da web com fontes citadas, filtragem dinâmica opcional e controles de domínio.
Veja a documentação completa da Messages API, incluindo tipos de blocos de conteúdo.
Armazene em cache resultados de busca com cache_control para reduzir custo e latência em solicitações repetidas.
Was this page helpful?