mid-conversation-system-messages changedbuild-with-claude/mid-conversation-system-messages
Nearest release: v2.1.309, published an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+35added
Lines−41removed
From line
13
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits27to this page, all time
The whole hunk
from line 13, old and new numbered
/
from line 13
1313Mid-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.
1414
1515<Note>
16 Mid-conversation system messages are available on the Claude API, [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai).
16 Mid-conversation system messages are available on the Claude API, [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed).
1717
1818 This feature is available on Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. No beta header is required for mid-conversation system messages. This feature is not available on Claude Sonnet 5. Use the top-level `system` field there instead.
1919
20 [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta on the same models. On the Claude API, send the `inline-tools-2026-09-15` beta header, which also covers [defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta). [Adding an MCP server that way](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta) needs a second beta header, `mcp-client-2026-09-15`, which is available on the Claude API. The `mid-conversation-tool-changes-2026-07-01` header works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, and Google Cloud.
20 [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta on the same models. On the Claude API, send the `inline-tools-2026-09-15` beta header, which also covers [defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta). [Adding an MCP server that way](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta) needs a second beta header, `mcp-client-2026-09-15`, which is available on the Claude API. The `mid-conversation-tool-changes-2026-07-01` header works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, and Claude Models on Google Cloud (Google managed).
2121
2222 [Turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at`) are in beta and require the `mid-conversation-system-clear-at-2026-08-21` beta header, on the same models and platforms as mid-conversation system messages.
2323</Note>
from line 283
283283 // Withdraw get_weather from this point onward. The block references
284284 // the tool by name instead of editing Tools, so earlier turns stay
285285 // byte-identical and the cache still hits.
286 {OfSystem: &anthropic.BetaSystemMessageParam{
287 Content: []anthropic.BetaSystemMessageParamContentUnion{{
288 OfToolRemoval: &anthropic.BetaRequestToolRemovalBlockParam{
289 Tool: anthropic.BetaRequestToolRemovalBlockToolUnionParam{
290 OfToolReference: &anthropic.BetaToolChangeToolReferenceParam{
291 Name: "get_weather",
292 },
286 anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{}, anthropic.BetaSystemMessageParamContentUnion{
287 OfToolRemoval: &anthropic.BetaRequestToolRemovalBlockParam{
288 Tool: anthropic.BetaRequestToolRemovalBlockToolUnionParam{
289 OfToolReference: &anthropic.BetaToolChangeToolReferenceParam{
290 Name: "get_weather",
293291 },
294292 },
295 }},
296 }},
293 },
294 }),
297295 },
298296 })
299297 if err != nil {
from line 783
785783 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("How many orders shipped yesterday?")),
786784 // Define db_query by value from this point onward. Tools and the
787785 // earlier messages stay exactly as sent, so the cache still hits.
788 {OfSystem: &anthropic.BetaSystemMessageParam{
789 Content: []anthropic.BetaSystemMessageParamContentUnion{{
790 OfToolAddition: &anthropic.BetaRequestToolAdditionBlockParam{
791 Tool: anthropic.BetaRequestToolAdditionBlockToolUnionParam{
792 OfToolDefinition: &anthropic.BetaToolChangeToolDefinitionParam{
793 Definition: anthropic.BetaToolUnionParam{OfTool: &anthropic.BetaToolParam{
794 Name: "db_query",
795 Description: anthropic.String("Run a read-only SQL query against the analytics database."),
796 InputSchema: anthropic.BetaToolInputSchemaParam{
797 Properties: map[string]any{
798 "sql": map[string]any{"type": "string"},
799 },
800 Required: []string{"sql"},
786 anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{}, anthropic.BetaSystemMessageParamContentUnion{
787 OfToolAddition: &anthropic.BetaRequestToolAdditionBlockParam{
788 Tool: anthropic.BetaRequestToolAdditionBlockToolUnionParam{
789 OfToolDefinition: &anthropic.BetaToolChangeToolDefinitionParam{
790 Definition: anthropic.BetaToolUnionParam{OfTool: &anthropic.BetaToolParam{
791 Name: "db_query",
792 Description: anthropic.String("Run a read-only SQL query against the analytics database."),
793 InputSchema: anthropic.BetaToolInputSchemaParam{
794 Properties: map[string]any{
795 "sql": map[string]any{"type": "string"},
801796 },
802 }},
803 },
797 Required: []string{"sql"},
798 },
799 }},
804800 },
805801 },
806 }},
807 }},
802 },
803 }),
808804 },
809805 })
810806 if err != nil {
from line 1368
13721368 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's on my calendar tomorrow?")),
13731369 // Make the calendar server's tools available from this point onward.
13741370 // The block names the server; it never holds a URL or token.
1375 {OfSystem: &anthropic.BetaSystemMessageParam{
1376 Content: []anthropic.BetaSystemMessageParamContentUnion{{
1377 OfToolAddition: &anthropic.BetaRequestToolAdditionBlockParam{
1378 Tool: anthropic.BetaRequestToolAdditionBlockToolUnionParam{
1379 OfToolDefinition: &anthropic.BetaToolChangeToolDefinitionParam{
1380 Definition: anthropic.BetaToolUnionParam{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
1381 MCPServerName: "calendar",
1382 }},
1383 },
1371 anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{}, anthropic.BetaSystemMessageParamContentUnion{
1372 OfToolAddition: &anthropic.BetaRequestToolAdditionBlockParam{
1373 Tool: anthropic.BetaRequestToolAdditionBlockToolUnionParam{
1374 OfToolDefinition: &anthropic.BetaToolChangeToolDefinitionParam{
1375 Definition: anthropic.BetaToolUnionParam{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
1376 MCPServerName: "calendar",
1377 }},
13841378 },
13851379 },
1386 }},
1387 }},
1380 },
1381 }),
13881382 },
13891383 })
13901384 if err != nil {
from line 1637
16431637
16441638You can still set the top-level `system` field for instructions that should apply to the entire conversation. Reserve mid-conversation system messages for instructions that only become relevant later, or that you want to add without invalidating the cached prefix.
16451639
1646A `role: "system"` message can also carry `output_config.effort` to change the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level partway through a conversation. This is in beta on Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5 on the Claude API and Google Cloud, and requires the `mid-conversation-output-config-2026-07-01` beta header. On Amazon Bedrock, it's in beta on Claude Fable 5.1, Claude Mythos 5.1, and Claude Opus 5.5, with the same beta value. Claude Opus 5 doesn't support it on Amazon Bedrock. See [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta).
1640A `role: "system"` message can also carry `output_config.effort` to change the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level partway through a conversation. This is in beta on Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5 on the Claude API and Claude Models on Google Cloud (Google managed), and requires the `mid-conversation-output-config-2026-07-01` beta header. On Amazon Bedrock, it's in beta on Claude Fable 5.1, Claude Mythos 5.1, and Claude Opus 5.5, with the same beta value. Claude Opus 5 doesn't support it on Amazon Bedrock. See [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta).
16471641
16481642<CodeGroup>
16491643 ```bash cURL
from line 2094
21002094messages.3.content.0: cache_control is not permitted on a turn-scoped system message (clear_at: 'next_user_message')
21012095```
21022096
2103The first is the error returned without the beta header. On Google Cloud and [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), send the beta value in the `anthropic-beta` header, as on the Claude API (see [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)). With the Amazon Bedrock [InvokeModel API](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), put it in the `anthropic_beta` array of the request body instead.
2097The first is the error returned without the beta header. On Claude Models on Google Cloud (Google managed) and [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), send the beta value in the `anthropic-beta` header, as on the Claude API (see [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)). With the Amazon Bedrock [InvokeModel API](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), put it in the `anthropic_beta` array of the request body instead.
21042098
21052099Through the SDK, set `clear_at` (csharp, go: `ClearAt`; java: `.clearAt()`; php: `clearAt`) on the `role: "system"` entry in `messages` and send the beta header. The following example appends a turn-scoped reminder after the user turn; on the next request, once a later user message exists, the reminder stays in the array but no longer renders:
21062100
No line in this hunk matches that.