Les blocs de contenu de résultats de recherche sont actuellement en version bêta. Utilisez l’en-tête bêta search-results-2025-06-09 pour activer cette fonctionnalité.

Les blocs de contenu de résultats de recherche permettent des citations naturelles avec une attribution de source appropriée, apportant des citations de qualité de recherche web à vos applications personnalisées. Cette fonctionnalité est particulièrement puissante pour les applications RAG (Génération Augmentée par Récupération) où vous avez besoin que Claude cite les sources avec précision.

​
Avantages clés

  • Citations naturelles - Obtenez la même qualité de citation que la recherche web pour n’importe quel contenu
  • Intégration flexible - Utilisez dans les retours d’outils pour un RAG dynamique ou comme contenu de niveau supérieur 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
  • Aucune solution de contournement de document nécessaire - Élimine le besoin de solutions de contournement basées sur des documents
  • Format de citation cohérent - Correspond à la qualité et au format de citation de la fonctionnalité de recherche web de Claude

​
Comment ça fonctionne

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

  1. À partir d’appels d’outils - Vos outils personnalisés retournent des résultats de recherche, permettant des applications RAG dynamiques
  2. Comme contenu de niveau supérieur - 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 des informations des résultats de recherche avec une attribution de source appropriée.

​
Schéma de résultat de recherche

Les résultats de recherche utilisent la structure suivante :

{
  "type": "search_result",
  "source": "https://example.com/article",  // Requis : URL ou identifiant de source
  "title": "Titre de l'article",                  // Requis : Titre du résultat
  "content": [ // Requis : Tableau de blocs de texte
    {
      "type": "text",
      "text": "Le contenu réel du résultat de recherche..."
    }
  ],
  "citations": {                             // Optionnel : Configuration de citation
    "enabled": true                          // Activer/désactiver les citations pour ce résultat
  }
}

​
Champs requis

ChampTypeDescription
typestringDoit être "search_result"
sourcestringL’URL ou identifiant de source pour le contenu
titlestringUn titre descriptif pour le résultat de recherche
contentarrayUn tableau de blocs de texte contenant le contenu réel

​
Champs optionnels

ChampTypeDescription
citationsobjectConfiguration de citation avec champ booléen enabled
cache_controlobjectParamètres de contrôle de cache (par ex., {"type": "ephemeral"})

Chaque élément dans le 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 est de retourner des résultats de recherche à partir de vos outils personnalisés. Cela permet des applications RAG dynamiques où les outils récupèrent et retournent du contenu pertinent avec des citations automatiques.

​
Exemple : Outil de base de connaissances

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

client = Anthropic()

# Définir un outil de recherche de base de connaissances
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Rechercher dans la base de connaissances de l'entreprise pour des informations",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "La requête de recherche"
            }
        },
        "required": ["query"]
    }
}

# Fonction pour gérer l'appel d'outil
def search_knowledge_base(query):
    # Votre logique de recherche ici
    # Retourne des résultats de recherche dans le format correct
    return [
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Guide de Configuration Produit",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Pour configurer le produit, naviguez vers Paramètres > Configuration. Le délai d'attente par défaut est de 30 secondes, mais peut être ajusté entre 10-120 secondes selon vos besoins."
                )
            ],
            citations={"enabled": True}
        ),
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Guide de Dépannage",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Si vous rencontrez des erreurs de délai d'attente, vérifiez d'abord les paramètres de configuration. Les causes communes incluent la latence réseau et des valeurs de délai d'attente incorrectes."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Créer un message avec l'outil
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="Comment configurer les paramètres de délai d'attente ?"
        )
    ]
)

# Quand Claude appelle l'outil, fournir 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.beta.messages.create(
        model="claude-opus-4-20250514",
        max_tokens=1024,
        betas=["search-results-2025-06-09"],
        messages=[
            BetaMessageParam(role="user", content="Comment configurer les paramètres de délai d'attente ?"),
            BetaMessageParam(role="assistant", content=response.content),
            BetaMessageParam(
                role="user",
                content=[
                    BetaToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Les résultats de recherche vont ici
                    )
                ]
            )
        ]
    )

​
Méthode 2 : Résultats de recherche comme contenu de niveau supérieur

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

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

​
Exemple : Résultats de recherche directs

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

client = Anthropic()

# Fournir des résultats de recherche directement dans le message utilisateur
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="Référence API - Authentification",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Toutes les requêtes API doivent inclure une clé API dans l'en-tête Authorization. Les clés peuvent être générées depuis le tableau de bord. Limites de taux : 1000 requêtes par heure pour le niveau standard, 10000 pour le premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Guide de Démarrage",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Pour commencer : 1) Inscrivez-vous pour un compte, 2) Générez une clé API depuis le tableau de bord, 3) Installez notre SDK en utilisant pip install company-sdk, 4) Initialisez le client avec votre clé API."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaTextBlockParam(
                    type="text",
                    text="Basé sur ces résultats de recherche, comment authentifier les requêtes API et quelles sont les limites de taux ?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

​
Réponse de Claude avec citations

Peu importe comment les résultats de recherche sont fournis, Claude inclut automatiquement des citations lors de l’utilisation d’informations de ceux-ci :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Pour authentifier les requêtes API, vous devez inclure une clé API dans l'en-tête Authorization",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Référence API - Authentification",
          "cited_text": "Toutes les requêtes API doivent inclure une clé API dans l'en-tête Authorization",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Vous pouvez générer des clés API depuis votre tableau de bord",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Référence API - Authentification",
          "cited_text": "Les clés peuvent être générées depuis le tableau de bord",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Les limites de taux sont de 1 000 requêtes par heure pour le niveau standard et 10 000 requêtes par heure pour le niveau premium.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Référence API - Authentification",
          "cited_text": "Limites de taux : 1000 requêtes par heure pour le niveau standard, 10000 pour le premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

