Résultats de recherche

Les blocs de contenu de résultats de recherche permettent des citations naturelles avec une attribution de source appropriée, apportant à vos applications personnalisées des citations de qualité équivalente à celles de la recherche web. Cette fonctionnalité est particulièrement puissante pour les applications « RAG » (Retrieval-Augmented Generation, ou génération augmentée par récupération) où vous avez besoin que Claude cite ses sources avec précision.

La fonctionnalité de résultats de recherche est disponible sur les modèles suivants :

• Claude Opus 4.8 (claude-opus-4-8)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (déprécié) (claude-opus-4-1-20250805)
• Claude Opus 4 (déprécié) (claude-opus-4-20250514)
• Claude Sonnet 4 (déprécié) (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (retiré, sauf sur Bedrock et Vertex AI) (claude-3-5-haiku-20241022)



Principaux avantages

• Citations naturelles : Obtenez la même qualité de citation que la recherche web pour n'importe quel contenu
• Intégration flexible : Utilisez-les dans les retours d'outils pour du RAG dynamique ou comme contenu de premier niveau pour des données pré-récupérées
• Attribution de source appropriée : Chaque résultat inclut des informations de source et de titre pour une attribution claire
• Aucun contournement basé sur les documents nécessaire : Élimine le besoin de solutions de contournement basées sur les documents
• Format de citation cohérent : Correspond à la qualité et au format de citation de la fonctionnalité de recherche web de Claude



Fonctionnement

Les résultats de recherche peuvent être fournis de deux manières :

1. À partir d'appels d'outils : Vos outils personnalisés renvoient des résultats de recherche, permettant des applications RAG dynamiques
2. Comme contenu de premier niveau : Vous fournissez des résultats de recherche directement dans les messages utilisateur pour du contenu pré-récupéré ou mis en cache

Dans les deux cas, Claude peut automatiquement citer les informations provenant des résultats de recherche avec une attribution de source appropriée.



Schéma des résultats de recherche

Les résultats de recherche utilisent la structure suivante :

{
  "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
  }
}



Champs obligatoires



Champs optionnels

Chaque élément du tableau content doit être un bloc de texte avec :

• type : Doit être "text"
• text : Le contenu textuel réel (chaîne non vide)



Méthode 1 : Résultats de recherche à partir d'appels d'outils

Le cas d'usage le plus puissant consiste à renvoyer des résultats de recherche depuis vos outils personnalisés. Cela permet des applications RAG dynamiques où les outils récupèrent et renvoient du contenu pertinent avec des citations automatiques.



Exemple : Outil de base de connaissances

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

client = Anthropic()

# Définir un outil de recherche dans la base de connaissances
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"],
    },
}


# Fonction pour gérer l'appel d'outil
def search_knowledge_base(query):
    # Votre logique de recherche ici
    # Renvoie les résultats de recherche au format correct
    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},
        ),
    ]


# Créer un message avec l'outil
response = client.messages.create(
    model="claude-opus-4-8",  # Works with all supported models
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(role="user", content="How do I configure the timeout settings?")
    ],
)

# Lorsque Claude appelle l'outil, fournissez les résultats de recherche
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])

    # Renvoyer le résultat de l'outil
    final_response = client.messages.create(
        model="claude-opus-4-8",  # Works with all supported models
        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,  # Search results go here
                    )
                ],
            ),
        ],
    )



Méthode 2 : Résultats de recherche comme contenu de premier niveau

Vous pouvez également fournir des résultats de recherche directement dans les messages utilisateur. Ceci est utile pour :

• Du contenu pré-récupéré depuis votre infrastructure de recherche
• Des résultats de recherche mis en cache provenant de requêtes précédentes
• Du contenu provenant de services de recherche externes
• Les tests et le développement



Exemple : Résultats de recherche directs

from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam

client = Anthropic()

# Fournissez les résultats de recherche directement dans le message utilisateur
response = client.messages.create(
    model="claude-opus-4-8",
    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)



Réponse de Claude avec citations

Quelle que soit la manière dont les résultats de recherche sont fournis, Claude inclut automatiquement des citations lorsqu'il utilise des informations qui en proviennent :

