Suchergebnis-Inhaltsblöcke ermöglichen natürliche Zitate mit ordnungsgemäßer Quellenangabe und bringen Web-Such-ähnliche Zitate in Ihre benutzerdefinierten Anwendungen. Diese Funktion ist besonders leistungsstark für RAG-Anwendungen (Retrieval-Augmented Generation), bei denen Claude Quellen genau zitieren muss. Die Suchergebnis-Funktion ist auf den folgenden Modellen verfügbar:
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (veraltet) (claude-3-7-sonnet-20250219)
  • Claude 3.5 Haiku (claude-3-5-haiku-20241022)

Wichtigste Vorteile

  • Natürliche Zitate - Erreichen Sie die gleiche Zitierqualität wie bei der Websuche für beliebige Inhalte
  • 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 Zuschreibung
  • Keine Dokument-Workarounds erforderlich - Beseitigt die Notwendigkeit für dokumentbasierte Workarounds
  • Konsistentes Zitierformat - Entspricht der Zitierqualität und dem Format von Claudes Web-Such-Funktionalitä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: Quellen-URL oder Kennung
  "title": "Article Title",                  // Erforderlich: Titel des Ergebnisses
  "content": [ // Erforderlich: Array von Textblöcken
    {
      "type": "text",
      "text": "The actual content of the search result..."
    }
  ],
  "citations": {                             // Optional: Zitier-Konfiguration
    "enabled": true                          // Zitate für dieses Ergebnis aktivieren/deaktivieren
  }
}

Erforderliche Felder

FeldTypBeschreibung
typestringMuss "search_result" sein
sourcestringDie Quellen-URL oder Kennung für den Inhalt
titlestringEin beschreibender Titel für das Suchergebnis
contentarrayEin Array von Textblöcken mit dem eigentlichen Inhalt

Optionale Felder

FeldTypBeschreibung
citationsobjectZitier-Konfiguration 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 eigentliche 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 import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam,
    ToolResultBlockParam
)

client = Anthropic()

# Definieren Sie ein Wissensdatenbank-Such-Tool
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 zum Verarbeiten des Tool-Aufrufs
def search_knowledge_base(query):
    # Ihre Such-Logik 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}
        )
    ]

# Erstellen Sie eine Nachricht mit dem Tool
response = client.messages.create(
    model="claude-sonnet-4-5",  # Funktioniert mit allen unterstützten Modellen
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content="How do I configure the timeout settings?"
        )
    ]
)

# Wenn Claude das Tool aufruft, stellen Sie die Suchergebnisse bereit
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Senden Sie das Tool-Ergebnis zurück
    final_response = client.messages.create(
        model="claude-sonnet-4-5",  # Funktioniert mit allen unterstützten Modellen
        max_tokens=1024,
        messages=[
            MessageParam(role="user", content="How do I configure the timeout settings?"),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Suchergebnisse gehen 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 Such-Infrastruktur
  • Zwischengespeicherte Suchergebnisse aus vorherigen Abfragen
  • Inhalte von externen Such-Services
  • Tests und Entwicklung

Beispiel: Direkte Suchergebnisse

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam
)

client = Anthropic()

# Stellen Sie Suchergebnisse direkt in der Benutzernachricht bereit
response = client.messages.create(
    model="claude-sonnet-4-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.model_dump_json(indent=2))

Claudes Antwort mit Zitaten

Unabhängig davon, wie Suchergebnisse bereitgestellt werden, fügt Claude automatisch Zitate ein, wenn Informationen aus ihnen verwendet werden:
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "To authenticate API requests, you need to include an API key in the Authorization header",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "All API requests must include an API key in the Authorization header",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". You can generate API keys from your dashboard",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Keys can be generated from the dashboard",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". The rate limits are 1,000 requests per hour for the standard tier and 10,000 requests per hour for the premium tier.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Rate limits: 1000 requests per hour for standard tier, 10000 for premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

Zitat-Felder

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 genaue zitierte Text
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 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."
    }
  ]
}
Claude kann spezifische Blöcke mit den Feldern start_block_index und end_block_index zitieren.

