Suchergebnisse

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

Die Suchergebnisse-Funktion ist für die folgenden Modelle verfügbar:

• Claude 3.5 Haiku (claude-3-5-haiku-20241022)
• Claude 3.5 Sonnet (claude-3-5-sonnet-20241022)
• Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)

​

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

​

Funktionsweise

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

​

Optionale Felder

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

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

​

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 abrufen und mit automatischen Zitaten 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-sonnet-4-20250514",  # Funktioniert mit allen unterstützten Modellen
    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-sonnet-4-20250514",  # Funktioniert mit allen unterstützten Modellen
        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 Suchergebnisse auch 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 daraus 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:

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 Verwendung

​

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
• Websuch-Qualitätszitate für jedes benutzerdefinierte Tool, das Suchergebnisse zurückgibt

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

​

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 bekanntem Inhalt

​

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