Suchergebnisse
Erhalte natürliche Zitate für RAG-Anwendungen, indem du Suchergebnisse mit Quellenangabe bereitstellst
Nutzung unterscheidet sich je nach Produkt
search_result-Blöcke in einem Tool-Ergebnis oder direkt in einer Benutzernachricht.user.custom_tool_result, nicht in Events user.message.„Search result content blocks“ (Suchergebnis-Inhaltsblöcke) ermöglichen es Claude, deine eigenen Inhalte genauso zu zitieren wie Websuchergebnisse: Jedes Zitat enthält die Quelle und den Titel, die du angegeben hast. Verwende sie in Anwendungen mit „Retrieval-Augmented Generation“ (abrufgestützter Generierung), oder RAG, bei denen Claude Antworten deinen Dokumenten zuordnen muss.
Funktionsweise
Suchergebnisse können auf zwei Arten bereitgestellt werden:
- Aus Tool-Aufrufen: Deine benutzerdefinierten Tools geben Suchergebnisse zurück, wodurch du dynamische RAG-Anwendungen erstellen kannst.
- Als Inhalt auf oberster Ebene: Du stellst Suchergebnisse direkt in Benutzernachrichten für vorab abgerufene oder zwischengespeicherte Inhalte bereit.
In beiden Fällen zitiert Claude die Suchergebnisse automatisch, wenn Zitate aktiviert sind. Es ist kein spezielles Prompting erforderlich: Stelle deine Frage, und die Zitate erscheinen an den Textblöcken, die sich auf deine Inhalte stützen. Wenn dein Prompt jedoch ausschließlich JSON anfordert, enthält die Antwort möglicherweise nur wenige oder gar keine Zitate. Um strukturierte Daten mit einem Zitat für jeden Wert zu extrahieren, siehe Strukturierte Daten mit Citations erhalten.
Schema für Suchergebnisse
Suchergebnisse verwenden die folgende Struktur:
{
"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
}
}Pflichtfelder
| Feld | Typ | Beschreibung |
|---|---|---|
type | string | Muss "search_result" sein |
source | string | Die Quelle des Inhalts. Jeder stabile String funktioniert: eine URL oder eine interne Kennung wie kb://article-1234 |
title | string | Ein aussagekräftiger Titel für das Suchergebnis |
content | array | Ein Array von Textblöcken, die den eigentlichen Inhalt enthalten |
Optionale Felder
| Feld | Typ | Beschreibung |
|---|---|---|
citations | object | Zitatkonfiguration mit dem booleschen Feld enabled. Zitate sind standardmäßig deaktiviert; jedes Beispiel auf dieser Seite setzt "enabled": true explizit. Alle Suchergebnisse in einer Anfrage müssen dieselbe Einstellung verwenden (siehe Zitatsteuerung) |
cache_control | object | Cache-Steuerungseinstellungen (zum Beispiel {"type": "ephemeral"}) |
Jedes Element im content-Array muss ein Textblock sein mit:
type: Muss"text"seintext: Der eigentliche Textinhalt (nicht leerer String)
Suchergebnisse enthalten nur Text. Bilder und andere Medien werden im content-Array nicht unterstützt.
Methode 1: Suchergebnisse aus Tool-Aufrufen
Wenn du Suchergebnisse aus deinen benutzerdefinierten Tools zurückgibst, kannst du dynamische RAG-Anwendungen erstellen: Tools rufen Inhalte zur Laufzeit ab, und Claude zitiert sie in der Antwort. Das folgende Beispiel erzwingt den Tool-Aufruf mit tool_choice, sodass der Abrufschritt jedes Mal ausgeführt wird.
Beispiel: Wissensdatenbank-Tool
from anthropic.types import (
MessageParam,
TextBlockParam,
SearchResultBlockParam,
ToolResultBlockParam,
)
client = Anthropic()
# Definiere ein Suchtool für die Wissensdatenbank
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"],
},
}
# Funktion zur Verarbeitung des Tool-Aufrufs
def search_knowledge_base(query):
# Deine Suchlogik hier
# Gibt Suchergebnisse im korrekten Format zurück
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},
),
]
# Baue die Konversation in einer Liste auf, beginnend mit der Frage des Nutzers
messages: list[MessageParam] = [
{"role": "user", "content": "How do I configure the timeout settings?"}
]
# Erstelle eine Nachricht mit dem Tool
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=[knowledge_base_tool],
tool_choice={
"type": "tool",
"name": "search_knowledge_base",
"disable_parallel_tool_use": True,
},
messages=messages,
)
# Wenn Claude das Tool aufruft, stelle die Suchergebnisse bereit.
# Der tool_use-Block ist nicht immer der erste: iteriere, um ihn zu finden.
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"])
# Hänge Claudes Zug und dann das Tool-Ergebnis an die laufende Konversation an
messages.append({"role": "assistant", "content": response.content})
messages.append(
{
"role": "user",
"content": [
ToolResultBlockParam(
type="tool_result",
tool_use_id=tool_use.id,
content=tool_result, # Search results go here
)
],
}
)
# Sende das Tool-Ergebnis zurück
final_response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
)
print(final_response)Methode 2: Suchergebnisse als Inhalt auf oberster Ebene
Du kannst Suchergebnisse auch direkt in Benutzernachrichten bereitstellen. Das ist nützlich für:
- Vorab abgerufene Inhalte aus deiner Suchinfrastruktur
- Zwischengespeicherte Suchergebnisse aus früheren Abfragen
- Inhalte aus externen Suchdiensten
- Tests und Entwicklung
Beispiel: Direkte Suchergebnisse
from anthropic.types import TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Stelle Suchergebnisse direkt in der Nutzernachricht bereit
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"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)Claudes Antwort mit Zitaten
Unabhängig davon, wie Suchergebnisse bereitgestellt werden, fügt Claude automatisch Zitate ein, wenn es Informationen daraus verwendet:
{
"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
}
]
}
]
}Zitatfelder
Jedes Zitat enthält:
| Feld | Typ | Beschreibung |
|---|---|---|
type | string | Bei Suchergebnis-Zitaten immer "search_result_location" |
source | string | Die Quelle aus dem ursprünglichen Suchergebnis |
title | string oder null | Der Titel aus dem ursprünglichen Suchergebnis |
cited_text | string | Der vollständige Text der zitierten Blöcke, verkettet. Entspricht den zusammengefügten Inhalten von content[start_block_index:end_block_index]. Wird nicht auf die Output-Token angerechnet. |
search_result_index | integer | 0-basierter Index des zitierten Suchergebnisses unter allen search_result-Blöcken in der Anfrage, in der Reihenfolge ihres Auftretens (über alle Nachrichten und Tool-Ergebnisse hinweg). |
start_block_index | integer | 0-basierter Index des ersten zitierten Blocks im content-Array des Suchergebnisses. |
end_block_index | integer | Exklusiver Endindex des zitierten Blockbereichs im content-Array des Suchergebnisses. Immer größer als start_block_index. |
Die Blockindizes kennzeichnen einen Ausschnitt des content-Arrays des Suchergebnisses, und cited_text ist der vollständige Text dieses Ausschnitts. Der Textblock ist die kleinste zitierbare Einheit: Claude zitiert ganze Blöcke, keine Teilstrings innerhalb eines Blocks. Um feinere Zitate zu erhalten, teile den Inhalt deiner Suchergebnisse in kleinere Blöcke auf (siehe Mehrere Inhaltsblöcke).
Mehrere Inhaltsblöcke
Suchergebnisse können mehrere Textblöcke im content-Array enthalten:
{
"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 }
}Ein Zitat, das auf den Ratenlimit-Block verweist, sieht so aus:
{
"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
}Wenn dieses Suchergebnis zitiert wird, geben start_block_index und end_block_index an, welche dieser Blöcke das Zitat abdeckt, und cited_text enthält genau den Text dieser Blöcke. Das Aufteilen von Inhalten in kleinere, fokussierte Blöcke gibt Claude feinere Zitatgrenzen; das Zusammenfassen von Inhalten in einem Block bedeutet, dass jedes Zitat den vollständigen Text zurückgibt. Dies ist dasselbe Modell, das von benutzerdefinierten Inhaltsdokumenten in der Citations-Funktion verwendet wird.
Erweiterte Nutzung
Beide Methoden kombinieren
Du kannst beide Methoden in derselben Konversation mischen. Claude zitiert aus beiden Quellen, und search_result_index zählt alle search_result-Blöcke in der Reihenfolge der Anfrage, unabhängig von der Quelle.
Das folgende Beispiel spielt eine vollständige Konversation nach. Die erste Benutzernachricht enthält ein vorab abgerufenes Suchergebnis, der Assistant-Turn ruft ein Wissensdatenbank-Tool auf, und das Tool-Ergebnis gibt ein zweites Suchergebnis zurück. Claudes Antwort zitiert beide Quellen:
from anthropic.types import (
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"],
},
}
# Spiele eine Unterhaltung ab, die Suchergebnisse auf beide Arten liefert: Die erste
# Nutzernachricht enthält ein vorab abgerufenes Ergebnis, und das Tool-Ergebnis liefert ein weiteres
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[knowledge_base_tool],
messages=[
{
"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?",
),
],
},
{
"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"},
),
],
},
{
"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)Die Antwort zitiert beide Quellen. Das vorab abgerufene Ergebnis ist search_result_index: 0 und das vom Tool zurückgegebene Ergebnis ist search_result_index: 1, entsprechend der Reihenfolge, in der die search_result-Blöcke in der Konversation erscheinen:
{
"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
}
]
}
]
}Mischen mit anderen Inhaltstypen
In Benutzernachrichten können search_result-Blöcke neben jedem anderen Inhaltsblock stehen. Das Beispiel zu Methode 2 kombiniert Suchergebnisse mit einer text-Frage, und Bild- oder Dokumentblöcke können auf dieselbe Weise hinzukommen.
Tool-Ergebnisse sind strenger: Wenn ein Block in einem tool_result-Content-Array ein search_result ist, müssen alle seine Blöcke search_result sein. Das Mischen von Suchergebnissen mit anderen Blocktypen im selben Tool-Ergebnis führt zu einem Validierungsfehler. Um ergänzenden Text zusammen mit aus Tools stammenden Suchergebnissen zurückzugeben, füge ihn als Textblock in das content-Array eines der Suchergebnisse ein, wo er ebenfalls zitierbar wird.
Cache-Steuerung
Füge cache_control zum Suchergebnisblock hinzu, um ihn für die Wiederverwendung über Anfragen hinweg zwischenzuspeichern. Es steht neben citations im selben Block:
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "..." }],
"citations": { "enabled": true },
"cache_control": { "type": "ephemeral" }
}Siehe Prompt-Caching für Mindestlängen zum Caching und weitere Anforderungen.
Zitatsteuerung
Standardmäßig sind Zitate für Suchergebnisse deaktiviert. Du kannst Zitate aktivieren, indem du die citations-Konfiguration explizit festlegst:
{
"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
}
}Wenn citations.enabled auf true gesetzt ist, hängt Claude Zitatverweise an die Textblöcke an, die sich auf das Suchergebnis stützen.
Best Practices
Für toolbasierte Suche (Methode 1)
- Dynamische Inhalte: Verwende sie für Echtzeitsuchen und dynamische RAG-Anwendungen
- Fehlerbehandlung: Gib passende Meldungen zurück, wenn Suchen fehlschlagen
- Ergebnislimits: Gib nur die relevantesten Ergebnisse zurück, um einen Kontextüberlauf zu vermeiden
Für Suche auf oberster Ebene (Methode 2)
- Vorab abgerufene Inhalte: Verwende sie, wenn du bereits Suchergebnisse hast
- Stapelverarbeitung: Verwende sie, um mehrere Suchergebnisse auf einmal zu verarbeiten
- Tests: Verwende sie, um das Zitatverhalten mit bekannten Inhalten zu testen
Allgemeine Best Practices
-
Ergebnisse effektiv strukturieren:
- Verwende klare, dauerhafte Quell-URLs
- Gib aussagekräftige Titel an
- Teile lange Inhalte in logische Textblöcke auf, um Claude feinere Zitatgrenzen zu geben
-
Konsistenz wahren:
- Verwende in deiner gesamten Anwendung einheitliche Quellformate
- Stelle sicher, dass Titel den Inhalt genau widerspiegeln
- Halte die Formatierung einheitlich
-
Fehler elegant behandeln: Wenn eine Suche fehlschlägt oder nichts zurückgibt, gib einen einfachen Textblock zurück, der das Ergebnis beschreibt (zum Beispiel
{"type": "text", "text": "No results found."}), anstatt einen Fehler auszulösen: Claude erklärt dem Benutzer das leere Ergebnis, und die Konversation wird fortgesetzt.
Einschränkungen
- Innerhalb von Suchergebnissen werden nur Textinhalte unterstützt (keine Bilder oder anderen Medien).
search_result-Blöcke können nur in Benutzernachrichten erscheinen (einschließlich innerhalb von Tool-Ergebnissen). Assistant-Nachrichten mit Suchergebnissen werden abgelehnt.- Wenn das Websuche-Tool in derselben Anfrage aktiviert ist, müssen Zitate für alle
search_result-Blöcke aktiviert sein.
Nächste Schritte
Erkenne und behandle Ablehnungs-Stop-Reasons in Streaming-Antworten und wiederhole abgelehnte Anfragen mit einem Fallback-Modell.
Verankere Claudes Antworten in deinen Quelldokumenten. Zitate geben die genauen Passagen zurück, die jede Aussage stützen, sodass du Antworten überprüfen und deinen Benutzern Quellen anzeigen kannst.
Gib Claude Zugriff auf aktuelle Webinhalte mit zitierten Quellen, optionaler dynamischer Filterung und Domain-Steuerung.
Sieh dir die vollständige Dokumentation der Messages API an, einschließlich der Inhaltsblocktypen.
Speichere Suchergebnisse mit cache_control zwischen, um Kosten und Latenz bei wiederholten Anfragen zu reduzieren.
Verfügbarkeit
Claude API
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Amazon Bedrock
- API
- Messages API
- Modelle
- Alle Modelle
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelle
- Alle Modelle
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Anthropic managed)
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelle
- Alle Modelle
Microsoft Foundry
- API
- Messages API
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/messagesmit Quellesearch_results
Ausgenommen: Abgedeckte Modelle
War diese Seite hilfreich?