Claude Platform Docs
MessagesModellfähigkeiten

Suchergebnisse

Aktiviere natürliche Zitate für RAG-Anwendungen, indem du Suchergebnisse mit Quellenangabe bereitstellst

Inhaltsblöcke für „search results“ (Suchergebnisse) ermöglichen es Claude, deine eigenen Inhalte auf dieselbe Weise zu zitieren, wie es Websuchergebnisse zitiert: Jedes Zitat enthält die Quelle und den Titel, die du angegeben hast. Verwende sie in RAG-Anwendungen („Retrieval-Augmented Generation“, abrufgestützte Generierung), in denen Claude Antworten deinen Dokumenten zuordnen muss.

Alle aktiven Modelle unterstützen Suchergebnisse mit Zitaten, mit Ausnahme von Claude Haiku 3. Es ist kein Beta-Header erforderlich: Suchergebnisse sind Teil der standardmäßigen Messages API.

So funktioniert es

Suchergebnisse können auf zwei Arten bereitgestellt werden:

  1. Aus Tool-Aufrufen: Deine benutzerdefinierten Tools geben Suchergebnisse zurück und ermöglichen so dynamische RAG-Anwendungen
  2. Als Inhalt auf oberster Ebene: Du stellst Suchergebnisse direkt in Benutzernachrichten bereit, für vorab abgerufene oder zwischengespeicherte Inhalte

In beiden Fällen zitiert Claude die Suchergebnisse automatisch, wenn Zitate aktiviert sind. Es ist kein spezielles Prompting nötig: Stelle deine Frage, und die Zitate erscheinen an den Textblöcken, die auf deine Inhalte zurückgreifen.

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

FeldTypBeschreibung
typestringMuss "search_result" sein
sourcestringDie Quelle des Inhalts. Jeder stabile String funktioniert: eine URL oder ein interner Bezeichner wie kb://article-1234
titlestringEin beschreibender Titel für das Suchergebnis
contentarrayEin Array von Textblöcken, die den eigentlichen Inhalt enthalten

Optionale Felder

FeldTypBeschreibung
citationsobjectZitatkonfiguration 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_controlobjectCache-Control-Einstellungen (zum Beispiel {"type": "ephemeral"})

Jedes Element im content-Array muss ein Textblock sein mit:

  • type: Muss "text" sein
  • text: Der eigentliche Textinhalt (nicht leerer String)

Suchergebnisse enthalten nur Text. Bilder und andere Medien werden innerhalb des content-Arrays nicht unterstützt.

Methode 1: Suchergebnisse aus Tool-Aufrufen

Das Zurückgeben von Suchergebnissen aus deinen benutzerdefinierten Tools ermöglicht dynamische RAG-Anwendungen: 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 Tool zur Suche in der 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 richtigen 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 als Liste auf, beginnend mit der Frage des Nutzers
messages = [
    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"},
    messages=messages,
)

# Wenn Claude das Tool aufruft, stelle die Suchergebnisse bereit.
# Der tool_use-Block steht nicht immer an erster Stelle: 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 Antwort und dann das Tool-Ergebnis an die laufende Konversation an
    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
                )
            ],
        )
    )

    # 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 von externen Suchdiensten
  • Tests und Entwicklung

Beispiel: Direkte Suchergebnisse

from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam

client = Anthropic()

# Stelle Suchergebnisse direkt in der User-Nachricht bereit
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)

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:

FeldTypBeschreibung
typestringImmer "search_result_location" für Zitate aus Suchergebnissen
sourcestringDie Quelle aus dem ursprünglichen Suchergebnis
titlestring oder nullDer Titel aus dem ursprünglichen Suchergebnis
cited_textstringDer vollständige Text des/der zitierten Blocks/Blöcke, zusammengefügt. Entspricht dem zusammengefügten Inhalt von content[start_block_index:end_block_index]. Wird nicht auf die Output-Token angerechnet.
search_result_indexinteger0-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_indexinteger0-basierter Index des ersten zitierten Blocks im content-Array des Suchergebnisses.
end_block_indexintegerExklusiver Endindex des zitierten Blockbereichs im content-Array des Suchergebnisses. Immer größer als start_block_index.

Die Blockindizes bezeichnen 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 Block zu Ratenlimits 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 einen einzigen Block bedeutet, dass jedes Zitat den vollständigen Text zurückgibt. Dies ist dasselbe Modell, das von Dokumenten mit benutzerdefiniertem Inhalt in der Zitate-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 (
    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"],
    },
}

# Spiele eine Konversation ab, die Suchergebnisse auf beide Arten liefert: Die erste
# Nutzernachricht enthält ein vorab abgerufenes Ergebnis, das Tool-Ergebnis liefert ein weiteres
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)

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 aus Methode 2 kombiniert Suchergebnisse mit einer text-Frage, und Bild- oder Dokumentblöcke können auf dieselbe Weise hinzukommen.

Tool-Ergebnisse sind strenger: Wenn irgendein Block im content-Array eines tool_result 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 begleitenden Text zusammen mit Suchergebnissen aus Tools zurückzugeben, füge ihn als Textblock in das content-Array eines der Suchergebnisse ein, wo er ebenfalls zitierbar wird.

Cache Control

Füge cache_control zum Suchergebnisblock hinzu, um ihn für die Wiederverwendung über Anfragen hinweg zu cachen. 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 minimale cachebare Längen und weitere Anforderungen.

Zitatsteuerung

Standardmäßig sind Zitate für Suchergebnisse deaktiviert. Du kannst Zitate aktivieren, indem du die citations-Konfiguration explizit setzt:

{
  "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, fügt Claude Zitatverweise an die Textblöcke an, die auf das Suchergebnis zurückgreifen.

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
  • Batch-Verarbeitung: Ideal für die Verarbeitung mehrerer Suchergebnisse auf einmal
  • Tests: Hervorragend geeignet, um das Zitatverhalten mit bekannten Inhalten zu testen

Allgemeine Best Practices

  1. Ergebnisse effektiv strukturieren:

    • Verwende klare, dauerhafte Quell-URLs
    • Gib beschreibende Titel an
    • Teile lange Inhalte in logische Textblöcke auf, um Claude feinere Zitatgrenzen zu geben
  2. Konsistenz wahren:

    • Verwende einheitliche Quellformate in deiner gesamten Anwendung
    • Stelle sicher, dass Titel den Inhalt genau widerspiegeln
    • Halte die Formatierung konsistent
  3. 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 geht weiter.

Einschränkungen

  • Inhaltsblöcke für Suchergebnisse sind auf der Claude API, Amazon Bedrock und Google Cloud verfügbar.
  • Innerhalb von Suchergebnissen wird nur Textinhalt unterstützt (keine Bilder oder andere 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-Kontrollen.

Sieh dir die vollständige Dokumentation der Messages API an, einschließlich der Inhaltsblocktypen.

Cache Suchergebnisse mit cache_control, um Kosten und Latenz bei wiederholten Anfragen zu reduzieren.

Was this page helpful?