MessagesCapacités des modèles

Résultats de recherche

Activez des citations naturelles pour les applications RAG en fournissant des résultats de recherche avec attribution de la source

Les blocs de contenu de résultats de recherche permettent à Claude de citer votre propre contenu de la même manière qu'il cite les résultats de recherche web : chaque citation porte la source et le titre que vous avez fournis. Utilisez-les dans les applications RAG (Retrieval-Augmented Generation, génération augmentée par récupération) où Claude doit attribuer les réponses à vos documents.

Tous les modèles actifs prennent en charge les résultats de recherche avec citations, à l'exception de Claude Haiku 3. Aucun en-tête bêta n'est requis : les résultats de recherche font partie de l'API Messages standard.

Comment ça fonctionne

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

À partir d'appels d'outils : Vos outils personnalisés renvoient des résultats de recherche, permettant des applications RAG dynamiques
En tant que contenu de premier niveau : Vous fournissez les 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 cite automatiquement les résultats de recherche lorsque les citations sont activées. Aucun prompt spécial n'est nécessaire : posez votre question, et les citations apparaissent sur les blocs de texte qui s'appuient sur votre contenu.

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

Champ	Type	Description
`type`	string	Doit être `"search_result"`
`source`	string	La source du contenu. Toute chaîne stable fonctionne : une URL, ou un identifiant interne tel que `kb://article-1234`
`title`	string	Un titre descriptif pour le résultat de recherche
`content`	array	Un tableau de blocs de texte contenant le contenu réel

Champs optionnels

Champ	Type	Description
`citations`	object	Configuration des citations avec le champ booléen `enabled`. Les citations sont désactivées par défaut ; chaque exemple de cette page définit explicitement `"enabled": true`. Tous les résultats de recherche d'une requête doivent utiliser le même paramètre (voir Contrôle des citations)
`cache_control`	object	Paramètres de contrôle du cache (par exemple, `{"type": "ephemeral"}`)

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)

Les résultats de recherche ne contiennent que du texte. Les images et autres médias ne sont pas pris en charge dans le tableau content.

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

Renvoyer des résultats de recherche depuis vos outils personnalisés permet des applications RAG dynamiques : les outils récupèrent le contenu à l'exécution, et Claude le cite dans la réponse. L'exemple suivant force l'appel d'outil avec tool_choice, de sorte que l'étape de récupération s'exécute à chaque fois.

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 bon format
    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},
        ),
    ]


# Construire la conversation dans une liste, en commençant par la question de l'utilisateur
messages = [
    MessageParam(role="user", content="How do I configure the timeout settings?")
]

# Créer un message avec l'outil
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    tool_choice={"type": "tool", "name": "search_knowledge_base"},
    messages=messages,
)

# Lorsque Claude appelle l'outil, fournissez les résultats de recherche.
# Le bloc tool_use n'est pas toujours en premier : itérez pour le trouver.
tool_use = next((block for block in response.content if block.type == "tool_use"), None)
if tool_use is not None:
    tool_result = search_knowledge_base(tool_use.input["query"])

    # Ajouter le tour de Claude, puis le résultat de l'outil, à la conversation en cours
    messages.append(MessageParam(role="assistant", content=response.content))
    messages.append(
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id=tool_use.id,
                    content=tool_result,  # Search results go here
                )
            ],
        )
    )

    # Renvoyer le résultat de l'outil
    final_response = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        messages=messages,
    )
    print(final_response)

Méthode 2 : Résultats de recherche en tant que contenu de premier niveau

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

Le contenu pré-récupéré depuis votre infrastructure de recherche
Les résultats de recherche mis en cache provenant de requêtes précédentes
Le 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-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)

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 provenant de ceux-ci :

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