Erweiterte Verwendung

Kombination beider Methoden

Sie können Tool-basierte und Top-Level-Suchergebnisse in der gleichen Konversation verwenden:
# Erste Nachricht mit Top-Level-Suchergebnissen
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Product Overview",
                content=[
                    TextBlockParam(type="text", text="Our product helps teams collaborate...")
                ],
                citations={"enabled": True}
            ),
            TextBlockParam(
                type="text",
                text="Tell me about this product and search for pricing information"
            )
        ]
    )
]

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

Kombination mit anderen Inhaltstypen

Beide Methoden unterstützen das Mischen von Suchergebnissen mit anderen Inhalten:
# In Tool-Ergebnissen
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="User Guide",
        content=[TextBlockParam(type="text", text="Configuration details...")],
        citations={"enabled": True}
    ),
    TextBlockParam(
        type="text",
        text="Additional context: This applies to version 2.0 and later."
    )
]

# In Top-Level-Inhalt
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Research Paper",
        content=[TextBlockParam(type="text", text="Key findings...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    TextBlockParam(
        type="text",
        text="How does the chart relate to the research findings?"
    )
]

Cache-Kontrolle

Fügen Sie Cache-Kontrolle für bessere Leistung hinzu:
{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

Zitier-Kontrolle

Standardmäßig sind Zitate für Suchergebnisse deaktiviert. Sie können Zitate aktivieren, indem Sie die citations-Konfiguration explizit setzen:
{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{"type": "text", "text": "Important documentation..."}],
  "citations": {
    "enabled": true  // Zitate für dieses Ergebnis aktivieren
  }
}
Wenn citations.enabled auf true gesetzt ist, wird Claude Zitierverweise einbeziehen, 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-ähnliche Zitate 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 Zitiereinstellungen 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)

  • Dynamische Inhalte: Verwenden Sie für Echtzeitsuchen und dynamische RAG-Anwendungen
  • Fehlerbehandlung: Geben Sie geeignete Meldungen zurück, wenn Suchen fehlschlagen
  • Ergebnis-Limits: Geben Sie nur die relevantesten Ergebnisse zurück, um Kontext-Überfluss zu vermeiden

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

  • Vorab abgerufene Inhalte: Verwenden Sie, wenn Sie bereits Suchergebnisse haben
  • Batch-Verarbeitung: Ideal für die Verarbeitung mehrerer Suchergebnisse auf einmal
  • Tests: Großartig zum Testen des Zitier-Verhaltens mit bekannten Inhalten

Allgemeine Best Practices

  1. Strukturieren Sie Ergebnisse effektiv
    • Verwenden Sie klare, permanente Quellen-URLs
    • Stellen Sie beschreibende Titel bereit
    • Teilen Sie lange Inhalte in logische Textblöcke auf
  2. Bewahren Sie Konsistenz
    • Verwenden Sie konsistente Quellenformate in Ihrer Anwendung
    • Stellen Sie sicher, dass Titel den Inhalt genau widerspiegeln
    • Halten Sie die Formatierung konsistent
  3. Behandeln Sie Fehler elegant
    def search_with_fallback(query):
        try:
            results = perform_search(query)
            if not results:
                return {"type": "text", "text": "No results found."}
            return format_as_search_results(results)
        except Exception as e:
            return {"type": "text", "text": f"Search error: {str(e)}"}
    

Einschränkungen

  • Suchergebnis-Inhaltsblöcke sind auf Claude API und Google Cloud’s Vertex AI verfügbar
  • Nur Textinhalte werden in Suchergebnissen unterstützt (keine Bilder oder andere Medien)
  • Das content-Array muss mindestens einen Textblock enthalten