Recusas em streaming

A partir dos modelos Claude 4, as respostas de streaming da API do Claude retornam stop_reason: "refusal" quando classificadores de streaming intervêm para tratar possíveis violações de política. Esse recurso de segurança ajuda a manter a conformidade do conteúdo durante o streaming em tempo real.



Formato de resposta da API

Quando os classificadores de streaming detectam conteúdo que viola as políticas da Anthropic, a API retorna esta resposta:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello.."
    }
  ],
  "stop_reason": "refusal"
}



Redefinir o contexto após uma recusa

Quando você recebe stop_reason: refusal, deve redefinir o contexto da conversa antes de continuar. Você pode remover ou reformular o turno que acionou a recusa, ou limpar completamente o histórico da conversa. Tentar continuar sem redefinir resultará em recusas contínuas.



Guia de implementação

Veja como detectar e tratar recusas de streaming em sua aplicação:

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-4-8",
    ) as stream:
        for event in stream:
            # Verificar recusa no delta da mensagem
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")



Tipos de recusa atuais

A API atualmente trata recusas de três maneiras diferentes:



Práticas recomendadas

• Monitore recusas: Inclua verificações de stop_reason: refusal no seu tratamento de erros
• Redefina automaticamente: Implemente a redefinição automática de contexto quando recusas forem detectadas
• Faça fallback para outro modelo: Configure fallback do lado do servidor ou o middleware do SDK para que solicitações recusadas sejam tentadas novamente em outro modelo Claude em vez de exibir uma recusa ao usuário
• Resgate o crédito de fallback em novas tentativas manuais: Se você mesmo implementar a nova tentativa, passe o token de crédito de fallback da recusa para que a nova tentativa não pague o custo de cache de prompt duas vezes
• Forneça mensagens personalizadas: Crie mensagens amigáveis ao usuário para uma melhor UX quando ocorrerem recusas
• Acompanhe padrões de recusa: Monitore a frequência de recusas para identificar possíveis problemas com seus prompts



Notas de migração

Se você implementou o tratamento de recusas quando esse recurso foi lançado pela primeira vez, ou está adicionando-o a uma integração existente, verifique o seguinte:

• Recusas são respostas, não erros. Uma recusa chega como uma resposta HTTP 200 bem-sucedida com stop_reason: "refusal", portanto, um monitoramento baseado apenas em taxas de erro não a detectará. Acompanhe as recusas como um sinal próprio.
• Modelos mais recentes retornam mais detalhes. No Claude Fable 5, uma recusa também inclui um objeto stop_details que identifica a categoria de política por trás da recusa. Consulte Recusas e fallback para ver o formato completo da resposta.
• Tente novamente em um modelo diferente. Reenviar uma solicitação recusada para o mesmo modelo geralmente resulta em outra recusa. Em vez de apenas redefinir o contexto, tente novamente em um modelo de fallback com fallback do lado do servidor, o middleware do SDK ou uma nova tentativa manual, e resgate o crédito de fallback quando você mesmo implementar a nova tentativa.
• Verifique os resultados de lote em busca de recusas. Uma solicitação recusada em um Message Batch é retornada como um resultado bem-sucedido com stop_reason: "refusal", não como um resultado com erro.
• Centralize o tratamento em stop_reason. A API continua a consolidar o tratamento de recusas em torno de stop_reason: "refusal", portanto, ramifique com base no motivo de parada em vez de em comportamento específico do modelo.



Próximos passos