Champ	Type	Description
`type`	string	Toujours `"search_result_location"` pour les citations de résultats de recherche
`source`	string	La source du résultat de recherche d'origine
`title`	string ou null	Le titre du résultat de recherche d'origine
`cited_text`	string	Le texte complet du ou des blocs cités, concaténés. Égal au contenu de `content[start_block_index:end_block_index]` joint ensemble. Non comptabilisé dans les output tokens.
`search_result_index`	integer	Index basé sur 0 du résultat de recherche cité parmi tous les blocs `search_result` de la requête, dans l'ordre où ils apparaissent (à travers tous les messages et résultats d'outils).
`start_block_index`	integer	Index basé sur 0 du premier bloc cité dans le tableau `content` du résultat de recherche.
`end_block_index`	integer	Index de fin exclusif de la plage de blocs cités dans le tableau `content` du résultat de recherche. Toujours supérieur à `start_block_index`.

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, pas 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."
    }
  ],
  "citations": { "enabled": true }
}

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

{
  "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 de contenu personnalisé dans la fonctionnalité Citations.

Utilisation avancée

Combinaison des deux méthodes

Vous pouvez mélanger les deux méthodes dans la même conversation. Claude cite à partir de l'une ou l'autre source, et search_result_index compte tous les blocs search_result dans l'ordre de la requête, quelle que soit la source.

L'exemple suivant rejoue une conversation complète. Le premier message utilisateur porte un résultat de recherche pré-récupéré, le tour de l'assistant appelle un outil de base de connaissances, et le résultat de l'outil renvoie un second résultat de recherche. La réponse de Claude cite les deux sources :

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

client = Anthropic()

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

# Rejoue une conversation qui fournit des résultats de recherche des deux manières : le premier
# message utilisateur contient un résultat pré-récupéré, le résultat d'outil en renvoie un autre
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/overview",
                    title="Product Overview",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
                        )
                    ],
                    citations={"enabled": True},
                ),
                TextBlockParam(
                    type="text",
                    text="What does Acme Dashboard do, and what plans is it available on?",
                ),
            ],
        ),
        MessageParam(
            role="assistant",
            content=[
                TextBlockParam(
                    type="text", text="Let me check the pricing information."
                ),
                ToolUseBlockParam(
                    type="tool_use",
                    id="toolu_01A09q90qw90lq917835lq9",
                    name="search_knowledge_base",
                    input={"query": "Acme Dashboard pricing plans"},
                ),
            ],
        ),
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id="toolu_01A09q90qw90lq917835lq9",
                    content=[
                        SearchResultBlockParam(
                            type="search_result",
                            source="https://docs.company.com/pricing",
                            title="Pricing Plans",
                            content=[
                                TextBlockParam(
                                    type="text",
                                    text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
                                )
                            ],
                            citations={"enabled": True},
                        )
                    ],
                )
            ],
        ),
    ],
)

print(response)

