Suchergebnis-Inhaltsblöcke befinden sich derzeit in der Beta-Phase. Verwenden Sie den search-results-2025-06-09 Beta-Header, um diese Funktion zu aktivieren.

Suchergebnis-Inhaltsblöcke ermöglichen natürliche Zitate mit ordnungsgemäßer Quellenangabe und bringen Web-Such-Qualitätszitate in Ihre benutzerdefinierten Anwendungen. Diese Funktion ist besonders leistungsstark für RAG (Retrieval-Augmented Generation) Anwendungen, bei denen Claude Quellen genau zitieren muss.

Hauptvorteile

  • Natürliche Zitate - Erreichen Sie die gleiche Zitatqualität wie bei der Websuche für jeden Inhalt
  • Flexible Integration - Verwenden Sie in Tool-Rückgaben für dynamisches RAG oder als Top-Level-Inhalt für vorab abgerufene Daten
  • Ordnungsgemäße Quellenangabe - Jedes Ergebnis enthält Quellen- und Titelinformationen für klare Zuordnung
  • Keine Dokument-Workarounds erforderlich - Eliminiert die Notwendigkeit für dokumentbasierte Workarounds
  • Konsistentes Zitatformat - Entspricht der Zitatqualität und dem Format von Claudes Websuchfunktionalität

Wie es funktioniert

Suchergebnisse können auf zwei Arten bereitgestellt werden:

  1. Aus Tool-Aufrufen - Ihre benutzerdefinierten Tools geben Suchergebnisse zurück und ermöglichen dynamische RAG-Anwendungen
  2. Als Top-Level-Inhalt - Sie stellen Suchergebnisse direkt in Benutzernachrichten für vorab abgerufene oder zwischengespeicherte Inhalte bereit

In beiden Fällen kann Claude automatisch Informationen aus den Suchergebnissen mit ordnungsgemäßer Quellenangabe zitieren.

Suchergebnis-Schema

Suchergebnisse verwenden die folgende Struktur:

{
  "type": "search_result",
  "source": "https://example.com/article",  // Erforderlich: Quell-URL oder Identifikator
  "title": "Artikeltitel",                  // Erforderlich: Titel des Ergebnisses
  "content": [ // Erforderlich: Array von Textblöcken
    {
      "type": "text",
      "text": "Der tatsächliche Inhalt des Suchergebnisses..."
    }
  ],
  "citations": {                             // Optional: Zitierkonfiguration
    "enabled": true                          // Zitate für dieses Ergebnis aktivieren/deaktivieren
  }
}

Erforderliche Felder

FeldTypBeschreibung
typestringMuss "search_result" sein
sourcestringDie Quell-URL oder der Identifikator für den Inhalt
titlestringEin beschreibender Titel für das Suchergebnis
contentarrayEin Array von Textblöcken mit dem tatsächlichen Inhalt

Optionale Felder

FeldTypBeschreibung
citationsobjectZitierkonfiguration mit enabled Boolean-Feld
cache_controlobjectCache-Kontrolleinstellungen (z.B. {"type": "ephemeral"})

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

  • type: Muss "text" sein
  • text: Der tatsächliche Textinhalt (nicht-leere Zeichenkette)

Methode 1: Suchergebnisse aus Tool-Aufrufen

Der leistungsstärkste Anwendungsfall ist die Rückgabe von Suchergebnissen aus Ihren benutzerdefinierten Tools. Dies ermöglicht dynamische RAG-Anwendungen, bei denen Tools relevante Inhalte mit automatischen Zitaten abrufen und zurückgeben.

Beispiel: Wissensdatenbank-Tool

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam,
    BetaToolResultBlockParam
)

client = Anthropic()

# Definiere ein Wissensdatenbank-Suchtool
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Durchsuche die Unternehmens-Wissensdatenbank nach Informationen",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Die Suchanfrage"
            }
        },
        "required": ["query"]
    }
}

# Funktion zur Behandlung des Tool-Aufrufs
def search_knowledge_base(query):
    # Ihre Suchlogik hier
    # Gibt Suchergebnisse im korrekten Format zurück
    return [
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Produktkonfigurationsleitfaden",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Um das Produkt zu konfigurieren, navigieren Sie zu Einstellungen > Konfiguration. Das Standard-Timeout beträgt 30 Sekunden, kann aber je nach Ihren Bedürfnissen zwischen 10-120 Sekunden angepasst werden."
                )
            ],
            citations={"enabled": True}
        ),
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Fehlerbehebungsleitfaden",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Wenn Sie Timeout-Fehler auftreten, überprüfen Sie zuerst die Konfigurationseinstellungen. Häufige Ursachen sind Netzwerklatenz und falsche Timeout-Werte."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Erstelle eine Nachricht mit dem Tool
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    tools=[knowledge_base_tool],
    messages=[
        BetaMessageParam(
            role="user",
            content="Wie konfiguriere ich die Timeout-Einstellungen?"
        )
    ]
)

