MessaggiSviluppare con Claude

Motivi di arresto e fallback

Scopri cosa significa ciascun valore di stop_reason e come gestire troncamenti, uso degli strumenti, turni in pausa e rifiuti nella tua applicazione.

Ogni risposta della Messages API include un campo stop_reason che indica perché Claude ha smesso di generare. Controlla questo campo per decidere se utilizzare la risposta così com'è, continuare la conversazione, riprovare o ricorrere a un altro modello come fallback.

Per lo schema completo della risposta, consulta il riferimento della Messages API.

Riferimento rapido

Valore	Quando si verifica	Cosa fare
`end_turn`	Claude ha completato la sua risposta in modo naturale.	Usa la risposta.
`max_tokens`	La risposta ha raggiunto il tuo limite `max_tokens`.	Aumenta `max_tokens` o continua la risposta.
`stop_sequence`	Claude ha emesso una delle tue `stop_sequences`.	Leggi `stop_sequence` per vedere quale è stata attivata.
`tool_use`	Claude sta chiamando uno strumento.	Esegui lo strumento e restituisci il risultato. Una chiamata a uno strumento server a cui manca ancora il blocco di risultato viene completata in una risposta successiva.
`pause_turn`	Un ciclo di strumenti server ha raggiunto il suo limite di iterazioni.	Rinvia il contenuto dell'assistente per continuare.
`refusal`	Claude ha rifiutato di rispondere.	Leggi `stop_details` e riprova su un modello di fallback.
`model_context_window_exceeded`	La risposta ha riempito la finestra di contesto del modello.	Tratta la risposta come troncata.

Il campo stop_reason

Il campo stop_reason fa parte di ogni risposta riuscita della Messages API. A differenza degli errori, che indicano fallimenti nell'elaborazione della tua richiesta, stop_reason ti dice perché Claude ha completato la generazione della sua risposta.

Example response

{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

Valori di stop_reason

end_turn

Il motivo di arresto più comune. Indica che Claude ha completato la sua risposta in modo naturale.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
    # Elabora la risposta completa
    print(response.content[0].text)

max_tokens

Claude si è fermato perché ha raggiunto il limite max_tokens specificato nella tua richiesta.

client = anthropic.Anthropic()
# Richiesta con token limitati
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}],
)

if response.stop_reason == "max_tokens":
    # La risposta è stata troncata
    print("Response was cut off at token limit")
    # Considera di effettuare un'altra richiesta per continuare

stop_sequence

Claude ha incontrato una delle tue sequenze di arresto personalizzate.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    stop_sequences=["END", "STOP"],
    messages=[{"role": "user", "content": "Generate text until you say END"}],
)

if response.stop_reason == "stop_sequence":
    print(f"Stopped at sequence: {response.stop_sequence}")

tool_use

Claude sta chiamando uno strumento e si aspetta che tu lo esegua.

Per la maggior parte delle implementazioni di uso degli strumenti, usa il tool runner, che gestisce automaticamente l'esecuzione degli strumenti, la formattazione dei risultati e la gestione della conversazione.

client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City and state"},
        },
        "required": ["location"],
    },
}


def execute_tool(name, tool_input):
    """Execute a tool and return the result."""
    return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"


response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

if response.stop_reason == "tool_use":
    # Estrai ed esegui lo strumento
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Restituisci il risultato a Claude per la risposta finale

Una risposta tool_use può anche contenere un blocco server_tool_use il cui id non ha un blocco di risultato corrispondente. Quella chiamata allo strumento server non è terminata, e questa risposta non contiene il suo risultato. Nel caso comune, Claude chiama uno strumento server e uno dei tuoi strumenti client nello stesso gruppo di chiamate parallele agli strumenti: l'API restituisce senza eseguire lo strumento server in modo che tu possa eseguire prima gli strumenti client. Non c'è altro indicatore per questo stato; rilevalo controllando l'id di ciascun blocco server_tool_use o mcp_tool_use alla ricerca di un blocco di risultato corrispondente.

Con il programmatic tool calling, la stessa forma di risposta significa qualcosa di diverso. Il blocco tool_use client proviene da codice in esecuzione nello strumento code_execution anziché direttamente da Claude, e il suo campo caller indica il blocco code_execution che lo ha chiamato. Quel codice è già stato avviato: è in pausa in attesa dei tuoi blocchi tool_result, e inviarli riprende l'esecuzione invece di avviare uno strumento differito. Il blocco di risultato del blocco code_execution stesso arriva una volta che il codice termina, il che può richiedere più di un ciclo di risultati degli strumenti. Il messaggio utente di follow-up in sé è lo stesso in entrambi i casi; con il programmatic tool calling, passa anche l'id dal campo container della risposta, come mostrato in quella pagina.