La réponse cite les deux sources. Le résultat pré-récupéré est search_result_index: 0 et le résultat renvoyé par l'outil est search_result_index: 1, correspondant à l'ordre dans lequel les blocs search_result apparaissent dans la conversation :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's what I found about Acme Dashboard:\n\n**What it does:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
          "source": "https://docs.company.com/overview",
          "title": "Product Overview",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    },
    {
      "type": "text",
      "text": "\n\n**Available plans:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
          "source": "https://docs.company.com/pricing",
          "title": "Pricing Plans",
          "search_result_index": 1,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Mélange avec d'autres types de contenu

Dans les messages utilisateur, les blocs search_result peuvent côtoyer n'importe quel autre bloc de contenu. L'exemple de la Méthode 2 associe des résultats de recherche à une question text, et des blocs d'image ou de document peuvent les rejoindre de la même manière.

Les résultats d'outils sont plus stricts : si un bloc quelconque dans un tableau de contenu tool_result est un search_result, tous ses blocs doivent être des search_result. Mélanger des résultats de recherche avec d'autres types de blocs dans le même résultat d'outil renvoie une erreur de validation. Pour renvoyer du texte d'accompagnement avec des résultats de recherche provenant d'outils, incluez-le en tant que bloc de texte à l'intérieur de l'un des tableaux content des résultats de recherche, où il devient également citable.

Contrôle du cache

Ajoutez cache_control sur le bloc de résultat de recherche pour le mettre en cache en vue d'une réutilisation entre les requêtes. Il se place à côté de citations sur le même bloc :

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

Consultez Mise en cache des prompts pour les longueurs minimales pouvant être mises en cache et les autres exigences.

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 attache des références de citation aux blocs de texte qui s'appuient sur le résultat de recherche.

Bonnes pratiques

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

Contenu dynamique : Utilisez-la 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 : Ne renvoyez que les résultats les plus pertinents pour éviter le débordement du contexte

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

Contenu pré-récupéré : Utilisez-la 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 un contenu connu

Bonnes pratiques générales

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
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
Gérez les erreurs avec élégance : lorsqu'une recherche échoue ou ne renvoie rien, renvoyez un bloc de texte brut décrivant le résultat (par exemple, {"type": "text", "text": "No results found."}) au lieu de lever une erreur : Claude explique le résultat vide à l'utilisateur, et la conversation continue.

Limitations

Les blocs de contenu de résultats de recherche sont disponibles sur l'API Claude, Amazon Bedrock et Google Cloud.
Seul le contenu textuel est pris en charge dans les résultats de recherche (pas d'images ni d'autres médias).
Les blocs search_result ne peuvent apparaître que dans les messages utilisateur (y compris à l'intérieur des résultats d'outils). Les messages de l'assistant contenant des résultats de recherche sont rejetés.
Lorsque l'outil de recherche web est activé dans la même requête, les citations doivent être activées sur tous les blocs search_result.

Prochaines étapes

Refus en streaming

Détectez et gérez les raisons d'arrêt de type refus dans les réponses en streaming, et réessayez les requêtes refusées sur un modèle de repli.

Citations

Ancrez les réponses de Claude dans vos documents sources. Les citations renvoient les passages exacts qui soutiennent chaque affirmation, afin que vous puissiez vérifier les réponses et présenter les sources à vos utilisateurs.

Outil de recherche web

Donnez à Claude l'accès au contenu web actuel avec des sources citées, un filtrage dynamique optionnel et des contrôles de domaine.

Référence de l'API Messages

Consultez la documentation complète de l'API Messages, y compris les types de blocs de contenu.

Mise en cache des prompts

Mettez en cache les résultats de recherche avec cache_control pour réduire le coût et la latence des requêtes répétées.

Was this page helpful?

MessagesCapacités des modèles

Résultats de recherche

Activez des citations naturelles pour les applications RAG en fournissant des résultats de recherche avec attribution de la source

Comment ça fonctionne

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

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

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

Champ	Type	Description
`type`	string	Doit être `"search_result"`
`source`	string	La source du contenu. Toute chaîne stable fonctionne : une URL, ou un identifiant interne tel que `kb://article-1234`
`title`	string	Un titre descriptif pour le résultat de recherche
`content`	array	Un tableau de blocs de texte contenant le contenu réel

Champs optionnels

Champ	Type	Description
`citations`	object	Configuration des citations avec le champ booléen `enabled`. Les citations sont désactivées par défaut ; chaque exemple de cette page définit explicitement `"enabled": true`. Tous les résultats de recherche d'une requête doivent utiliser le même paramètre (voir Contrôle des citations)
`cache_control`	object	Paramètres de contrôle du cache (par exemple, `{"type": "ephemeral"}`)

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)

Les résultats de recherche ne contiennent que du texte. Les images et autres médias ne sont pas pris en charge dans le tableau content.

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

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 bon format
    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},
        ),
    ]


# Construire la conversation dans une liste, en commençant par la question de l'utilisateur
messages = [
    MessageParam(role="user", content="How do I configure the timeout settings?")
]

# Créer un message avec l'outil
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    tool_choice={"type": "tool", "name": "search_knowledge_base"},
    messages=messages,
)