{
  "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
        }
      ]
    }
  ]
}



Champs de citation

Chaque citation inclut :

Les index de blocs identifient une tranche du tableau content du résultat de recherche, et cited_text est le texte complet de cette tranche. Le bloc de texte est l'unité citable minimale : Claude cite des blocs entiers, et non des sous-chaînes au sein d'un bloc. Pour obtenir des citations plus fines, divisez le contenu de votre résultat de recherche en blocs plus petits (voir Blocs de contenu multiples).



Blocs de contenu multiples

Les résultats de recherche peuvent contenir plusieurs blocs de texte dans le tableau content :

{
  "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."
    }
  ]
}

Une citation référençant le bloc des limites de débit ressemble à ceci :

{
  "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
}

Lorsque ce résultat de recherche est cité, start_block_index et end_block_index identifient lesquels de ces blocs la citation couvre, et cited_text contient exactement le texte de ces blocs. Diviser le contenu en blocs plus petits et ciblés donne à Claude des limites de citation plus fines ; combiner le contenu en un seul bloc signifie que chaque citation renvoie le texte complet. C'est le même modèle que celui utilisé par les documents à contenu personnalisé dans la fonctionnalité Citations.



Utilisation avancée



Combinaison des deux méthodes

Vous pouvez utiliser à la fois des résultats de recherche basés sur des outils et de premier niveau dans la même conversation :

from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam

# Premier message avec des résultats de recherche au niveau supérieur
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 pourrait répondre et appeler un outil pour rechercher les tarifs
# Ensuite, vous fournissez les résultats d'outil avec d'autres résultats de recherche



Combinaison avec d'autres types de contenu

Les deux méthodes prennent en charge le mélange de résultats de recherche avec d'autres contenus :

from anthropic.types import SearchResultBlockParam, TextBlockParam

# Dans les résultats d'outils
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."
    ),
]

# Dans le contenu de niveau supérieur
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?"
    ),
]



Contrôle du cache

Ajoutez un contrôle du cache pour de meilleures performances :

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



Contrôle des citations

Par défaut, les citations sont désactivées pour les résultats de recherche. Vous pouvez activer les citations en définissant explicitement la configuration citations :

{
  "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
  }
}

Lorsque citations.enabled est défini sur true, Claude inclut des références de citation lorsqu'il utilise des informations provenant du résultat de recherche. Cela permet :

• Des citations naturelles pour vos applications RAG personnalisées
• L'attribution de source lors de l'interfaçage avec des bases de connaissances propriétaires
• Des citations de qualité équivalente à la recherche web pour tout outil personnalisé qui renvoie des résultats de recherche



Bonnes pratiques



Pour la recherche basée sur des outils (Méthode 1)

• Contenu dynamique : À utiliser pour les recherches en temps réel et les applications RAG dynamiques
• Gestion des erreurs : Renvoyez des messages appropriés lorsque les recherches échouent
• Limites de résultats : Renvoyez uniquement les résultats les plus pertinents pour éviter le débordement de contexte



Pour la recherche de premier niveau (Méthode 2)

• Contenu pré-récupéré : À utiliser lorsque vous disposez déjà de résultats de recherche
• Traitement par lots : Idéal pour traiter plusieurs résultats de recherche à la fois
• Tests : Parfait pour tester le comportement des citations avec du contenu connu



Bonnes pratiques générales

1. Structurez les résultats efficacement :

   • Utilisez des URL sources claires et permanentes
   • Fournissez des titres descriptifs
   • Divisez le contenu long en blocs de texte logiques pour donner à Claude des limites de citation plus fines

2. Maintenez la cohérence :

   • Utilisez des formats de source cohérents dans toute votre application
   • Assurez-vous que les titres reflètent fidèlement le contenu
   • Gardez un formatage cohérent

3. Gérez les erreurs avec élégance :

   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)}"}

   



Limitations

• Les blocs de contenu de résultats de recherche sont disponibles sur l'API Claude, Amazon Bedrock et Vertex AI de Google Cloud
• Seul le contenu textuel est pris en charge dans les résultats de recherche (pas d'images ni d'autres médias)
• Le tableau content doit contenir au moins un bloc de texte