---
title: Risultati di ricerca
url: https://platform.claude.com/docs/it/build-with-claude/search-results
description: Abilita citazioni naturali per applicazioni RAG fornendo risultati di ricerca con attribuzione della fonte
---
Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
I blocchi di contenuto dei risultati di ricerca consentono a Claude di citare i tuoi contenuti nello stesso modo in cui cita i risultati di ricerca web: ogni citazione riporta la fonte e il titolo che hai fornito. Usali nelle applicazioni RAG ("Retrieval-Augmented Generation", generazione aumentata dal recupero) in cui Claude deve attribuire le risposte ai tuoi documenti.
Tutti i [modelli attivi](https://platform.claude.com/docs/it/models/overview) supportano i risultati di ricerca con citazioni, ad eccezione di Claude Haiku 3. Non è richiesto alcun header beta: i risultati di ricerca fanno parte della Messages API standard.
## Come funziona
I risultati di ricerca possono essere forniti in due modi:
1. **Dalle chiamate agli strumenti:** I tuoi strumenti personalizzati restituiscono risultati di ricerca, abilitando applicazioni RAG dinamiche
2. **Come contenuto di primo livello:** Fornisci i risultati di ricerca direttamente nei messaggi utente per contenuti pre-recuperati o memorizzati in cache
In entrambi i casi, Claude cita automaticamente i risultati di ricerca quando le citazioni sono abilitate. Non è necessario alcun prompt speciale: poni la tua domanda e le citazioni compaiono nei blocchi di testo che attingono ai tuoi contenuti.
### Schema dei risultati di ricerca
I risultati di ricerca usano la seguente struttura:
```json
{
"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
}
}
```
### Campi obbligatori
| Campo | Tipo | Descrizione |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Deve essere `"search_result"` |
| `source` | string | La fonte del contenuto. Qualsiasi stringa stabile funziona: un URL o un identificatore interno come `kb://article-1234` |
| `title` | string | Un titolo descrittivo per il risultato di ricerca |
| `content` | array | Un array di blocchi di testo contenenti il contenuto effettivo |
### Campi opzionali
| Campo | Tipo | Descrizione |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `citations` | object | Configurazione delle citazioni con il campo booleano `enabled`. Le citazioni sono disabilitate per impostazione predefinita; ogni esempio in questa pagina imposta esplicitamente `"enabled": true`. Tutti i risultati di ricerca in una richiesta devono usare la stessa impostazione (vedi [Controllo delle citazioni](https://platform.claude.com/docs/it/build-with-claude/search-results#citation-control)) |
| `cache_control` | object | Impostazioni di controllo della cache (ad esempio, `{"type": "ephemeral"}`) |
Ogni elemento nell'array `content` deve essere un blocco di testo con:
* `type`: Deve essere `"text"`
* `text`: Il contenuto testuale effettivo (stringa non vuota)
I risultati di ricerca contengono solo testo. Immagini e altri media non sono supportati all'interno dell'array `content`.
## Metodo 1: Risultati di ricerca dalle chiamate agli strumenti
Restituire risultati di ricerca dai tuoi strumenti personalizzati abilita applicazioni RAG dinamiche: gli strumenti recuperano i contenuti in fase di esecuzione e Claude li cita nella risposta. L'esempio seguente forza la chiamata allo strumento con [`tool_choice`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools#forcing-tool-use), in modo che la fase di recupero venga eseguita ogni volta.
### Esempio: Strumento per base di conoscenza
Il flusso di chiamata agli strumenti richiede una logica di ricerca nella tua applicazione, che necessita di più di un singolo comando shell. Usa il Claude SDK per il flusso completo. Per la struttura della richiesta grezza di una conversazione con strumenti e risultati di ricerca, vedi [Combinare entrambi i metodi](https://platform.claude.com/docs/it/build-with-claude/search-results#combining-both-methods). Per i risultati di ricerca come contenuto di primo livello, vedi [Metodo 2](https://platform.claude.com/docs/it/build-with-claude/search-results#method-2-search-results-as-top-level-content).
Il flusso di chiamata agli strumenti richiede una logica di ricerca nella tua applicazione, che necessita di più di un singolo comando shell. Usa il Claude SDK per il flusso completo. Per la struttura della richiesta grezza di una conversazione con strumenti e risultati di ricerca, vedi [Combinare entrambi i metodi](https://platform.claude.com/docs/it/build-with-claude/search-results#combining-both-methods). Per i risultati di ricerca come contenuto di primo livello, vedi [Metodo 2](https://platform.claude.com/docs/it/build-with-claude/search-results#method-2-search-results-as-top-level-content).
```python Python
from anthropic.types import (
MessageParam,
TextBlockParam,
SearchResultBlockParam,
ToolResultBlockParam,
)
client = Anthropic()
# Definisci uno strumento di ricerca nella knowledge base
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"],
},
}
# Funzione per gestire la chiamata allo strumento
def search_knowledge_base(query):
# Inserisci qui la tua logica di ricerca
# Restituisce i risultati di ricerca nel formato corretto
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},
),
]
# Costruisci la conversazione in una lista, partendo dalla domanda dell'utente
messages = [
MessageParam(role="user", content="How do I configure the timeout settings?")
]
# Crea un messaggio con lo strumento
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 chiama lo strumento, fornisci i risultati di ricerca.
# Il blocco tool_use non è sempre il primo: itera per trovarlo.
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"])
# Aggiungi il turno di Claude, poi il risultato dello strumento, alla conversazione in corso
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
)
],
)
)
# Invia il risultato dello strumento
final_response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
)
print(final_response)
```
```typescript TypeScript
const client = new Anthropic();
// Definisci uno strumento di ricerca nella knowledge base
const knowledgeBaseTool: Anthropic.Tool = {
name: "search_knowledge_base",
description: "Search the company knowledge base for information",
input_schema: {
type: "object" as const,
properties: {
query: {
type: "string",
description: "The search query"
}
},
required: ["query"]
}
};
// Funzione per gestire la chiamata allo strumento
function searchKnowledgeBase(query: string) {
// Inserisci qui la tua logica di ricerca
// Restituisce i risultati di ricerca nel formato corretto
return [
{
type: "search_result" as const,
source: "https://docs.company.com/product-guide",
title: "Product Configuration Guide",
content: [
{
type: "text" as const,
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 }
},
{
type: "search_result" as const,
source: "https://docs.company.com/troubleshooting",
title: "Troubleshooting Guide",
content: [
{
type: "text" as const,
text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."
}
],
citations: { enabled: true }
}
];
}
// Costruisci la conversazione in una lista, partendo dalla domanda dell'utente
const messages: Anthropic.MessageParam[] = [
{ role: "user", content: "How do I configure the timeout settings?" }
];
// Crea un messaggio con lo strumento
const response = await client.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
tools: [knowledgeBaseTool],
tool_choice: { type: "tool", name: "search_knowledge_base" },
messages
});
// Gestisci l'uso degli strumenti e fornisci i risultati.
// Il blocco tool_use non è sempre il primo: cercalo nell'array content.
const toolUse = response.content.find(
(block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
);
if (toolUse) {
const input = toolUse.input as { query: string };
const toolResult = searchKnowledgeBase(input.query);
// Aggiungi il turno di Claude, poi il risultato dello strumento, alla conversazione in corso
messages.push({ role: "assistant", content: response.content });
messages.push({
role: "user",
content: [
{
type: "tool_result" as const,
tool_use_id: toolUse.id,
content: toolResult // Search results go here
}
]
});
// Invia il risultato dello strumento
const finalResponse = await client.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
messages
});
console.log(finalResponse);
}
```
```csharp C#
AnthropicClient client = new();
var tools = new List
{
new ToolUnion(new Tool()
{
Name = "search_knowledge_base",
Description = "Search the company knowledge base for information",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The search query" }),
},
Required = ["query"],
},
}),
};
// Funzione per gestire la chiamata allo strumento
static List SearchKnowledgeBase(string query)
{
// Inserisci qui la tua logica di ricerca
// Restituisce i risultati di ricerca nel formato corretto
return
[
new SearchResultBlockParam
{
Source = "https://docs.company.com/product-guide",
Title = "Product Configuration Guide",
Content = [new() { 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 = new() { Enabled = true },
},
new SearchResultBlockParam
{
Source = "https://docs.company.com/troubleshooting",
Title = "Troubleshooting Guide",
Content = [new() { Text = "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values." }],
Citations = new() { Enabled = true },
},
];
}
// Costruisci la conversazione in una lista, partendo dalla domanda dell'utente
List messages = [new() { Role = Role.User, Content = "How do I configure the timeout settings?" }];
// Crea un messaggio con lo strumento
var response = await client.Messages.Create(new()
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = tools,
ToolChoice = new ToolChoiceTool { Name = "search_knowledge_base" },
Messages = messages,
});
// Quando Claude chiama lo strumento, fornisci i risultati di ricerca.
// Il blocco tool_use non è sempre il primo: trova il primo presente.
foreach (var block in response.Content)
{
if (block.TryPickToolUse(out var toolUse))
{
var query = toolUse.Input["query"].GetString() ?? "";
var toolResults = SearchKnowledgeBase(query);
// Aggiungi il turno di Claude, poi il risultato dello strumento, alla conversazione in corso
messages.Add(new() { Role = Role.Assistant, Content = response.Content.Select(contentBlock => new ContentBlockParam(contentBlock.Json)).ToList() });
messages.Add(new()
{
Role = Role.User,
Content = new MessageParamContent(
[new ContentBlockParam(new ToolResultBlockParam() { ToolUseID = toolUse.ID, Content = new ToolResultBlockParamContent(toolResults) })]
),
});
// Invia il risultato dello strumento
var finalResponse = await client.Messages.Create(new()
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Messages = messages,
});
Console.WriteLine(finalResponse);
break;
}
}
```
```go Go
client := anthropic.NewClient()
knowledgeBaseTool := anthropic.ToolUnionParam{
OfTool: &anthropic.ToolParam{
Name: "search_knowledge_base",
Description: anthropic.String("Search the company knowledge base for information"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{
"type": "string",
"description": "The search query",
},
},
Required: []string{"query"},
},
},
}
// Costruisci la conversazione in una slice, partendo dalla domanda dell'utente
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("How do I configure the timeout settings?")),
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{knowledgeBaseTool},
ToolChoice: anthropic.ToolChoiceUnionParam{OfTool: &anthropic.ToolChoiceToolParam{Name: "search_knowledge_base"}},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
// Il blocco tool_use non è sempre il primo: trovalo nell'elenco dei contenuti
var toolUse *anthropic.ToolUseBlock
for _, block := range response.Content {
if variant, ok := block.AsAny().(anthropic.ToolUseBlock); ok {
toolUse = &variant
break
}
}
if toolUse != nil {
var input struct {
Query string `json:"query"`
}
if err := json.Unmarshal(toolUse.Input, &input); err != nil {
log.Fatal(err)
}
toolResults := searchKnowledgeBase(input.Query)
// Aggiungi il turno di Claude, poi il risultato dello strumento, alla conversazione in corso
messages = append(messages, response.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{
OfToolResult: &anthropic.ToolResultBlockParam{
ToolUseID: toolUse.ID,
Content: toolResults,
},
}))
// Invia il risultato dello strumento
finalResponse, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(finalResponse)
}
// ...
func searchKnowledgeBase(query string) []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{
{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{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."},
},
Source: "https://docs.company.com/product-guide",
Title: "Product Configuration Guide",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{Text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."},
},
Source: "https://docs.company.com/troubleshooting",
Title: "Troubleshooting Guide",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
}
}
```
```java Java
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.CitationsConfigParam;
// ...
import com.anthropic.models.messages.MessageParam;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.SearchResultBlockParam;
import com.anthropic.models.messages.TextBlockParam;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.ToolChoice;
import com.anthropic.models.messages.ToolChoiceTool;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.core.JsonValue;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool knowledgeBaseTool = Tool.builder()
.name("search_knowledge_base")
.description("Search the company knowledge base for information")
.inputSchema(Tool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"query", Map.of(
"type", "string",
"description", "The search query"
)
)))
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build())
.build();
// Costruisci la conversazione in una lista, partendo dalla domanda dell'utente
List messages = new ArrayList<>();
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content("How do I configure the timeout settings?")
.build());
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.addTool(knowledgeBaseTool)
.toolChoice(ToolChoice.ofTool(ToolChoiceTool.builder()
.name("search_knowledge_base")
.build()))
.messages(messages)
.build();
Message response = client.messages().create(params);
// Il blocco tool_use non è sempre il primo: trovalo nella lista dei contenuti
response.content().stream()
.flatMap(contentBlock -> contentBlock.toolUse().stream())
.findFirst()
.ifPresent(toolUse -> {
Map input =
(Map) toolUse._input().asObject().get();
List toolResult = searchKnowledgeBase(
input.get("query").asStringOrThrow()
);
// Aggiungi l'intero turno di Claude alla conversazione in corso, poi il risultato dello strumento.
// Ricostruire solo il blocco tool_use scarterebbe gli altri blocchi di contenuto che Claude
// ha restituito (es. testo iniziale quando la chiamata allo strumento non è forzata) — aggiungi il
// turno completo, come fanno le schede degli altri linguaggi.
messages.add(MessageParam.builder()
.role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(
response.content().stream()
.map(block -> block.toParam())
.toList()
)
.build());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.contentOfBlocks(toolResult)
.build()
)
))
.build());
// Invia il risultato dello strumento
MessageCreateParams finalParams = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.messages(messages)
.build();
Message finalResponse = client.messages().create(finalParams);
System.out.println(finalResponse);
});
}
static List searchKnowledgeBase(String query) {
return List.of(
ToolResultBlockParam.Content.Block.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/product-guide")
.title("Product Configuration Guide")
.content(List.of(
TextBlockParam.builder()
.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.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
),
ToolResultBlockParam.Content.Block.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/troubleshooting")
.title("Troubleshooting Guide")
.content(List.of(
TextBlockParam.builder()
.text("If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
)
);
}
```
```php PHP
$client = new Client();
$knowledgeBaseTool = [
'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']
]
];
function searchKnowledgeBase($query) {
return [
[
'type' => 'search_result',
'source' => 'https://docs.company.com/product-guide',
'title' => 'Product Configuration Guide',
'content' => [
[
'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]
],
[
'type' => 'search_result',
'source' => 'https://docs.company.com/troubleshooting',
'title' => 'Troubleshooting Guide',
'content' => [
[
'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]
]
];
}
// Costruisci la conversazione in una lista, partendo dalla domanda dell'utente
$messages = [
['role' => 'user', 'content' => 'How do I configure the timeout settings?']
];
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5',
toolChoice: ['type' => 'tool', 'name' => 'search_knowledge_base'],
tools: [$knowledgeBaseTool],
);
$toolUseBlock = null;
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
$toolUseBlock = $block;
break;
}
}
if ($toolUseBlock !== null) {
$toolResult = searchKnowledgeBase($toolUseBlock->input['query']);
// Aggiungi il turno di Claude, poi il risultato dello strumento, alla conversazione in corso
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = [
'role' => 'user',
'content' => [
[
'type' => 'tool_result',
'tool_use_id' => $toolUseBlock->id,
'content' => $toolResult
]
]
];
// Invia indietro il risultato dello strumento
$finalResponse = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5',
);
echo $finalResponse;
} else {
echo $response;
}
```
```ruby Ruby
client = Anthropic::Client.new
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"]
}
}
def search_knowledge_base(query)
[
{
type: "search_result",
source: "https://docs.company.com/product-guide",
title: "Product Configuration Guide",
content: [
{
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 }
},
{
type: "search_result",
source: "https://docs.company.com/troubleshooting",
title: "Troubleshooting Guide",
content: [
{
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 }
}
]
end
# Costruisci la conversazione in una lista, partendo dalla domanda dell'utente
messages = [
{ role: "user", content: "How do I configure the timeout settings?" }
]
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
)
# Il blocco tool_use non è sempre il primo: trovalo nell'array content
tool_use = response.content.find { |block| block.type == :tool_use }
if tool_use
tool_result = search_knowledge_base(tool_use.input[:query])
# Aggiungi il turno di Claude, poi il risultato dello strumento, alla conversazione in corso
messages << { role: "assistant", content: response.content }
messages << {
role: "user",
content: [
{
type: "tool_result",
tool_use_id: tool_use.id,
content: tool_result
}
]
}
# Invia il risultato dello strumento
final_response = client.messages.create(
model: "claude-opus-5",
max_tokens: 1024,
messages: messages
)
puts final_response
end
```
## Metodo 2: Risultati di ricerca come contenuto di primo livello
Puoi anche fornire i risultati di ricerca direttamente nei messaggi utente. Questo è utile per:
* Contenuti pre-recuperati dalla tua infrastruttura di ricerca
* Risultati di ricerca memorizzati in cache da query precedenti
* Contenuti da servizi di ricerca esterni
* Test e sviluppo
### Esempio: Risultati di ricerca diretti
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "search_result",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"content": [
{
"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
}
},
{
"type": "search_result",
"source": "https://docs.company.com/quickstart",
"title": "Getting Started Guide",
"content": [
{
"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
}
},
{
"type": "text",
"text": "Based on these search results, how do I authenticate API requests and what are the rate limits?"
}
]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
messages:
- role: user
content:
- type: search_result
source: https://docs.company.com/api-reference
title: API Reference - Authentication
content:
- 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
- type: search_result
source: https://docs.company.com/quickstart
title: Getting Started Guide
content:
- 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
- type: text
text: >-
Based on these search results, how do I authenticate API requests
and what are the rate limits?
YAML
```
```python Python
from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Fornisci i risultati di ricerca direttamente nel messaggio dell'utente
response = client.messages.create(
model="claude-opus-5-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)
```
```typescript TypeScript
const client = new Anthropic();
// Fornisci i risultati di ricerca direttamente nel messaggio dell'utente
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "search_result" as const,
source: "https://docs.company.com/api-reference",
title: "API Reference - Authentication",
content: [
{
type: "text" as const,
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 }
},
{
type: "search_result" as const,
source: "https://docs.company.com/quickstart",
title: "Getting Started Guide",
content: [
{
type: "text" as const,
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 }
},
{
type: "text" as const,
text: "Based on these search results, how do I authenticate API requests and what are the rate limits?"
}
]
}
]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
// Fornisci i risultati di ricerca direttamente nel messaggio dell'utente
var response = await client.Messages.Create(new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(
[
new ContentBlockParam(new SearchResultBlockParam
{
Source = "https://docs.company.com/api-reference",
Title = "API Reference - Authentication",
Content = [new() { 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 = new() { Enabled = true },
}),
new ContentBlockParam(new SearchResultBlockParam
{
Source = "https://docs.company.com/quickstart",
Title = "Getting Started Guide",
Content = [new() { 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 = new() { Enabled = true },
}),
new ContentBlockParam(new TextBlockParam { Text = "Based on these search results, how do I authenticate API requests and what are the rate limits?" }),
]),
},
],
});
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{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",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
anthropic.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{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",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
anthropic.NewTextBlock("Based on these search results, how do I authenticate API requests and what are the rate limits?"),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.CitationsConfigParam;
// ...
import com.anthropic.models.messages.SearchResultBlockParam;
import com.anthropic.models.messages.TextBlockParam;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/api-reference")
.title("API Reference - Authentication")
.content(List.of(
TextBlockParam.builder()
.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.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
),
ContentBlockParam.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/quickstart")
.title("Getting Started Guide")
.content(List.of(
TextBlockParam.builder()
.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.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Based on these search results, how do I authenticate API requests and what are the rate limits?")
.build()
)
))
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'search_result',
'source' => 'https://docs.company.com/api-reference',
'title' => 'API Reference - Authentication',
'content' => [
[
'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]
],
[
'type' => 'search_result',
'source' => 'https://docs.company.com/quickstart',
'title' => 'Getting Started Guide',
'content' => [
[
'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]
],
[
'type' => 'text',
'text' => 'Based on these search results, how do I authenticate API requests and what are the rate limits?'
]
]
]
],
model: 'claude-opus-5-5',
);
echo json_encode($message, JSON_PRETTY_PRINT);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "search_result",
source: "https://docs.company.com/api-reference",
title: "API Reference - Authentication",
content: [
{
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 }
},
{
type: "search_result",
source: "https://docs.company.com/quickstart",
title: "Getting Started Guide",
content: [
{
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 }
},
{
type: "text",
text: "Based on these search results, how do I authenticate API requests and what are the rate limits?"
}
]
}
]
)
puts message
```
## La risposta di Claude con citazioni
Indipendentemente da come vengono forniti i risultati di ricerca, Claude include automaticamente le citazioni quando usa informazioni provenienti da essi:
```json
{
"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
}
]
}
]
}
```
### Campi delle citazioni
Ogni citazione include:
| Campo | Tipo | Descrizione |
| --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Sempre `"search_result_location"` per le citazioni dei risultati di ricerca |
| `source` | string | La fonte del risultato di ricerca originale |
| `title` | string o null | Il titolo del risultato di ricerca originale |
| `cited_text` | string | Il testo completo del blocco o dei blocchi citati, concatenato. Equivale al contenuto di `content[start_block_index:end_block_index]` unito insieme. Non conteggiato nei token di output. |
| `search_result_index` | integer | Indice a base 0 del risultato di ricerca citato tra tutti i blocchi `search_result` nella richiesta, nell'ordine in cui compaiono (attraverso tutti i messaggi e i risultati degli strumenti). |
| `start_block_index` | integer | Indice a base 0 del primo blocco citato nell'array `content` del risultato di ricerca. |
| `end_block_index` | integer | Indice finale esclusivo dell'intervallo di blocchi citati nell'array `content` del risultato di ricerca. Sempre maggiore di `start_block_index`. |
Gli indici dei blocchi identificano una porzione dell'array `content` del risultato di ricerca, e `cited_text` è il testo completo di quella porzione. Il blocco di testo è l'unità minima citabile: Claude cita blocchi interi, non sottostringhe all'interno di un blocco. Per ottenere citazioni più granulari, suddividi il contenuto dei tuoi risultati di ricerca in blocchi più piccoli (vedi [Blocchi di contenuto multipli](https://platform.claude.com/docs/it/build-with-claude/search-results#multiple-content-blocks)).
## Blocchi di contenuto multipli
I risultati di ricerca possono contenere più blocchi di testo nell'array `content`:
```json
{
"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 }
}
```
Una citazione che fa riferimento al blocco sui limiti di velocità appare così:
```json
{
"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 questo risultato di ricerca viene citato, `start_block_index` e `end_block_index` identificano quali di questi blocchi copre la citazione, e `cited_text` contiene esattamente il testo di quei blocchi. Suddividere il contenuto in blocchi più piccoli e mirati offre a Claude confini di citazione più precisi; combinare il contenuto in un unico blocco significa che ogni citazione restituisce il testo completo. Questo è lo stesso modello usato dai [documenti con contenuto personalizzato](https://platform.claude.com/docs/it/build-with-claude/citations#custom-content-documents) nella funzionalità Citazioni.
## Uso avanzato
### Combinare entrambi i metodi
Puoi combinare entrambi i metodi nella stessa conversazione. Claude cita da entrambe le fonti, e `search_result_index` conta tutti i blocchi `search_result` nell'ordine della richiesta, indipendentemente dalla fonte.
L'esempio seguente riproduce una conversazione completa. Il primo messaggio utente contiene un risultato di ricerca pre-recuperato, il turno dell'assistente chiama uno strumento per base di conoscenza e il risultato dello strumento restituisce un secondo risultato di ricerca. La risposta di Claude cita entrambe le fonti:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [
{
"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"]
}
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "search_result",
"source": "https://docs.company.com/overview",
"title": "Product Overview",
"content": [
{
"type": "text",
"text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards."
}
],
"citations": {"enabled": true}
},
{
"type": "text",
"text": "What does Acme Dashboard do, and what plans is it available on?"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "Let me check the pricing information."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "search_knowledge_base",
"input": {"query": "Acme Dashboard pricing plans"}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{
"type": "search_result",
"source": "https://docs.company.com/pricing",
"title": "Pricing Plans",
"content": [
{
"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}
}
]
}
]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
tools:
- 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]
messages:
- role: user
content:
- type: search_result
source: https://docs.company.com/overview
title: Product Overview
content:
- type: text
text: >-
Acme Dashboard is a monitoring tool for distributed systems.
It supports real-time alerting and custom metric dashboards.
citations:
enabled: true
- type: text
text: What does Acme Dashboard do, and what plans is it available on?
- role: assistant
content:
- type: text
text: Let me check the pricing information.
- type: tool_use
id: toolu_01A09q90qw90lq917835lq9
name: search_knowledge_base
input:
query: Acme Dashboard pricing plans
- role: user
content:
- type: tool_result
tool_use_id: toolu_01A09q90qw90lq917835lq9
content:
- type: search_result
source: https://docs.company.com/pricing
title: Pricing Plans
content:
- 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
YAML
```
```python Python
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"],
},
}
# Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
# messaggio utente contiene un risultato già recuperato, il risultato dello strumento ne restituisce un altro
response = client.messages.create(
model="claude-opus-5-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)
```
```typescript TypeScript
const client = new Anthropic();
const knowledgeBaseTool: Anthropic.Tool = {
name: "search_knowledge_base",
description: "Search the company knowledge base for information",
input_schema: {
type: "object" as const,
properties: {
query: { type: "string", description: "The search query" }
},
required: ["query"]
}
};
// Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
// messaggio utente contiene un risultato già recuperato, il risultato dello strumento ne restituisce un altro
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [knowledgeBaseTool],
messages: [
{
role: "user",
content: [
{
type: "search_result" as const,
source: "https://docs.company.com/overview",
title: "Product Overview",
content: [
{
type: "text" as const,
text: "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards."
}
],
citations: { enabled: true }
},
{
type: "text" as const,
text: "What does Acme Dashboard do, and what plans is it available on?"
}
]
},
{
role: "assistant",
content: [
{ type: "text" as const, text: "Let me check the pricing information." },
{
type: "tool_use" as const,
id: "toolu_01A09q90qw90lq917835lq9",
name: "search_knowledge_base",
input: { query: "Acme Dashboard pricing plans" }
}
]
},
{
role: "user",
content: [
{
type: "tool_result" as const,
tool_use_id: "toolu_01A09q90qw90lq917835lq9",
content: [
{
type: "search_result" as const,
source: "https://docs.company.com/pricing",
title: "Pricing Plans",
content: [
{
type: "text" as const,
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 }
}
]
}
]
}
]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
// Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
// messaggio utente contiene un risultato già recuperato, il risultato dello strumento ne restituisce un altro
var response = await client.Messages.Create(new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ToolUnion(new Tool()
{
Name = "search_knowledge_base",
Description = "Search the company knowledge base for information",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The search query" }),
},
Required = ["query"],
},
}),
],
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(
[
new ContentBlockParam(new SearchResultBlockParam
{
Source = "https://docs.company.com/overview",
Title = "Product Overview",
Content = [new() { Text = "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards." }],
Citations = new() { Enabled = true },
}),
new ContentBlockParam(new TextBlockParam { Text = "What does Acme Dashboard do, and what plans is it available on?" }),
]),
},
new()
{
Role = Role.Assistant,
Content = new MessageParamContent(
[
new ContentBlockParam(new TextBlockParam { Text = "Let me check the pricing information." }),
new ContentBlockParam(new ToolUseBlockParam
{
ID = "toolu_01A09q90qw90lq917835lq9",
Name = "search_knowledge_base",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Acme Dashboard pricing plans"),
},
}),
]),
},
new()
{
Role = Role.User,
Content = new MessageParamContent(
[
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = "toolu_01A09q90qw90lq917835lq9",
Content = new ToolResultBlockParamContent(
[
new SearchResultBlockParam
{
Source = "https://docs.company.com/pricing",
Title = "Pricing Plans",
Content = [new() { Text = "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing." }],
Citations = new() { Enabled = true },
},
]),
}),
]),
},
],
});
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
knowledgeBaseTool := anthropic.ToolUnionParam{
OfTool: &anthropic.ToolParam{
Name: "search_knowledge_base",
Description: anthropic.String("Search the company knowledge base for information"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{"type": "string", "description": "The search query"},
},
Required: []string{"query"},
},
},
}
// Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
// messaggio utente contiene un risultato già recuperato, il risultato dello strumento ne restituisce un altro
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{knowledgeBaseTool},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{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",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
anthropic.NewTextBlock("What does Acme Dashboard do, and what plans is it available on?"),
),
anthropic.NewAssistantMessage(
anthropic.NewTextBlock("Let me check the pricing information."),
anthropic.ContentBlockParamUnion{OfToolUse: &anthropic.ToolUseBlockParam{
ID: "toolu_01A09q90qw90lq917835lq9",
Name: "search_knowledge_base",
Input: map[string]any{"query": "Acme Dashboard pricing plans"},
}},
),
anthropic.NewUserMessage(
anthropic.ContentBlockParamUnion{OfToolResult: &anthropic.ToolResultBlockParam{
ToolUseID: "toolu_01A09q90qw90lq917835lq9",
Content: []anthropic.ToolResultBlockParamContentUnion{
{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{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",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
},
}},
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.CitationsConfigParam;
import com.anthropic.models.messages.ContentBlockParam;
// ...
import com.anthropic.models.messages.SearchResultBlockParam;
import com.anthropic.models.messages.TextBlockParam;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlockParam;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool knowledgeBaseTool = Tool.builder()
.name("search_knowledge_base")
.description("Search the company knowledge base for information")
.inputSchema(Tool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"query", Map.of("type", "string", "description", "The search query")
)))
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build())
.build();
// Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
// messaggio utente contiene un risultato già recuperato, il risultato dello strumento ne restituisce un altro
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(knowledgeBaseTool)
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofSearchResult(SearchResultBlockParam.builder()
.source("https://docs.company.com/overview")
.title("Product Overview")
.content(List.of(TextBlockParam.builder()
.text("Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.")
.build()))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("What does Acme Dashboard do, and what plans is it available on?")
.build())
))
.addAssistantMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Let me check the pricing information.")
.build()),
ContentBlockParam.ofToolUse(ToolUseBlockParam.builder()
.id("toolu_01A09q90qw90lq917835lq9")
.name("search_knowledge_base")
.input(JsonValue.from(Map.of("query", "Acme Dashboard pricing plans")))
.build())
))
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofToolResult(ToolResultBlockParam.builder()
.toolUseId("toolu_01A09q90qw90lq917835lq9")
.contentOfBlocks(List.of(
ToolResultBlockParam.Content.Block.ofSearchResult(SearchResultBlockParam.builder()
.source("https://docs.company.com/pricing")
.title("Pricing Plans")
.content(List.of(TextBlockParam.builder()
.text("Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.")
.build()))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build())
))
.build())
))
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
$knowledgeBaseTool = [
'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']
]
];
// Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
// messaggio utente contiene un risultato già recuperato, il risultato dello strumento ne restituisce un altro
$response = $client->messages->create(
maxTokens: 1024,
tools: [$knowledgeBaseTool],
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'search_result',
'source' => 'https://docs.company.com/overview',
'title' => 'Product Overview',
'content' => [
[
'type' => 'text',
'text' => 'Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.'
]
],
'citations' => ['enabled' => true]
],
[
'type' => 'text',
'text' => 'What does Acme Dashboard do, and what plans is it available on?'
]
]
],
[
'role' => 'assistant',
'content' => [
['type' => 'text', 'text' => 'Let me check the pricing information.'],
[
'type' => 'tool_use',
'id' => 'toolu_01A09q90qw90lq917835lq9',
'name' => 'search_knowledge_base',
'input' => ['query' => 'Acme Dashboard pricing plans']
]
]
],
[
'role' => 'user',
'content' => [
[
'type' => 'tool_result',
'tool_use_id' => 'toolu_01A09q90qw90lq917835lq9',
'content' => [
[
'type' => 'search_result',
'source' => 'https://docs.company.com/pricing',
'title' => 'Pricing Plans',
'content' => [
[
'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]
]
]
]
]
]
],
model: 'claude-opus-5-5',
);
echo json_encode($response, JSON_PRETTY_PRINT);
```
```ruby Ruby
client = Anthropic::Client.new
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"]
}
}
# Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
# messaggio utente contiene un risultato già recuperato, il risultato dello strumento ne restituisce un altro
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [knowledge_base_tool],
messages: [
{
role: "user",
content: [
{
type: "search_result",
source: "https://docs.company.com/overview",
title: "Product Overview",
content: [
{
type: "text",
text: "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards."
}
],
citations: { enabled: true }
},
{
type: "text",
text: "What does Acme Dashboard do, and what plans is it available on?"
}
]
},
{
role: "assistant",
content: [
{ type: "text", text: "Let me check the pricing information." },
{
type: "tool_use",
id: "toolu_01A09q90qw90lq917835lq9",
name: "search_knowledge_base",
input: { query: "Acme Dashboard pricing plans" }
}
]
},
{
role: "user",
content: [
{
type: "tool_result",
tool_use_id: "toolu_01A09q90qw90lq917835lq9",
content: [
{
type: "search_result",
source: "https://docs.company.com/pricing",
title: "Pricing Plans",
content: [
{
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 }
}
]
}
]
}
]
)
puts response
```
La risposta cita entrambe le fonti. Il risultato pre-recuperato è `search_result_index: 0` e il risultato restituito dallo strumento è `search_result_index: 1`, in corrispondenza dell'ordine in cui i blocchi `search_result` compaiono nella conversazione:
```json
{
"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
}
]
}
]
}
```
### Combinazione con altri tipi di contenuto
Nei messaggi utente, i blocchi `search_result` possono trovarsi accanto a qualsiasi altro blocco di contenuto. L'esempio del Metodo 2 abbina i risultati di ricerca a una domanda `text`, e blocchi immagine o documento possono unirsi a essi nello stesso modo.
I risultati degli strumenti sono più restrittivi: se un qualsiasi blocco nell'array di contenuto di un `tool_result` è un `search_result`, tutti i suoi blocchi devono essere `search_result`. Combinare risultati di ricerca con altri tipi di blocco nello stesso risultato dello strumento restituisce un errore di validazione. Per restituire testo di supporto insieme ai risultati di ricerca provenienti dagli strumenti, includilo come blocco di testo all'interno di uno degli array `content` dei risultati di ricerca, dove diventa anch'esso citabile.
### Controllo della cache
Aggiungi `cache_control` al blocco del risultato di ricerca per memorizzarlo in cache e riutilizzarlo tra le richieste. Si trova accanto a `citations` sullo stesso blocco:
```json
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "..." }],
"citations": { "enabled": true },
"cache_control": { "type": "ephemeral" }
}
```
Consulta [Cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) per le lunghezze minime memorizzabili in cache e altri requisiti.
### Controllo delle citazioni
Per impostazione predefinita, le citazioni sono disabilitate per i risultati di ricerca. Puoi abilitare le citazioni impostando esplicitamente la configurazione `citations`:
```json
{
"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` è impostato su `true`, Claude allega riferimenti di citazione ai blocchi di testo che attingono al risultato di ricerca.
Le citazioni sono tutto-o-niente: o tutti i risultati di ricerca in una richiesta devono avere le citazioni abilitate, oppure tutti devono averle disabilitate. Combinare risultati di ricerca con impostazioni di citazione diverse produce un errore.
## Best practice
### Per la ricerca basata su strumenti (Metodo 1)
* **Contenuto dinamico:** Usala per ricerche in tempo reale e applicazioni RAG dinamiche
* **Gestione degli errori:** Restituisci messaggi appropriati quando le ricerche falliscono
* **Limiti dei risultati:** Restituisci solo i risultati più rilevanti per evitare l'overflow del contesto
### Per la ricerca di primo livello (Metodo 2)
* **Contenuto pre-recuperato:** Usala quando disponi già dei risultati di ricerca
* **Elaborazione in batch:** Ideale per elaborare più risultati di ricerca contemporaneamente
* **Test:** Ottima per testare il comportamento delle citazioni con contenuti noti
### Best practice generali
1. **Struttura i risultati in modo efficace:**
* Usa URL di origine chiari e permanenti
* Fornisci titoli descrittivi
* Suddividi i contenuti lunghi in blocchi di testo logici per offrire a Claude confini di citazione più precisi
2. **Mantieni la coerenza:**
* Usa formati di origine coerenti in tutta la tua applicazione
* Assicurati che i titoli riflettano accuratamente il contenuto
* Mantieni la formattazione coerente
3. **Gestisci gli errori con eleganza:** quando una ricerca fallisce o non restituisce nulla, restituisci un semplice blocco di testo che descrive l'esito (ad esempio, `{"type": "text", "text": "No results found."}`) invece di sollevare un errore: Claude spiega il risultato vuoto all'utente e la conversazione continua.
## Limitazioni
* I blocchi di contenuto dei risultati di ricerca sono disponibili su Claude API, Amazon Bedrock e Google Cloud.
* All'interno dei risultati di ricerca è supportato solo contenuto testuale (niente immagini o altri media).
* I blocchi `search_result` possono comparire solo nei messaggi utente (inclusi quelli all'interno dei risultati degli strumenti). I messaggi dell'assistente con risultati di ricerca vengono rifiutati.
* Quando lo [strumento di ricerca web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool) è abilitato nella stessa richiesta, le citazioni devono essere abilitate su tutti i blocchi `search_result`.
## Prossimi passi
Rileva e gestisci i motivi di arresto per rifiuto nelle risposte in streaming, e riprova le richieste rifiutate su un modello di fallback.
Fonda le risposte di Claude sui tuoi documenti di origine. Le citazioni restituiscono i passaggi esatti che supportano ogni affermazione, così puoi verificare le risposte e mostrare le fonti ai tuoi utenti.
Dai a Claude accesso a contenuti web aggiornati con fonti citate, filtraggio dinamico opzionale e controlli sui domini.
Consulta la documentazione completa della Messages API, inclusi i tipi di blocchi di contenuto.
Memorizza in cache i risultati di ricerca con `cache_control` per ridurre costi e latenza nelle richieste ripetute.