Lidar com 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 lidar com 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",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  }
}

No fluxo de eventos, stop_details chega no evento message_delta junto com stop_reason.

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 em streaming na 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-5-5",
    ) as stream:
        for event in stream:
            # Verifica se há 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

Atualmente, a API trata recusas de três maneiras diferentes:

Melhores práticas

• 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 o fallback no 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ê construir a nova tentativa por conta própria, passe o token de crédito de fallback da recusa para que a nova tentativa não pague o custo do 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ê construiu 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.
• Recusas incluem detalhes estruturados. Em todos os modelos, 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 no lado do servidor, o middleware do SDK ou uma nova tentativa manual, e resgate o crédito de fallback quando você construir a nova tentativa por conta própria.
• Verifique recusas nos resultados de lotes. 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 faça a ramificação com base no motivo de parada em vez de em comportamentos específicos de modelo.

Próximos passos