D4 · Prompt Engineering › Cluster 6 · Prefill & Output Control

6.4 · Stop Sequences as Output Control

Cut generation cleanly

CONCEPT A delimiter that ends the turn

stop_sequences is a request parameter: a list of strings that, when Claude is about to generate any of them, cause generation to stop immediately. Where prefill controls where the response starts (6.1–6.3), stop sequences control where it ends. Together they bound the output on both sides.

🔑 The matched stop sequence is not included in the returned text. If you stop on </analysis>, the content ends right before it — you get the inside of the block, not the closing tag.

CONCEPT Reading why it stopped: stop_reason + stop_sequence

Every response carries a stop_reason. When a stop sequence fired, it is "stop_sequence", and a companion field stop_sequence tells you which string matched — useful when you pass several. Always branch on stop_reason; don't assume the response ran to a natural end.

stop_reasonMeaning
end_turnClaude finished naturally
stop_sequenceHit one of your stop_sequences — see stop_sequence for which
max_tokensHit the token cap — output may be truncated
tool_useClaude wants to call a tool
refusalDeclined for safety — check stop_details
The showcase combo: prefill { and stop on }. The response opens as JSON and halts the instant the first object closes — you get exactly one JSON object, no trailing commentary.

DIAGRAM Prefill { + stop on } → one object

flowchart TD START["assistant prefill: '{'"] --> GEN["Claude generates:
"name": "Ada", "id": 7"] GEN --> HIT{"About to emit '}'?"} HIT -->|"yes"| STOP["🟢 STOP before '}'
stop_reason = 'stop_sequence'
stop_sequence = '}'"] HIT -->|"no"| GEN STOP --> REBUILD["Rebuild object:
'{' + content + '}'"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class STOP ok; class REBUILD ok; class HIT gate;

CODE Exactly one JSON object: prefill {, stop }

import anthropic, json
client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=300,
    stop_sequences=["}"],                 # ← halt at the first closing brace
    messages=[
        {"role": "user",      "content": "Return {name, id} for user Ada as JSON."},
        {"role": "assistant", "content": "{"},           # ← force straight into JSON
    ],
)

print(resp.stop_reason)        # 'stop_sequence'
print(resp.stop_sequence)      # '}'  ← which sequence matched

# content excludes both the prefill '{' AND the matched '}' — add both back:
obj = json.loads("{" + resp.content[0].text + "}")
print(obj)                     # {'name': 'Ada', 'id': 7}
Both ends are missing from content: the prefill { was your text, and the stop sequence } is excluded by design. Reconstruct with "{" + text + "}".
⚠️ The prefill half is legacy-model-only (400 on Claude 4.6+). stop_sequences itself is a normal parameter that works everywhere — it's independent of prefill and pairs equally well with Structured Outputs or plain instructions.

TRADE-OFFS Stop sequence vs. max_tokens to end output

✅ Stop sequence

  • Ends on a semantic boundary (a delimiter)
  • stop_reason: "stop_sequence" confirms a clean cut
  • Great for one-object / one-block extraction

⚠️ max_tokens as a cutoff

  • Ends at an arbitrary token — often mid-word
  • stop_reason: "max_tokens" = likely truncated
  • A safety cap, not an output-shaping tool

EXAM TRAPS

Trap: "The stop sequence appears at the end of the output." → It does not — the matched sequence is excluded from content. Add it back if you need a complete structure.
Trap: Confusing stop_reason: "stop_sequence" with "max_tokens". → The first is a clean, intended cut at your delimiter; the second means the token cap was hit and output may be truncated.
Trap: Ignoring the stop_sequence field with multiple sequences. → When you pass several, that field tells you which one fired — you need it to know why generation ended.
Trap: "Stop sequences need prefill." → No. stop_sequences is an independent parameter valid on all models; it just pairs nicely with a prefill for one-object extraction.

PRACTICE

Q1 · With stop_sequences=["}"] and a prefill of {, what's in content?

Only the middle — e.g. "name": "Ada", "id": 7. The prefill { was your own text (not echoed) and the stop sequence } is excluded from the output. Reconstruct valid JSON with "{" + content + "}".

Q2 · How do you tell a clean stop from a truncated one?

Check stop_reason: "stop_sequence" means it halted at your delimiter as intended (and stop_sequence names which one); "max_tokens" means it ran out of token budget and the output may be cut off mid-content.

Q3 · Why pair a stop sequence with a tag prefill like <analysis>?

The prefill makes the response open inside the tag, and a stop sequence of </analysis> ends generation right before the close. You extract exactly one clean block — prefill bounds the start, the stop sequence bounds the end.