Gérer les refus en streaming

À partir des modèles Claude 4, les réponses en streaming de l'API de Claude renvoient stop_reason : "refusal" lorsque les classificateurs de streaming interviennent pour gérer des violations potentielles des politiques. 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 du contenu qui viole 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 aux côtés de 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 continus.



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",
    ) as stream:
        for event in stream:
            # Vérifier le 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 réessayées sur un autre modèle Claude au lieu de présenter un refus à l'utilisateur
• Utilisez le crédit de repli lors des nouvelles tentatives manuelles : si vous construisez vous-même la nouvelle tentative, transmettez le jeton de crédit de repli du refus afin que la nouvelle tentative ne paie pas deux fois le coût du cache de prompt
• Fournissez des messages personnalisés : créez des messages conviviaux pour une meilleure expérience utilisateur lorsque des refus se produisent
• Suivez les schémas de refus : surveillez la fréquence des refus pour identifier les problèmes potentiels avec vos prompts



Notes de migration

Si vous avez construit la gestion des refus lorsque cette fonctionnalité a été lancée pour la première fois, 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", donc une surveillance basé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.
• Réessayez sur un modèle différent. Renvoyer une requête refusée au même modèle entraîne généralement un autre refus. Au lieu de simplement réinitialiser le contexte, réessayez sur un modèle de repli avec le repli côté serveur, le middleware du SDK, ou une nouvelle tentative manuelle, et utilisez le crédit de repli lorsque vous construisez vous-même la nouvelle tentative.
• Vérifiez les résultats des lots pour les refus. 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", donc effectuez un branchement sur la raison d'arrêt plutôt que sur un comportement spécifique au modèle.



Prochaines étapes