D1 · Agentic Architecture › Cluster 2 · Stop Reasons

2.6 · stop_sequence & Custom Protocols

You supply the boundary; the model stops on it

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.
AspectDetail
How to enablePass stop_sequences=["<<END>>"] (a list) in the request.
When it firesThe model's output reaches one of your sequences.
stop_reason"stop_sequence"
Which one matchedThe response reports the matched sequence (e.g. resp.stop_sequence).
Typical useDelimiters, protocol boundaries, cutting off a known section.
In agentsRare — control flow normally comes from end_turn/tool_use.

DIAGRAM Where stop_sequence fits

flowchart TD A([request with stop_sequences=[...]]) --> B{"output contains
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
Use it for machine-parseable boundaries (a fixed delimiter you split on) or to enforce a protocol section end. For ordinary agent control, prefer letting the model reach 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

Trap: Expecting stop_sequence without setting stop_sequences. → It only fires when you supply the parameter. No parameter → you'll never see this reason.
Trap: Confusing 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.
Trap: Relying on 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.