Gérer les refus en streaming

À partir des modèles Claude 4, les réponses en « streaming » (streaming) de l'API de Claude renvoient stop_reason: "refusal" lorsque les classificateurs de streaming interviennent pour gérer d'éventuelles violations de politique. Cette fonctionnalité de sécurité aide à maintenir la conformité du contenu pendant le streaming en temps réel.

Format de réponse de l'API

Lorsque les classificateurs de streaming détectent un contenu qui enfreint les politiques d'Anthropic, l'API renvoie cette réponse :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello.."
    }
  ],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  }
}

Dans le flux d'événements, stop_details arrive sur l'événement message_delta en même temps que stop_reason.

Réinitialiser le contexte après un refus

Lorsque vous recevez stop_reason: refusal, vous devez réinitialiser le contexte de la conversation avant de continuer. Vous pouvez supprimer ou reformuler le tour qui a déclenché le refus, ou effacer entièrement l'historique de la conversation. Tenter de continuer sans réinitialiser entraînera des refus répétés.

Guide d'implémentation

Voici comment détecter et gérer les refus en streaming dans votre application :

client = anthropic.Anthropic()
messages = []


def reset_conversation():
    """Reset conversation context after refusal"""
    global messages
    messages = []
    print("Conversation reset due to refusal")


try:
    with client.messages.stream(
        max_tokens=1024,
        messages=messages + [{"role": "user", "content": "Hello"}],
        model="claude-opus-5-5",
    ) as stream:
        for event in stream:
            # Vérifier la présence d'un refus dans le delta du message.
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")

Types de refus actuels

L'API gère actuellement les refus de trois manières différentes :

Bonnes pratiques

• Surveillez les refus : incluez des vérifications de stop_reason: refusal dans votre gestion des erreurs.
• Réinitialisez automatiquement : implémentez une réinitialisation automatique du contexte lorsque des refus sont détectés.
• Repliez-vous sur un autre modèle : configurez le repli côté serveur ou le middleware du SDK afin que les requêtes refusées soient relancées sur un autre modèle Claude au lieu de présenter un refus à l'utilisateur.
• Utilisez le crédit de repli lors des relances manuelles : si vous construisez vous-même la relance, transmettez le jeton de crédit de repli du refus afin que la relance ne paie pas deux fois le coût de la mise en cache des prompts.
• Fournissez des messages personnalisés : créez des messages conviviaux pour une meilleure expérience utilisateur lorsque des refus se produisent.
• Suivez les tendances de refus : surveillez la fréquence des refus pour identifier d'éventuels problèmes avec vos prompts.

Notes de migration

Si vous avez mis en place une gestion des refus lors du lancement initial de cette fonctionnalité, ou si vous l'ajoutez à une intégration existante, vérifiez les points suivants :

• Les refus sont des réponses, pas des erreurs. Un refus arrive sous la forme d'une réponse HTTP 200 réussie avec stop_reason: "refusal", de sorte qu'une surveillance fondée uniquement sur les taux d'erreur ne le fera pas apparaître. Suivez les refus comme un signal à part entière.
• Les refus incluent des détails structurés. Sur chaque modèle, un refus inclut également un objet stop_details qui identifie la catégorie de politique à l'origine du refus. Consultez Refus et repli pour la forme complète de la réponse.
• Relancez sur un autre modèle. Renvoyer une requête refusée au même modèle aboutit généralement à un nouveau refus. Au lieu de seulement réinitialiser le contexte, relancez sur un modèle de repli avec le repli côté serveur, le middleware du SDK ou une relance manuelle, et utilisez le crédit de repli lorsque vous construisez vous-même la relance.
• Vérifiez les refus dans les résultats de lots. Une requête refusée dans un Message Batch est renvoyée comme un résultat réussi avec stop_reason: "refusal", et non comme un résultat en erreur.
• Centralisez la gestion sur stop_reason. L'API continue de consolider la gestion des refus autour de stop_reason: "refusal", effectuez donc votre branchement sur la raison d'arrêt plutôt que sur un comportement propre à un modèle.

Étapes suivantes