A mixed tool_use response

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_fetch",
      "input": { "url": "https://example.com/article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

La continuazione è un messaggio utente di blocchi tool_result, uno per ogni blocco tool_use nella risposta (vedi Gestire le chiamate agli strumenti), con due regole aggiuntive: quel messaggio non deve contenere nient'altro che i blocchi tool_result, e la richiesta deve mantenere lo stesso array tools. Una richiesta di ripresa che non definisce più lo strumento server in attesa fallisce con un errore 400 il cui messaggio termina con but no `web_fetch` tool was provided. L'API allega i tuoi risultati al turno dell'assistente ancora aperto, esegue lo strumento server differito (per l'esecuzione di codice in pausa, la riprende) e continua il turno. Per uno strumento server chiamato direttamente da Claude, il content della risposta successiva inizia con il blocco di risultato che risponde all'id del server_tool_use della risposta precedente.

The follow-up user message

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

Aggiungere qualsiasi cosa dopo i blocchi tool_result in quel messaggio utente, come del testo, termina il turno dell'assistente; per uno strumento server chiamato direttamente da Claude, la richiesta fallisce quindi con un errore 400 invalid_request_error che indica lo strumento server non risolto:

`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block

Omettere un tool_result, o inserirne uno dopo altro contenuto, fallisce prima con l'errore standard tool_use ids were found without tool_result blocks immediately after. Per fornire a Claude ulteriore input, invialo come messaggio utente separato dopo che il turno è completato.

pause_turn

Restituito quando il ciclo di campionamento lato server raggiunge il suo limite di iterazioni durante l'esecuzione di strumenti server come la ricerca web o il web fetch. Il limite predefinito è di 10 iterazioni per richiesta.

Quando questo accade, la risposta può contenere un blocco server_tool_use senza un blocco di risultato corrispondente. Per permettere a Claude di completare l'elaborazione, continua la conversazione rinviando la risposta così com'è. Una risposta che lascia un blocco tool_use client in attesa di te non ha mai uno stop_reason di pause_turn: quando Claude si ferma per chiamare i tuoi strumenti, stop_reason è tool_use, e la continui inviando i blocchi tool_result client invece della risposta stessa.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Search for latest AI news"}],
)

if response.stop_reason == "pause_turn":
    # Continua la conversazione inviando la risposta indietro
    messages = [
        {"role": "user", "content": "Search for latest AI news"},
        {"role": "assistant", "content": response.content},
    ]
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}],
    )

La tua applicazione dovrebbe gestire pause_turn in qualsiasi ciclo agente che utilizza strumenti server. Aggiungi la risposta dell'assistente al tuo array di messaggi ed effettua un'altra richiesta API per permettere a Claude di continuare.

refusal

Claude ha rifiutato di generare una risposta. Su Claude Fable 5, i classificatori di sicurezza restituiscono questo motivo di arresto come una normale risposta HTTP 200, non come un errore.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}],
)

if response.stop_reason == "refusal":
    # Claude ha rifiutato di rispondere
    print("Claude was unable to process this request")
    # Considera di riformulare o modificare la richiesta

Se incontri frequentemente motivi di arresto refusal mentre usi Claude Sonnet 4.5 o Opus 4.1 (deprecato), puoi provare ad aggiornare le tue chiamate API per usare Haiku 4.5 (claude-haiku-4-5-20251001), che ha restrizioni d'uso diverse. Scopri di più su come comprendere i filtri di sicurezza API di Sonnet 4.5.

In caso di rifiuto, l'oggetto stop_details identifica la categoria di policy che lo ha attivato. Le categorie e la forma completa della risposta di rifiuto sono trattate in Rifiuti e fallback. stop_details è null per tutti i motivi di arresto diversi da refusal.

Una richiesta rifiutata su Claude Fable 5 può solitamente essere servita riprovando su un altro modello Claude, e Rifiuti e fallback mostra come configurare quel nuovo tentativo, lato server o nel tuo client. Credito di fallback spiega come evitare di pagare due volte il costo della cache dei prompt quando costruisci tu stesso il nuovo tentativo.

model_context_window_exceeded

Claude si è fermato perché ha raggiunto il limite della "context window" (finestra di contesto) del modello. Questo ti permette di richiedere il massimo numero possibile di token senza conoscere la dimensione esatta dell'input.

Questo motivo di arresto è attualmente tipizzato solo nel namespace beta degli SDK, quindi gli esempi seguenti chiamano client.beta.messages e usano i tipi con prefisso Beta. Su Sonnet 4.5 e modelli più recenti l'API restituisce questo valore senza un header beta. Per i modelli precedenti, aggiungi l'header beta model-context-window-exceeded-2025-08-26 per abilitarlo.

# Richiesta con il massimo dei token per ottenere il più possibile
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k (Opus 4.8 supports 128k with streaming)
    messages=[
        {"role": "user", "content": "Large input that uses most of context window..."}
    ],
)

if response.stop_reason == "model_context_window_exceeded":
    # La risposta ha raggiunto il limite della finestra di contesto prima di max_tokens
    print("Response reached model's context window limit")
    # La risposta è comunque valida ma è stata limitata dalla finestra di contesto

Best practice per la gestione dei motivi di arresto

Controlla sempre stop_reason

Prendi l'abitudine di controllare stop_reason nella tua logica di gestione delle risposte:

def handle_response(response):
    if response.stop_reason == "tool_use":
        return handle_tool_use(response)
    elif response.stop_reason == "max_tokens":
        return handle_truncation(response)
    elif response.stop_reason == "model_context_window_exceeded":
        return handle_context_limit(response)
    elif response.stop_reason == "pause_turn":
        return handle_pause(response)
    elif response.stop_reason == "refusal":
        return handle_refusal(response)
    else:
        # Gestisci end_turn e altri casi
        return response.content[0].text

Gestisci le risposte troncate in modo elegante

Quando una risposta viene troncata a causa dei limiti di token o della finestra di contesto, aggiungi un avviso in modo che il lettore sappia che l'output è incompleto. Per continuare invece a generare dal punto in cui la risposta si è interrotta, vedi Garantire risposte complete.

def handle_truncated_response(response):
    if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
        if response.stop_reason == "max_tokens":
            note = "[Response truncated due to max_tokens limit]"
        else:
            note = "[Response truncated due to context window limit]"
        return f"{response.content[0].text}\n\n{note}"
    return response.content[0].text

Implementa la logica di retry per pause_turn

Quando usi strumenti server, l'API può restituire pause_turn se il ciclo di campionamento lato server raggiunge il suo limite di iterazioni (predefinito 10). Gestisci questo caso continuando la conversazione:

def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
    """
    Handle server tool conversations that may require multiple continuations.

    The server runs a sampling loop when executing server tools. If the loop
    reaches its iteration limit, the API returns pause_turn. Continue the
    conversation by sending the response back to let Claude finish.
    """
    messages = [{"role": "user", "content": user_query}]

    for _ in range(max_continuations):
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=4096, messages=messages, tools=tools
        )

        if response.stop_reason != "pause_turn":
            # Claude ha terminato l'elaborazione - restituisci la risposta finale
            return response

        # pause_turn: sostituisci l'intero elenco di messaggi per mantenere l'alternanza dei ruoli
        messages = [
            {"role": "user", "content": user_query},
            {"role": "assistant", "content": response.content},
        ]

    # Raggiunto il numero massimo di continuazioni - restituisci l'ultima risposta
    return response

Motivi di arresto vs. errori

È importante distinguere tra i valori di stop_reason e gli errori veri e propri:

Motivi di arresto (risposte riuscite)

Fanno parte del corpo della risposta
Indicano perché la generazione si è fermata normalmente
La risposta contiene contenuto valido

Errori (richieste fallite)

Codici di stato HTTP 4xx o 5xx
Indicano fallimenti nell'elaborazione della richiesta
La risposta contiene i dettagli dell'errore

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    )

    # Gestisci la risposta riuscita con stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Gestisci gli errori effettivi
    if e.status_code == 429:
        print("Rate limit exceeded")
    elif e.status_code == 500:
        print("Server error")

Considerazioni sullo streaming

Quando usi lo streaming, stop_reason è:

null nell'evento iniziale message_start
Fornito nell'evento message_delta
Non fornito in nessun altro evento

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for event in stream:
        if event.type == "message_delta":
            stop_reason = event.delta.stop_reason
            if stop_reason:
                print(f"Stream ended with: {stop_reason}")

Pattern comuni

Gestione dei flussi di lavoro con uso degli strumenti

Più semplice con il tool runner: l'esempio seguente mostra la gestione manuale degli strumenti. Per la maggior parte dei casi d'uso, il tool runner gestisce automaticamente l'esecuzione degli strumenti con molto meno codice.

def complete_tool_workflow(client, user_query, tools):
    messages = [{"role": "user", "content": user_query}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=1024, messages=messages, tools=tools
        )

        if response.stop_reason == "tool_use":
            # Esegui gli strumenti e continua
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Risposta finale
            return response

Garantire risposte complete

def get_complete_response(client, prompt, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    full_response = ""

    for _ in range(max_attempts):
        response = client.messages.create(
            model="claude-opus-4-8", messages=messages, max_tokens=4096
        )

        full_response += response.content[0].text

        if response.stop_reason != "max_tokens":
            break

        # Continua da dove si era interrotto
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Ottenere il massimo dei token senza conoscere la dimensione dell'input

Con il motivo di arresto model_context_window_exceeded, puoi richiedere il massimo numero possibile di token senza calcolare la dimensione dell'input:

def get_max_possible_tokens(client, prompt):
    """
    Get as many tokens as possible within the model's context window
    without needing to calculate input token count
    """
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    )

    if response.stop_reason == "model_context_window_exceeded":
        # Ottenuto il massimo numero possibile di token data la dimensione dell'input
        print(
            f"Generated {response.usage.output_tokens} tokens (context limit reached)"
        )
    elif response.stop_reason == "max_tokens":
        # Ottenuto esattamente il numero di token richiesto
        print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
    else:
        # Completamento naturale
        print(f"Generated {response.usage.output_tokens} tokens (natural completion)")

    return response.content[0].text

Passaggi successivi

Rifiuti e fallback

Riprova le richieste rifiutate su un modello di fallback, lato server o nel tuo client.

Tool Runner (SDK)

Lascia che l'SDK gestisca per te il ciclo tool_use, la formattazione dei risultati e i retry.

Messaggi in streaming

Leggi stop_reason dall'evento message_delta quando usi lo streaming.

Errori

Gestisci gli errori HTTP 4xx e 5xx, che sono distinti dai motivi di arresto.

Was this page helpful?

MessaggiSviluppare con Claude

Motivi di arresto e fallback

Scopri cosa significa ciascun valore di stop_reason e come gestire troncamenti, uso degli strumenti, turni in pausa e rifiuti nella tua applicazione.

Per lo schema completo della risposta, consulta il riferimento della Messages API.

Riferimento rapido

Valore	Quando si verifica	Cosa fare
`end_turn`	Claude ha completato la sua risposta in modo naturale.	Usa la risposta.
`max_tokens`	La risposta ha raggiunto il tuo limite `max_tokens`.	Aumenta `max_tokens` o continua la risposta.
`stop_sequence`	Claude ha emesso una delle tue `stop_sequences`.	Leggi `stop_sequence` per vedere quale è stata attivata.
`tool_use`	Claude sta chiamando uno strumento.	Esegui lo strumento e restituisci il risultato. Una chiamata a uno strumento server a cui manca ancora il blocco di risultato viene completata in una risposta successiva.
`pause_turn`	Un ciclo di strumenti server ha raggiunto il suo limite di iterazioni.	Rinvia il contenuto dell'assistente per continuare.
`refusal`	Claude ha rifiutato di rispondere.	Leggi `stop_details` e riprova su un modello di fallback.
`model_context_window_exceeded`	La risposta ha riempito la finestra di contesto del modello.	Tratta la risposta come troncata.

Il campo stop_reason

Example response

{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

Valori di stop_reason

end_turn

Il motivo di arresto più comune. Indica che Claude ha completato la sua risposta in modo naturale.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
    # Elabora la risposta completa
    print(response.content[0].text)

max_tokens

Claude si è fermato perché ha raggiunto il limite max_tokens specificato nella tua richiesta.

client = anthropic.Anthropic()
# Richiesta con token limitati
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}],
)

if response.stop_reason == "max_tokens":
    # La risposta è stata troncata
    print("Response was cut off at token limit")
    # Considera di effettuare un'altra richiesta per continuare

stop_sequence

Claude ha incontrato una delle tue sequenze di arresto personalizzate.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    stop_sequences=["END", "STOP"],
    messages=[{"role": "user", "content": "Generate text until you say END"}],
)

if response.stop_reason == "stop_sequence":
    print(f"Stopped at sequence: {response.stop_sequence}")

tool_use

Claude sta chiamando uno strumento e si aspetta che tu lo esegua.

client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City and state"},
        },
        "required": ["location"],
    },
}


def execute_tool(name, tool_input):
    """Execute a tool and return the result."""
    return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"


response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

if response.stop_reason == "tool_use":
    # Estrai ed esegui lo strumento
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Restituisci il risultato a Claude per la risposta finale

A mixed tool_use response

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_fetch",
      "input": { "url": "https://example.com/article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

The follow-up user message

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block

pause_turn

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Search for latest AI news"}],
)

if response.stop_reason == "pause_turn":
    # Continua la conversazione inviando la risposta indietro
    messages = [
        {"role": "user", "content": "Search for latest AI news"},
        {"role": "assistant", "content": response.content},
    ]
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}],
    )

refusal

Claude ha rifiutato di generare una risposta. Su Claude Fable 5, i classificatori di sicurezza restituiscono questo motivo di arresto come una normale risposta HTTP 200, non come un errore.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}],
)

if response.stop_reason == "refusal":
    # Claude ha rifiutato di rispondere
    print("Claude was unable to process this request")
    # Considera di riformulare o modificare la richiesta

model_context_window_exceeded

# Richiesta con il massimo dei token per ottenere il più possibile
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k (Opus 4.8 supports 128k with streaming)
    messages=[
        {"role": "user", "content": "Large input that uses most of context window..."}
    ],
)

if response.stop_reason == "model_context_window_exceeded":
    # La risposta ha raggiunto il limite della finestra di contesto prima di max_tokens
    print("Response reached model's context window limit")
    # La risposta è comunque valida ma è stata limitata dalla finestra di contesto

Best practice per la gestione dei motivi di arresto

Controlla sempre stop_reason

Prendi l'abitudine di controllare stop_reason nella tua logica di gestione delle risposte:

def handle_response(response):
    if response.stop_reason == "tool_use":
        return handle_tool_use(response)
    elif response.stop_reason == "max_tokens":
        return handle_truncation(response)
    elif response.stop_reason == "model_context_window_exceeded":
        return handle_context_limit(response)
    elif response.stop_reason == "pause_turn":
        return handle_pause(response)
    elif response.stop_reason == "refusal":
        return handle_refusal(response)
    else:
        # Gestisci end_turn e altri casi
        return response.content[0].text

Gestisci le risposte troncate in modo elegante

def handle_truncated_response(response):
    if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
        if response.stop_reason == "max_tokens":
            note = "[Response truncated due to max_tokens limit]"
        else:
            note = "[Response truncated due to context window limit]"
        return f"{response.content[0].text}\n\n{note}"
    return response.content[0].text

Implementa la logica di retry per pause_turn

def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
    """
    Handle server tool conversations that may require multiple continuations.

    The server runs a sampling loop when executing server tools. If the loop
    reaches its iteration limit, the API returns pause_turn. Continue the
    conversation by sending the response back to let Claude finish.
    """
    messages = [{"role": "user", "content": user_query}]

    for _ in range(max_continuations):
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=4096, messages=messages, tools=tools
        )

        if response.stop_reason != "pause_turn":
            # Claude ha terminato l'elaborazione - restituisci la risposta finale
            return response

        # pause_turn: sostituisci l'intero elenco di messaggi per mantenere l'alternanza dei ruoli
        messages = [
            {"role": "user", "content": user_query},
            {"role": "assistant", "content": response.content},
        ]

    # Raggiunto il numero massimo di continuazioni - restituisci l'ultima risposta
    return response

Motivi di arresto vs. errori

È importante distinguere tra i valori di stop_reason e gli errori veri e propri:

Motivi di arresto (risposte riuscite)

Fanno parte del corpo della risposta
Indicano perché la generazione si è fermata normalmente
La risposta contiene contenuto valido

Errori (richieste fallite)

Codici di stato HTTP 4xx o 5xx
Indicano fallimenti nell'elaborazione della richiesta
La risposta contiene i dettagli dell'errore

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    )

    # Gestisci la risposta riuscita con stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Gestisci gli errori effettivi
    if e.status_code == 429:
        print("Rate limit exceeded")
    elif e.status_code == 500:
        print("Server error")

Considerazioni sullo streaming

Quando usi lo streaming, stop_reason è:

null nell'evento iniziale message_start
Fornito nell'evento message_delta
Non fornito in nessun altro evento

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for event in stream:
        if event.type == "message_delta":
            stop_reason = event.delta.stop_reason
            if stop_reason:
                print(f"Stream ended with: {stop_reason}")

Pattern comuni

Gestione dei flussi di lavoro con uso degli strumenti

def complete_tool_workflow(client, user_query, tools):
    messages = [{"role": "user", "content": user_query}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=1024, messages=messages, tools=tools
        )

        if response.stop_reason == "tool_use":
            # Esegui gli strumenti e continua
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Risposta finale
            return response

Garantire risposte complete

def get_complete_response(client, prompt, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    full_response = ""

    for _ in range(max_attempts):
        response = client.messages.create(
            model="claude-opus-4-8", messages=messages, max_tokens=4096
        )

        full_response += response.content[0].text

        if response.stop_reason != "max_tokens":
            break

        # Continua da dove si era interrotto
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Ottenere il massimo dei token senza conoscere la dimensione dell'input

Con il motivo di arresto model_context_window_exceeded, puoi richiedere il massimo numero possibile di token senza calcolare la dimensione dell'input:

def get_max_possible_tokens(client, prompt):
    """
    Get as many tokens as possible within the model's context window
    without needing to calculate input token count
    """
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    )

    if response.stop_reason == "model_context_window_exceeded":
        # Ottenuto il massimo numero possibile di token data la dimensione dell'input
        print(
            f"Generated {response.usage.output_tokens} tokens (context limit reached)"
        )
    elif response.stop_reason == "max_tokens":
        # Ottenuto esattamente il numero di token richiesto
        print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
    else:
        # Completamento naturale
        print(f"Generated {response.usage.output_tokens} tokens (natural completion)")

    return response.content[0].text

Passaggi successivi

Rifiuti e fallback

Riprova le richieste rifiutate su un modello di fallback, lato server o nel tuo client.

Tool Runner (SDK)

Lascia che l'SDK gestisca per te il ciclo tool_use, la formattazione dei risultati e i retry.

Messaggi in streaming

Leggi stop_reason dall'evento message_delta quando usi lo streaming.

Errori

Gestisci gli errori HTTP 4xx e 5xx, che sono distinti dai motivi di arresto.

Was this page helpful?

Riferimento rapido

Il campo stop_reason

Valori di stop_reason

end_turn

Risposte vuote con end_turn

max_tokens

Blocchi tool_use incompleti

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Best practice per la gestione dei motivi di arresto

Controlla sempre stop_reason

Gestisci le risposte troncate in modo elegante

Implementa la logica di retry per pause_turn

Motivi di arresto vs. errori

Motivi di arresto (risposte riuscite)

Errori (richieste fallite)

Considerazioni sullo streaming

Pattern comuni

Gestione dei flussi di lavoro con uso degli strumenti

Garantire risposte complete

Ottenere il massimo dei token senza conoscere la dimensione dell'input

Passaggi successivi

Riferimento rapido

Il campo stop_reason

Valori di stop_reason

end_turn

Risposte vuote con end_turn

max_tokens

Blocchi tool_use incompleti

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Best practice per la gestione dei motivi di arresto

Controlla sempre stop_reason

Gestisci le risposte troncate in modo elegante

Implementa la logica di retry per pause_turn

Motivi di arresto vs. errori

Motivi di arresto (risposte riuscite)

Errori (richieste fallite)

Considerazioni sullo streaming

Pattern comuni

Gestione dei flussi di lavoro con uso degli strumenti

Garantire risposte complete

Ottenere il massimo dei token senza conoscere la dimensione dell'input

Passaggi successivi

Riferimento rapido

Il campo stop_reason

Valori di stop_reason

end_turn

max_tokens

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Best practice per la gestione dei motivi di arresto

Controlla sempre stop_reason

Gestisci le risposte troncate in modo elegante

Implementa la logica di retry per pause_turn

Motivi di arresto vs. errori

Motivi di arresto (risposte riuscite)

Errori (richieste fallite)

Considerazioni sullo streaming

Pattern comuni

Gestione dei flussi di lavoro con uso degli strumenti

Garantire risposte complete

Ottenere il massimo dei token senza conoscere la dimensione dell'input

Passaggi successivi

Riferimento rapido

Il campo stop_reason

Valori di stop_reason

end_turn

max_tokens

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Best practice per la gestione dei motivi di arresto

Controlla sempre stop_reason

Gestisci le risposte troncate in modo elegante

Implementa la logica di retry per pause_turn

Motivi di arresto vs. errori

Motivi di arresto (risposte riuscite)

Errori (richieste fallite)

Considerazioni sullo streaming

Pattern comuni

Gestione dei flussi di lavoro con uso degli strumenti

Garantire risposte complete

Ottenere il massimo dei token senza conoscere la dimensione dell'input

Passaggi successivi