CONCEPT A stop you designed
Unlike the other five stop reasons, stop_sequence is opt-in: it only occurs when
you pass a stop_sequences=[…] parameter. The model generates normally until its output
contains one of your sequences, at which point generation halts and stop_reason == "stop_sequence".
It's a way to impose delimiters or protocol boundaries on the output.
stop_sequence is rare in agents. Agent loops rely on
end_turn/tool_use for control. Reach for stop_sequences only when you need a
hard textual boundary — e.g. stopping at a delimiter you'll parse around.| Aspect | Detail |
|---|---|
| How to enable | Pass stop_sequences=["<<END>>"] (a list) in the request. |
| When it fires | The model's output reaches one of your sequences. |
stop_reason | "stop_sequence" |
| Which one matched | The response reports the matched sequence (e.g. resp.stop_sequence). |
| Typical use | Delimiters, protocol boundaries, cutting off a known section. |
| In agents | Rare — control flow normally comes from end_turn/tool_use. |
DIAGRAM Where stop_sequence fits
a stop sequence?"} B -->|No| C["generates until end_turn / max_tokens / etc."] B -->|Yes| D["🟠 halt generation
stop_reason == stop_sequence"] D --> E["text EXCLUDES the sequence*
resp.stop_sequence = which matched"] E --> F["parse around your delimiter /
protocol boundary"] classDef stop fill:#ffe8cc,stroke:#d9480f,color:#7a2e08; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; class D,E stop; class C ok;
*You supplied the sequence, so you know the boundary to parse around.
CODE Using a stop sequence as a delimiter
# You supply the boundary. Generation halts when the model emits it. resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, stop_sequences=["<<END>>"], # a list of custom boundaries messages=[{"role": "user", "content": "Write the summary, then output <<END>>."}], ) if resp.stop_reason == "stop_sequence": which = resp.stop_sequence # which of your sequences matched summary = resp.content[0].text # text up to (not incl.) the boundary handle_boundary(summary, which) # your protocol parsing
end_turn or request tools.TRADE-OFFS stop_sequence vs. natural end_turn
✅ stop_sequence
- Hard, deterministic textual boundary you control
- Great for delimiters / structured protocol cutoffs
- Stops early — saves tokens past the boundary
⚠️ Costs / caveats
- Rare and easy to over-engineer in agents
- A stray occurrence of the sequence cuts output early
- Adds a branch you must handle distinctly from
end_turn
EXAM TRAPS
stop_sequence without setting stop_sequences. → It
only fires when you supply the parameter. No parameter → you'll never see this reason.stop_sequence with end_turn. → end_turn
is the model finishing naturally; stop_sequence is your custom boundary being hit. Handle
them as separate branches.stop_sequence for agent control flow. → It's rare in
agents; loop control should come from end_turn/tool_use. Use stop sequences for
delimiters, not orchestration.PRACTICE
Q1 · You never set stop_sequences but expect stop_reason == "stop_sequence". Will it happen?
No. stop_sequence only occurs when you pass stop_sequences=[…]. Without
that parameter the model can't stop for that reason.
Q2 · When is a stop sequence the right tool in an agent?
Rarely — mainly for a delimiter or protocol boundary you'll parse around (e.g. cut output
at a fixed marker). Normal agent control flow should come from end_turn and tool_use,
not stop sequences.
Q3 · How do you tell which sequence matched?
Read the matched sequence off the response (e.g. resp.stop_sequence) after confirming
stop_reason == "stop_sequence". That tells you which of your supplied boundaries fired.