mid-conversation-system-messages changedbuild-with-claude/mid-conversation-system-messages
Recorded here
Lines+62added
Lines−3removed
From line
2
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits32to this page, all time
## Availability ### API support #### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) #### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) ### Data handling
The whole hunk
from line 2, old and new numbered
/
from line 2
22title: Mid-conversation system messages and tool changes
33url: https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
44description: Change system instructions or tool availability partway through a conversation without invalidating the cached prefix that came before them.
5featureMetadata:
6 status: ga
7 zdr:
8 eligibility: eligible
9 note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Request-shape capability of the Messages API; mid-conversation system messages flow through the standard inference path and nothing is stored server-side after the response.
10 supportedModels:
11 - claude-fable-5-1
12 - claude-mythos-5-1
13 - claude-fable-5
14 - claude-mythos-5
15 - claude-mythos-preview
16 - claude-opus-5-5
17 - claude-opus-5
18 - claude-sonnet-5-5
19 - claude-haiku-5-5
20 - claude-opus-4-8
21 supportedPlatforms:
22 Claude API: ga
23 Claude Platform on AWS: ga
24 Amazon Bedrock: ga
25 Claude Models on Google Cloud (Google managed): ga
526---
627
7<Note>
8 To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
9</Note>
28**API support**: Usage differs by product.
1029
30* **Messages API**: Append a message with `role` `"system"` to `messages` at the point where the instruction starts to apply.
31* **Managed Agents**: Send a `system.message` event. It applies to that turn and all later turns; the agent’s own `system` field cannot change during a session.
32
1133System instructions normally live in the top-level `system` field, ahead of every message in the conversation. That position is great for [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): the system prompt is part of the stable prefix, so subsequent turns hit the cache. It is a poor position for instructions you only discover you need partway through a session, because editing the top-level `system` field changes the very beginning of the prompt and invalidates the cache for everything that follows.
1234
1335Mid-conversation system messages close that gap. You append a `{"role": "system"}` message at the point in the conversation where the new instruction becomes relevant, instead of editing the top-level `system` field. The cached prefix stays the same, so the next request still reads it from cache, and the new instruction is still applied as a system instruction rather than as ordinary user text.
from line 2385
23632385 How `tool_use` and `tool_result` blocks are structured in the `messages` array.
23642386 </Card>
23652387</CardGroup>
2388
2389## Availability
2390
2391Mid-conversation system messages are available on select models and eligible for zero data retention and HIPAA readiness.
2392
2393### API support
2394
2395#### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)
2396
2397* Availability: Available
2398* Usage: Append a message with `role` `"system"` to `messages` at the point where the instruction starts to apply.
2399
2400| Status | Cloud platforms | Models |
2401| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2402| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
2403
2404#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
2405
2406* Availability: Available
2407* Usage: Send a `system.message` event. It applies to that turn and all later turns; the agent’s own `system` field cannot change during a session.
2408
2409| Status | Cloud platforms | Models |
2410| --------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2411| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
2412
2413### Data handling
2414
2415[Data handling overview](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility)
2416
2417| Item | Zero data retention | HIPAA |
2418| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
2419| Status | Eligible (excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Eligible |
2420| Details | Request-shape capability of the Messages API; mid-conversation system messages flow through the standard inference path and nothing is stored server-side after the response. | — |
2421
2422Applicable endpoints:
2423
2424* `/v1/messages` with `role: "system"` messages
23662425
No line in this hunk matches that.