Lidando com razões de parada
Aprenda como lidar adequadamente com diferentes valores de stop_reason na API Messages do Claude para construir aplicações robustas.
Quando você faz uma solicitação para a API Messages, a resposta do Claude inclui um campo stop_reason
que indica por que o modelo parou de gerar sua resposta. Compreender esses valores é crucial para construir aplicações robustas que lidam adequadamente com diferentes tipos de resposta.
Para detalhes sobre stop_reason
na resposta da API, consulte a referência da API Messages.
O que é stop_reason?
O campo stop_reason
faz parte de toda resposta bem-sucedida da API Messages. Ao contrário dos erros, que indicam falhas no processamento de sua solicitação, stop_reason
informa por que o Claude completou com sucesso a geração de sua resposta.
Valores de razão de parada
end_turn
A razão de parada mais comum. Indica que o Claude terminou sua resposta naturalmente.
max_tokens
O Claude parou porque atingiu o limite de max_tokens
especificado em sua solicitação.
stop_sequence
O Claude encontrou uma de suas sequências de parada personalizadas.
tool_use
O Claude está chamando uma ferramenta e espera que você a execute.
pause_turn
Usado com ferramentas de servidor como busca na web quando o Claude precisa pausar uma operação de longa duração.
refusal
O Claude se recusou a gerar uma resposta devido a preocupações de segurança.
Melhores práticas para lidar com razões de parada
1. Sempre verifique stop_reason
Torne um hábito verificar o stop_reason
em sua lógica de tratamento de resposta:
2. Lide com max_tokens graciosamente
Quando uma resposta é truncada devido a limites de token:
3. Implemente lógica de retry para pause_turn
Para ferramentas de servidor que podem pausar:
Razões de parada vs. erros
É importante distinguir entre valores de stop_reason
e erros reais:
Razões de parada (respostas bem-sucedidas)
- Parte do corpo da resposta
- Indicam por que a geração parou normalmente
- A resposta contém conteúdo válido
Erros (solicitações falhadas)
- Códigos de status HTTP 4xx ou 5xx
- Indicam falhas no processamento da solicitação
- A resposta contém detalhes do erro
Considerações sobre streaming
Ao usar streaming, stop_reason
é:
null
no evento inicialmessage_start
- Fornecido no evento
message_delta
- Não fornecido em nenhum outro evento
Padrões comuns
Lidando com fluxos de trabalho de uso de ferramentas
Garantindo respostas completas
Ao lidar adequadamente com valores de stop_reason
, você pode construir aplicações mais robustas que lidam graciosamente com diferentes cenários de resposta e fornecem melhores experiências do usuário.