# Lorsque Claude appelle l'outil, fournissez les résultats de recherche.
# Le bloc tool_use n'est pas toujours en premier : itérez pour le trouver.
tool_use = next((block for block in response.content if block.type == "tool_use"), None)
if tool_use is not None:
    tool_result = search_knowledge_base(tool_use.input["query"])

    # Ajouter le tour de Claude, puis le résultat de l'outil, à la conversation en cours
    messages.append(MessageParam(role="assistant", content=response.content))
    messages.append(
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id=tool_use.id,
                    content=tool_result,  # Search results go here
                )
            ],
        )
    )

    # Renvoyer le résultat de l'outil
    final_response = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        messages=messages,
    )
    print(final_response)

Méthode 2 : Résultats de recherche en tant que contenu de premier niveau

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

Le contenu pré-récupéré depuis votre infrastructure de recherche
Les résultats de recherche mis en cache provenant de requêtes précédentes
Le 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-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)

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 provenant de ceux-ci :

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

Champ	Type	Description
`type`	string	Toujours `"search_result_location"` pour les citations de résultats de recherche
`source`	string	La source du résultat de recherche d'origine
`title`	string ou null	Le titre du résultat de recherche d'origine
`cited_text`	string	Le texte complet du ou des blocs cités, concaténés. Égal au contenu de `content[start_block_index:end_block_index]` joint ensemble. Non comptabilisé dans les output tokens.
`search_result_index`	integer	Index basé sur 0 du résultat de recherche cité parmi tous les blocs `search_result` de la requête, dans l'ordre où ils apparaissent (à travers tous les messages et résultats d'outils).
`start_block_index`	integer	Index basé sur 0 du premier bloc cité dans le tableau `content` du résultat de recherche.
`end_block_index`	integer	Index de fin exclusif de la plage de blocs cités dans le tableau `content` du résultat de recherche. Toujours supérieur à `start_block_index`.

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."
    }
  ],
  "citations": { "enabled": true }
}

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

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

Utilisation avancée

Combinaison des deux méthodes

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

client = Anthropic()

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

# Rejoue une conversation qui fournit des résultats de recherche des deux manières : le premier
# message utilisateur contient un résultat pré-récupéré, le résultat d'outil en renvoie un autre
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/overview",
                    title="Product Overview",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
                        )
                    ],
                    citations={"enabled": True},
                ),
                TextBlockParam(
                    type="text",
                    text="What does Acme Dashboard do, and what plans is it available on?",
                ),
            ],
        ),
        MessageParam(
            role="assistant",
            content=[
                TextBlockParam(
                    type="text", text="Let me check the pricing information."
                ),
                ToolUseBlockParam(
                    type="tool_use",
                    id="toolu_01A09q90qw90lq917835lq9",
                    name="search_knowledge_base",
                    input={"query": "Acme Dashboard pricing plans"},
                ),
            ],
        ),
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id="toolu_01A09q90qw90lq917835lq9",
                    content=[
                        SearchResultBlockParam(
                            type="search_result",
                            source="https://docs.company.com/pricing",
                            title="Pricing Plans",
                            content=[
                                TextBlockParam(
                                    type="text",
                                    text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
                                )
                            ],
                            citations={"enabled": True},
                        )
                    ],
                )
            ],
        ),
    ],
)