​
Champs de citation

Chaque citation inclut :

ChampTypeDescription
typestringToujours "search_result_location" pour les citations de résultats de recherche
sourcestringLa source du résultat de recherche original
titlestring ou nullLe titre du résultat de recherche original
cited_textstringLe texte exact étant cité
search_result_indexintegerIndex du résultat de recherche (basé sur 0)
start_block_indexintegerPosition de début dans le tableau de contenu
end_block_indexintegerPosition de fin dans le tableau de contenu

Note : Le search_result_index fait référence à l’index du bloc de contenu de résultat de recherche (basé sur 0), peu importe comment les résultats de recherche ont été fournis (appel d’outil ou contenu de niveau supérieur).

​
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": "Documentation API",
  "content": [
    {
      "type": "text",
      "text": "Authentification : Toutes les requêtes API nécessitent une clé API."
    },
    {
      "type": "text",
      "text": "Limites de Taux : L'API permet 1000 requêtes par heure par clé."
    },
    {
      "type": "text",
      "text": "Gestion d'Erreurs : L'API retourne des codes de statut HTTP standard."
    }
  ]
}

Claude peut citer des blocs spécifiques en utilisant les champs start_block_index et end_block_index.

​
Utilisation avancée

​
Combiner les deux méthodes

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

# Premier message avec des résultats de recherche de niveau supérieur
messages = [
    BetaMessageParam(
        role="user",
        content=[
            BetaSearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Aperçu du Produit",
                content=[
                    Bet

aTextBlockParam(type="text", text="Notre produit aide les équipes à collaborer...")
                ],
                citations={"enabled": True}
            ),
            BetaTextBlockParam(
                type="text",
                text="Parlez-moi de ce produit et recherchez des informations de tarification"
            )
        ]
    )
]

# Claude pourrait répondre et appeler un outil pour rechercher la tarification
# Puis vous fournissez des résultats d'outils avec plus de résultats de recherche

​
Combiner avec d’autres types de contenu

Les deux méthodes supportent le mélange de résultats de recherche avec d’autres contenus :

# Dans les résultats d'outils
tool_result = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Guide Utilisateur",
        content=[BetaTextBlockParam(type="text", text="Détails de configuration...")],
        citations={"enabled": True}
    ),
    BetaTextBlockParam(
        type="text",
        text="Contexte supplémentaire : Ceci s'applique à la version 2.0 et ultérieures."
    )
]

# Dans le contenu de niveau supérieur
user_content = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Article de Recherche",
        content=[BetaTextBlockParam(type="text", text="Résultats clés...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    BetaTextBlockParam(
        type="text",
        text="Comment le graphique se rapporte-t-il aux résultats de recherche ?"
    )
]

​
Contrôle de cache

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

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

​
Contrôle de citation

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": "Guide Utilisateur",
  "content": [{"type": "text", "text": "Documentation importante..."}],
  "citations": {
    "enabled": true  // Activer les citations pour ce résultat
  }
}

Quand citations.enabled est défini sur true, Claude inclura des références de citation lors de l’utilisation d’informations du résultat de recherche. Cela permet :

  • Des citations naturelles pour vos applications RAG personnalisées
  • L’attribution de source lors de l’interface avec des bases de connaissances propriétaires
  • Des citations de qualité de recherche web pour tout outil personnalisé qui retourne des résultats de recherche

Si le champ citations est omis, les citations sont désactivées par défaut.

Les citations sont tout ou rien : soit tous les résultats de recherche dans une requête doivent avoir les citations activées, soit tous doivent les avoir désactivées. Mélanger des résultats de recherche avec différents paramètres de citation résultera en une erreur. Si vous devez désactiver les citations pour certaines sources, vous devez les désactiver pour tous les résultats de recherche dans cette requête.

​
Meilleures pratiques

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

  • Contenu dynamique : Utilisez pour des recherches en temps réel et des applications RAG dynamiques
  • Gestion d’erreurs : Retournez des messages appropriés quand les recherches échouent
  • Limites de résultats : Retournez seulement les résultats les plus pertinents pour éviter le débordement de contexte

​
Pour la recherche de niveau supérieur (Méthode 2)

  • Contenu pré-récupéré : Utilisez quand vous avez déjà des résultats de recherche
  • Traitement par lots : Idéal pour traiter plusieurs résultats de recherche à la fois
  • Tests : Excellent pour tester le comportement de citation avec du contenu connu

​
Meilleures pratiques générales

  1. Structurer les résultats efficacement

    • Utilisez des URL de source claires et permanentes
    • Fournissez des titres descriptifs
    • Divisez le contenu long en blocs de texte logiques

  2. Maintenir la cohérence

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

  3. Gérer les erreurs gracieusement

    def search_with_fallback(query):
    try:
        results = perform_search(query)
        if not results:
            return {"type": "text", "text": "Aucun résultat trouvé."}
        return format_as_search_results(results)
    except Exception as e:
        return {"type": "text", "text": f"Erreur de recherche : {str(e)}"}

​
Limitations

  • Les blocs de contenu de résultats de recherche ne sont disponibles qu’avec l’en-tête bêta
  • Seul le contenu texte est supporté dans les résultats de recherche (pas d’images ou autres médias)
  • Le tableau content doit contenir au moins un bloc de texte