# Wenn Claude das Tool aufruft, stelle die Suchergebnisse bereit
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Sende das Tool-Ergebnis zurück
    final_response = client.beta.messages.create(
        model="claude-opus-4-20250514",
        max_tokens=1024,
        betas=["search-results-2025-06-09"],
        messages=[
            BetaMessageParam(role="user", content="Wie konfiguriere ich die Timeout-Einstellungen?"),
            BetaMessageParam(role="assistant", content=response.content),
            BetaMessageParam(
                role="user",
                content=[
                    BetaToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Suchergebnisse kommen hier hin
                    )
                ]
            )
        ]
    )

Methode 2: Suchergebnisse als Top-Level-Inhalt

Sie können auch Suchergebnisse direkt in Benutzernachrichten bereitstellen. Dies ist nützlich für:

  • Vorab abgerufene Inhalte aus Ihrer Suchinfrastruktur
  • Zwischengespeicherte Suchergebnisse aus vorherigen Anfragen
  • Inhalte von externen Suchdiensten
  • Tests und Entwicklung

Beispiel: Direkte Suchergebnisse

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam
)

client = Anthropic()

# Stelle Suchergebnisse direkt in der Benutzernachricht bereit
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    messages=[
        BetaMessageParam(
            role="user",
            content=[
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="API-Referenz - Authentifizierung",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Alle API-Anfragen müssen einen API-Schlüssel im Authorization-Header enthalten. Schlüssel können über das Dashboard generiert werden. Ratenlimits: 1000 Anfragen pro Stunde für Standard-Tier, 10000 für Premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Erste Schritte Leitfaden",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Um zu beginnen: 1) Registrieren Sie sich für ein Konto, 2) Generieren Sie einen API-Schlüssel über das Dashboard, 3) Installieren Sie unser SDK mit pip install company-sdk, 4) Initialisieren Sie den Client mit Ihrem API-Schlüssel."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaTextBlockParam(
                    type="text",
                    text="Basierend auf diesen Suchergebnissen, wie authentifiziere ich API-Anfragen und was sind die Ratenlimits?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

Claudes Antwort mit Zitaten

Unabhängig davon, wie Suchergebnisse bereitgestellt werden, fügt Claude automatisch Zitate hinzu, wenn Informationen aus ihnen verwendet werden:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Um API-Anfragen zu authentifizieren, müssen Sie einen API-Schlüssel im Authorization-Header einschließen",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API-Referenz - Authentifizierung",
          "cited_text": "Alle API-Anfragen müssen einen API-Schlüssel im Authorization-Header enthalten",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Sie können API-Schlüssel über Ihr Dashboard generieren",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API-Referenz - Authentifizierung",
          "cited_text": "Schlüssel können über das Dashboard generiert werden",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Die Ratenlimits betragen 1.000 Anfragen pro Stunde für den Standard-Tier und 10.000 Anfragen pro Stunde für den Premium-Tier.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API-Referenz - Authentifizierung",
          "cited_text": "Ratenlimits: 1000 Anfragen pro Stunde für Standard-Tier, 10000 für Premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

Zitatfelder

Jedes Zitat enthält:

FeldTypBeschreibung
typestringImmer "search_result_location" für Suchergebnis-Zitate
sourcestringDie Quelle aus dem ursprünglichen Suchergebnis
titlestring oder nullDer Titel aus dem ursprünglichen Suchergebnis
cited_textstringDer exakte Text, der zitiert wird
search_result_indexintegerIndex des Suchergebnisses (0-basiert)
start_block_indexintegerStartposition im content-Array
end_block_indexintegerEndposition im content-Array

Hinweis: Der search_result_index bezieht sich auf den Index des Suchergebnis-Inhaltsblocks (0-basiert), unabhängig davon, wie die Suchergebnisse bereitgestellt wurden (Tool-Aufruf oder Top-Level-Inhalt).

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-Dokumentation",
  "content": [
    {
      "type": "text",
      "text": "Authentifizierung: Alle API-Anfragen erfordern einen API-Schlüssel."
    },
    {
      "type": "text",
      "text": "Ratenlimits: Die API erlaubt 1000 Anfragen pro Stunde pro Schlüssel."
    },
    {
      "type": "text",
      "text": "Fehlerbehandlung: Die API gibt Standard-HTTP-Statuscodes zurück."
    }
  ]
}

Claude kann spezifische Blöcke mit den Feldern start_block_index und end_block_index zitieren.

Erweiterte Nutzung

Kombination beider Methoden

Sie können sowohl tool-basierte als auch Top-Level-Suchergebnisse in derselben Unterhaltung verwenden:

# Erste Nachricht mit Top-Level-Suchergebnissen
messages = [
    BetaMessageParam(
        role="user",
        content=[
            BetaSearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Produktübersicht",
                content=[
                    BetaTextBlockParam(type="text", text="Unser Produkt hilft Teams bei der Zusammenarbeit...")
                ],
                citations={"enabled": True}
            ),
            BetaTextBlockParam(
                type="text",
                text="Erzählen Sie mir von diesem Produkt und suchen Sie nach Preisinformationen"
            )
        ]
    )
]

# Claude könnte antworten und ein Tool aufrufen, um nach Preisen zu suchen
# Dann stellen Sie Tool-Ergebnisse mit weiteren Suchergebnissen bereit

Kombination mit anderen Inhaltstypen

Beide Methoden unterstützen das Mischen von Suchergebnissen mit anderen Inhalten:

# In Tool-Ergebnissen
tool_result = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Benutzerhandbuch",
        content=[BetaTextBlockParam(type="text", text="Konfigurationsdetails...")],
        citations={"enabled": True}
    ),
    BetaTextBlockParam(
        type="text",
        text="Zusätzlicher Kontext: Dies gilt für Version 2.0 und später."
    )
]

