Claude Platform Docs
MessagesModellfähigkeiten

Suchergebnisse

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

Nutzung unterscheidet sich je nach Produkt

Messages API
Sende search_result-Blöcke in einem Tool-Ergebnis oder direkt in einer Benutzernachricht.
Managed Agents
Nur in Tool-Ergebnissen akzeptiert, etwa in einem Event 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:

  1. Aus Tool-Aufrufen: Deine benutzerdefinierten Tools geben Suchergebnisse zurück, wodurch du dynamische RAG-Anwendungen erstellen kannst.
  2. 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

FeldTypBeschreibung
typestringMuss "search_result" sein
sourcestringDie Quelle des Inhalts. Jeder stabile String funktioniert: eine URL oder eine interne Kennung wie kb://article-1234
titlestringEin aussagekräftiger 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-Steuerungseinstellungen (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 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:

FeldTypBeschreibung
typestringBei Suchergebnis-Zitaten immer "search_result_location"
sourcestringDie Quelle aus dem ursprünglichen Suchergebnis
titlestring oder nullDer Titel aus dem ursprünglichen Suchergebnis
cited_textstringDer 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_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 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

  1. 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
  2. Konsistenz wahren:

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

Suchergebnisse
APIs
  • Messages API
  • Managed Agents
Modelle
  • Alle Modelle

Zutreffende Endpunkte

  • /v1/messages mit Quelle search_results
Zero Data RetentionBerechtigt

Ausgenommen: Abgedeckte Modelle

HIPAABerechtigt

War diese Seite hilfreich?