print(response)

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's what I found about Acme Dashboard:\n\n**What it does:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
          "source": "https://docs.company.com/overview",
          "title": "Product Overview",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    },
    {
      "type": "text",
      "text": "\n\n**Available plans:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
          "source": "https://docs.company.com/pricing",
          "title": "Pricing Plans",
          "search_result_index": 1,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Mélange avec d'autres types de contenu

Contrôle du cache

Ajoutez cache_control sur le bloc de résultat de recherche pour le mettre en cache en vue d'une réutilisation entre les requêtes. Il se place à côté de citations sur le même bloc :

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

Consultez Mise en cache des prompts pour les longueurs minimales pouvant être mises en cache et les autres exigences.

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 attache des références de citation aux blocs de texte qui s'appuient sur le résultat de recherche.

Bonnes pratiques

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

Contenu dynamique : Utilisez-la 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 : Ne renvoyez que les résultats les plus pertinents pour éviter le débordement du contexte

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

Contenu pré-récupéré : Utilisez-la 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 un contenu connu

Bonnes pratiques générales

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
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
Gérez les erreurs avec élégance : lorsqu'une recherche échoue ou ne renvoie rien, renvoyez un bloc de texte brut décrivant le résultat (par exemple, {"type": "text", "text": "No results found."}) au lieu de lever une erreur : Claude explique le résultat vide à l'utilisateur, et la conversation continue.

Limitations

Les blocs de contenu de résultats de recherche sont disponibles sur l'API Claude, Amazon Bedrock et Google Cloud.
Seul le contenu textuel est pris en charge dans les résultats de recherche (pas d'images ni d'autres médias).
Les blocs search_result ne peuvent apparaître que dans les messages utilisateur (y compris à l'intérieur des résultats d'outils). Les messages de l'assistant contenant des résultats de recherche sont rejetés.
Lorsque l'outil de recherche web est activé dans la même requête, les citations doivent être activées sur tous les blocs search_result.

Prochaines étapes

Refus en streaming

Détectez et gérez les raisons d'arrêt de type refus dans les réponses en streaming, et réessayez les requêtes refusées sur un modèle de repli.

Citations

Outil de recherche web

Donnez à Claude l'accès au contenu web actuel avec des sources citées, un filtrage dynamique optionnel et des contrôles de domaine.

Référence de l'API Messages

Consultez la documentation complète de l'API Messages, y compris les types de blocs de contenu.

Mise en cache des prompts

Mettez en cache les résultats de recherche avec cache_control pour réduire le coût et la latence des requêtes répétées.

Was this page helpful?

Comment ça fonctionne

Schéma des résultats de recherche

Champs obligatoires

Champs optionnels

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

Exemple : Outil de base de connaissances

Méthode 2 : Résultats de recherche en tant que contenu de premier niveau

Exemple : Résultats de recherche directs

Réponse de Claude avec citations

Champs de citation

Blocs de contenu multiples

Utilisation avancée

Combinaison des deux méthodes

Mélange avec d'autres types de contenu

Contrôle du cache

Contrôle des citations

Bonnes pratiques

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

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

Bonnes pratiques générales

Limitations

Prochaines étapes

Comment ça fonctionne

Schéma des résultats de recherche

Champs obligatoires

Champs optionnels

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

Exemple : Outil de base de connaissances

Méthode 2 : Résultats de recherche en tant que contenu de premier niveau

Exemple : Résultats de recherche directs

Réponse de Claude avec citations

Champs de citation

Blocs de contenu multiples

Utilisation avancée

Combinaison des deux méthodes

Mélange avec d'autres types de contenu

Contrôle du cache

Contrôle des citations

Bonnes pratiques

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

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

Bonnes pratiques générales

Limitations

Prochaines étapes

Comment ça fonctionne

Schéma des résultats de recherche

Champs obligatoires

Champs optionnels

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

Exemple : Outil de base de connaissances

Méthode 2 : Résultats de recherche en tant que contenu de premier niveau

Exemple : Résultats de recherche directs

Réponse de Claude avec citations

Champs de citation

Blocs de contenu multiples

Utilisation avancée

Combinaison des deux méthodes

Mélange avec d'autres types de contenu

Contrôle du cache

Contrôle des citations

Bonnes pratiques

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

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

Bonnes pratiques générales

Limitations

Prochaines étapes

Comment ça fonctionne

Schéma des résultats de recherche

Champs obligatoires

Champs optionnels

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

Exemple : Outil de base de connaissances

Méthode 2 : Résultats de recherche en tant que contenu de premier niveau

Exemple : Résultats de recherche directs

Réponse de Claude avec citations

Champs de citation

Blocs de contenu multiples

Utilisation avancée

Combinaison des deux méthodes

Mélange avec d'autres types de contenu

Contrôle du cache

Contrôle des citations

Bonnes pratiques

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

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

Bonnes pratiques générales

Limitations

Prochaines étapes