按消息设置 effort
使用系统消息在对话中途更改 effort 级别,同时保留提示缓存。
按消息更改 effort 会为对话的后续轮次设置新的 effort 级别,而不会更改请求的顶层值,因此缓存的前缀仍然匹配。
更改 effort 级别
要在对话中途更改级别:
- 在
messages中添加一条role: "system"消息,将content留空,并在output_config.effort中设置新的 effort 级别。 - 发送
mid-conversation-output-config-2026-07-01beta 标头。 - 保持顶层值不变。
以下示例将顶层值保持为 high,并在一次常规的后续交互中降至 low:
# 仅含 effort 的系统消息:新级别从下一个用户轮次起生效。
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: mid-conversation-output-config-2026-07-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"output_config": {"effort": "high"},
"messages": [
{"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
{"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
{"role": "system", "content": [], "output_config": {"effort": "low"}},
{"role": "user", "content": "Summarize the plan in one sentence."}
]
}'
ant beta:messages create \
--beta mid-conversation-output-config-2026-07-01 <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
output_config:
effort: high
messages:
- role: user
content: Plan a migration from SQLite to PostgreSQL in three short steps.
- role: assistant
content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."
# 仅含 effort 的系统消息:新级别从下一个用户轮次起生效。
- role: system
content: []
output_config:
effort: low
- role: user
content: Summarize the plan in one sentence.
YAML
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
output_config={"effort": "high"},
messages=[
{
"role": "user",
"content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
},
{
"role": "assistant",
"content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
},
# 仅含 effort 的系统消息:新级别从下一个用户轮次开始生效。
{"role": "system", "content": [], "output_config": {"effort": "low"}},
{"role": "user", "content": "Summarize the plan in one sentence."},
],
betas=["mid-conversation-output-config-2026-07-01"],
)
for block in response.content:
if block.type == "text":
print(block.text)
const client = new Anthropic();
const response = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
output_config: { effort: "high" },
messages: [
{
role: "user",
content: "Plan a migration from SQLite to PostgreSQL in three short steps."
},
{
role: "assistant",
content:
"1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."
},
// 仅含 effort 的系统消息:新级别从下一个用户轮次起生效。
{ role: "system", content: [], output_config: { effort: "low" } },
{ role: "user", content: "Summarize the plan in one sentence." }
],
betas: ["mid-conversation-output-config-2026-07-01"]
});
for (const block of response.content) {
if (block.type === "text") {
console.log(block.text);
}
}
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
// ...
AnthropicClient client = new();
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
OutputConfig = new() { Effort = Effort.High },
Messages =
[
new BetaUserMessageParam { Content = "Plan a migration from SQLite to PostgreSQL in three short steps." },
new BetaAssistantMessageParam { Content = "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." },
// 仅含 effort 的系统消息:新级别从下一个用户轮次起生效。
new BetaSystemMessageParam
{
Content = new([]),
OutputConfig = new() { Effort = BetaSystemMessageOutputConfigEffort.Low },
},
new BetaUserMessageParam { Content = "Summarize the plan in one sentence." },
],
Betas = [AnthropicBeta.MidConversationOutputConfig2026_07_01],
});
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
OutputConfig: anthropic.BetaOutputConfigParam{
Effort: anthropic.BetaOutputConfigEffortHigh,
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Plan a migration from SQLite to PostgreSQL in three short steps.")),
{OfAssistant: &anthropic.BetaAssistantMessageParam{
Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")},
}},
// 仅含 effort 的系统消息:新级别将从下一个用户轮次起生效。
anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{
Effort: anthropic.BetaSystemMessageOutputConfigEffortLow,
}),
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize the plan in one sentence.")),
},
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMidConversationOutputConfig2026_07_01},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
fmt.Println(textBlock.Text)
}
}
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaOutputConfig;
import com.anthropic.models.beta.messages.BetaSystemMessageOutputConfig;
import com.anthropic.models.beta.messages.BetaSystemMessageParam;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addBeta(AnthropicBeta.MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01)
.outputConfig(BetaOutputConfig.builder()
.effort(BetaOutputConfig.Effort.HIGH)
.build())
.addUserMessage("Plan a migration from SQLite to PostgreSQL in three short steps.")
.addAssistantMessage("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")
// 仅含 effort 的系统消息:新级别从下一个用户轮次起生效。
.addMessage(BetaSystemMessageParam.builder()
.contentOfBlocks(List.of())
.outputConfig(BetaSystemMessageOutputConfig.builder()
.effort(BetaSystemMessageOutputConfig.Effort.LOW)
.build())
.build())
.addUserMessage("Summarize the plan in one sentence.")
.build();
BetaMessage response = client.beta().messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaMessageParam;
use Anthropic\Beta\Messages\BetaOutputConfig;
use Anthropic\Beta\Messages\BetaSystemMessageOutputConfig;
use Anthropic\Beta\Messages\BetaTextBlock;
// ...
$client = new Client();
$response = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 4096,
outputConfig: BetaOutputConfig::with(effort: 'high'),
messages: [
BetaMessageParam::with(role: 'user', content: 'Plan a migration from SQLite to PostgreSQL in three short steps.'),
BetaMessageParam::with(role: 'assistant', content: '1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.'),
// 仅含 effort 的系统消息:新级别从下一个用户轮次开始生效。
BetaMessageParam::with(
role: 'system',
content: [],
outputConfig: BetaSystemMessageOutputConfig::with(effort: 'low'),
),
BetaMessageParam::with(role: 'user', content: 'Summarize the plan in one sentence.'),
],
betas: [AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01],
);
foreach ($response->content as $block) {
if ($block instanceof BetaTextBlock) {
echo $block->text, PHP_EOL;
}
}
client = Anthropic::Client.new
response = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
output_config: { effort: :high },
messages: [
{ role: "user", content: "Plan a migration from SQLite to PostgreSQL in three short steps." },
{ role: "assistant", content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." },
# 仅含 effort 的系统消息:新级别从下一个用户轮次开始生效。
{ role: "system", content: [], output_config: { effort: :low } },
{ role: "user", content: "Summarize the plan in one sentence." }
],
betas: [Anthropic::AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01]
)
response.content.each do |block|
case block
when Anthropic::Beta::BetaTextBlock
puts block.text
end
end
该消息的位置决定新级别何时开始生效:
- 紧跟在包含新输入的
user轮次之后:Claude 对该轮次的回复会使用新的级别。 - 在其他任何位置,例如前面示例中那样位于一个
assistant轮次与下一个user轮次之间:新的级别从下一个包含新输入的user轮次开始生效。
仅包含 tool_result 块的 user 轮次不算新输入。
新的级别会一直有效,直到后续消息更改它为止。
请将该消息放在您已发送的所有内容之后,并在后续请求中将其保留在原位。不要将其插入到您已发送的轮次之前,之后也不要移动或删除它。在支持 preserved thinking(保留思考)的模型上,任何此类更改都会使该消息之后 assistant 轮次中的思考块失效。有关接下来会发生什么,请参阅设置 prefix_mismatch_behavior。
如果它与一条有内容的 system 消息相邻,则两条消息都必须遵循对话中途系统消息的放置规则。
使用 Amazon Bedrock InvokeModel API 时,请在请求体的 anthropic_beta 数组中发送 beta 值,而不是通过标头发送。有关在该平台上支持按消息设置 effort 的模型,请参阅 Bedrock 上的对话中系统消息。
错误
- 如果没有 beta 标头,按消息设置的
output_config会返回 400 错误:messages.N.output_config: Extra inputs are not permitted,其中N是该system消息在messages中的索引。 - 如果带有 beta 标头,不支持按消息设置 effort 的模型(例如 Claude Fable 5)会返回 400 错误:
output_config.effort requires a model that supports per-turn effort; this model does not。在 Amazon Bedrock 上,这些模型以及 Claude Opus 5 则会返回Extra inputs are not permitted。 - 在使用
thinking: {"type": "between_tools"}的 Claude Sonnet 5.5 以及使用thinking: {"type": "disabled"}的 Claude Haiku 5.5 上,effort 级别无法在对话中途更改。在这些情况下,带有新级别的按消息设置的output_config.effort会返回 400 错误。要为每个轮次设置不同的 effort,请使用 adaptive thinking(自适应思考)。
按消息设置还是顶层设置 effort
相比在请求之间更改顶层值,建议优先使用按消息设置 effort。按消息更改不会影响其之前的所有内容,因此缓存的前缀仍然匹配。更改顶层值可能会使全部或部分缓存失效。在 Claude Fable 5.1 上,更改顶层值对模型的引导效果也不太可靠。模型之前的回复是在先前级别下生成的,它往往会与这些回复保持一致。
可用性
按消息设置 effort在部分模型上处于 beta 阶段。
API 支持
Messages API
- 可用性:可用
- 在请求正文的
anthropic_beta数组中发送 beta 值。
Managed Agents
- 可用性:不可用
- 用法:改为通过覆盖智能体的模型设置来为会话设置 effort。
所需的 beta 请求头
Beta 请求头让您可以在实验性功能和新模型能力成为标准 API 的一部分之前访问它们。
mid-conversation-output-config-2026-07-01