# In Top-Level-Inhalt
user_content = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Forschungsarbeit",
        content=[BetaTextBlockParam(type="text", text="Wichtige Erkenntnisse...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    BetaTextBlockParam(
        type="text",
        text="Wie bezieht sich das Diagramm auf die Forschungsergebnisse?"
    )
]

Cache-Kontrolle

Fügen Sie Cache-Kontrolle für bessere Leistung hinzu:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Benutzerhandbuch",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

Zitierkontrolle

Standardmäßig sind Zitate für Suchergebnisse deaktiviert. Sie können Zitate aktivieren, indem Sie explizit die citations-Konfiguration setzen:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Benutzerhandbuch",
  "content": [{"type": "text", "text": "Wichtige Dokumentation..."}],
  "citations": {
    "enabled": true  // Zitate für dieses Ergebnis aktivieren
  }
}

Wenn citations.enabled auf true gesetzt ist, wird Claude Zitatreferenzen einschließen, wenn Informationen aus dem Suchergebnis verwendet werden. Dies ermöglicht:

  • Natürliche Zitate für Ihre benutzerdefinierten RAG-Anwendungen
  • Quellenangabe bei der Schnittstelle mit proprietären Wissensdatenbanken
  • Web-Such-Qualitätszitate für jedes benutzerdefinierte Tool, das Suchergebnisse zurückgibt

Wenn das citations-Feld weggelassen wird, sind Zitate standardmäßig deaktiviert.

Zitate sind alles-oder-nichts: Entweder müssen alle Suchergebnisse in einer Anfrage Zitate aktiviert haben, oder alle müssen sie deaktiviert haben. Das Mischen von Suchergebnissen mit unterschiedlichen Zitateinstellungen führt zu einem Fehler. Wenn Sie Zitate für einige Quellen deaktivieren müssen, müssen Sie sie für alle Suchergebnisse in dieser Anfrage deaktivieren.

Best Practices

Für tool-basierte Suche (Methode 1)

  • Dynamischer Inhalt: Verwenden Sie für Echtzeitsuchen und dynamische RAG-Anwendungen
  • Fehlerbehandlung: Geben Sie angemessene Nachrichten zurück, wenn Suchen fehlschlagen
  • Ergebnislimits: Geben Sie nur die relevantesten Ergebnisse zurück, um Kontextüberlauf zu vermeiden

Für Top-Level-Suche (Methode 2)

  • Vorab abgerufener Inhalt: Verwenden Sie, wenn Sie bereits Suchergebnisse haben
  • Stapelverarbeitung: Ideal für die Verarbeitung mehrerer Suchergebnisse auf einmal
  • Tests: Großartig zum Testen des Zitierverhaltens mit bekannten Inhalten

Allgemeine Best Practices

  1. Strukturieren Sie Ergebnisse effektiv

    • Verwenden Sie klare, permanente Quell-URLs
    • Stellen Sie beschreibende Titel bereit
    • Teilen Sie lange Inhalte in logische Textblöcke auf
  2. Konsistenz beibehalten

    • Verwenden Sie konsistente Quellformate in Ihrer Anwendung
    • Stellen Sie sicher, dass Titel den Inhalt genau widerspiegeln
    • Halten Sie die Formatierung konsistent
  3. Fehler elegant behandeln

    def search_with_fallback(query):
        try:
            results = perform_search(query)
            if not results:
                return {"type": "text", "text": "Keine Ergebnisse gefunden."}
            return format_as_search_results(results)
        except Exception as e:
            return {"type": "text", "text": f"Suchfehler: {str(e)}"}
    

Einschränkungen

  • Suchergebnis-Inhaltsblöcke sind nur mit dem Beta-Header verfügbar
  • Nur Textinhalt wird innerhalb von Suchergebnissen unterstützt (keine Bilder oder andere Medien)
  • Das content-Array muss mindestens einen Textblock enthalten