你让 AI Agent 连夜迁移一个代码库。第二天一早,满怀期待地打开终端,没想到只看到这样一条消息:
已完成 3 个接口迁移,接下来我将处理剩余两个端点,并补上测试。
然后,就没有下文了。想让它干完剩下的活,你还得再敲两个字:继续。本以为它会一口气干到底,结果它只给你画了张「下一步」的饼,程序就替它打卡下班了。这不是某一个人的倒霉经历。
Opus 5.5 一发布,跑 Agent 的开发者就发现,模型能力是强了,可干着干着就爱停下来,你不催它就不动。
Anthropic 自己也看到了。发布没几天,配套的提示词指南已经挂了出来,专门给这类毛病打补丁。
在开篇的排查清单里,官方直接点名了这种「半路溜号」:
无人值守的 Agent 汇报完进度,直接停在了半路。
背后的原因,你可能想不到:Opus 5.5 太爱汇报了。
干长活时,它会主动向你同步进度。难题是,有些汇报发完,它就不再动手了,API 给出的信号是 end_turn,意思是「这一轮我说完了」。
可不少沿用旧逻辑的 Agent 程序只认一条死规矩:模型不再调用工具,就算活干完了。
一份进度汇报,就这样被当成了交差。
这一点,官方指南说得也很清楚:
纯文本的回合结束,应该看作一份汇报,绝不能当作任务完成的凭证。
所以,真正的难题是,AI 压根没想偷懒,是你的程序先替它打了下班卡。
害人的优等生习惯
官方把这种半路停工归结成了四种情况,只要你经常跑 Agent,大概率都遇到过。
第一种,纸上谈兵。
写了一大长篇总结,结尾宣布下一步要做什么,却压根没调用任何工具,下一步永远停在口头上。
第二种,过分礼貌。
干着干着,突然停下来问一句「如果您不介意,我接下来继续处理某某」,然后原地挂机,等你这个根本不在电脑前的人去回复它。
第三种,假装请示。
列出一大串需要你拍板的决策项,但实际上按它自己的说法,这些决策根本不影响它继续干剩下的活。
第四种,汇报强迫症。
模型觉得当前回合字数够多了,或者刚好做完一个小阶段,非得停下来向你做个总结。
有点讽刺的是,在 Opus 5.5 的官方宣传里,「沟通更主动、总结更清楚」恰恰是它的核心卖点。
谁能想到,这些优等生的好习惯,一放进旧的无人值守程序里,反倒成了停工的诱因。
官方三招:把验收权从 AI 手里拿回来
怎么让它接着干,又不至于陷入无限死循环?
官方给出了三招。
第一招,任务清单。
把大任务拆成细项,交给待办工具或文本去维护,让模型边做边勾选。
回合结束时,如果清单上还有没做完的任务,模型也没解释被什么卡住了,你的应用就得自动发条消息,点名让它接着干。
官方给出的续跑示例:「你的任务清单还有未完成项:迁移剩下两个端点,并更新它们的测试。继续做。如果哪项被卡住,说明卡在哪里。」
第二招,铁面验收员。
事先定好完成的标准。每次回合结束,甩给一个更小的模型去对照检查。没达标?把没达标的原因当成下一条消息再塞给它,让它返工。
第三招,硬刹车。
同一个任务如果自动续跑两三次还卡在原地,必须强制停下来交给人复查。真卡死的任务,千万别让它把你的 API 额度空转烧光。
除此之外,提示词也得跟上。
官方给了一段可以直接抄的平台提示词,说白了就是两头堵:
既要明说绝对不想要上述四种停法,也要说清楚什么时候才准停,例如离了使用者真推不下去,或者碰到了被刻意保护的核心资源。
旧代码为什么突然报 400 错误?
如果说干一半停工只是磨洋工,那下面这些迁移陷阱就是直接让程序崩溃了。
从 Opus 5 切换到 Opus 5.5,有四处 API 改动。原来给 Opus 5 写的请求,不改就发给新模型,会被直接拒绝,返回 400 错误。
1.thinking 参数不能再关了。
如果你把 thinking 设为 disabled,或者手工指定了 budget_tokens,平台会直接拒绝请求。要么别传 thinking 字段,要么设为 adaptive,让 effort 参数来控制思考深度。
2.tool_choice 不能再强制调用工具。
把 tool_choice 设为 any 或者指定某一个 tool,都会报 400。官方建议用 auto,配合严格工具调用或结构化输出,再在提示词里说清什么时候用哪个工具。
3.thinking 块绑定了模型和上下文。
2026 年 8 月 31 日之后创建的账户,中途改了平台提示词、工具或历史消息,再回放旧的 thinking 块,默认会直接报错。只追加、不改写的用法不受影响。
4.旧版电脑操作工具下线。
在 Claude API 和 Google Cloud 上,要换成 computer_toolset_20260801。Amazon Bedrock 上,旧的 computer_20251124 照样能用。
还有那些不报错的暗坑。
第一个,看不见干活过程。
在 Opus 5 上,模型在两次工具调用之间写的进度文字,是普通的正文(text 块)。
到了 Opus 5.5,这些文字被挪进了思考块(thinking 块),而思考块默认不表明内容(display 为 omitted),返回时是空的。
如果你的界面只表明正文,长任务跑起来就是一片安静。请求一个都没失败,使用者却以为它卡死了。
解法是把 display 设为 updates(beta),只拿进度摘要;或者设为 summarized,进度和推理摘要一起返回。
第二个,回答被截断。
max_tokens 管的是思考加正文的总量。过去关掉思考时定的上限,现在可能不够用,回答写到一半就断了。
第三个,看不见推理,照样烧 token。
思考内容就算不返回给你,也照样按输出 token 计费。
处理返回结果的代码里,还有两个地方容易忘了改。
一是读结果时要分清类型。模型返回的内容里,思考和正文是分开的,别想当然地把第一段当成回答。
二是来回调用工具时,模型的思考记录要原封不动地传回去。删掉一段、改几个字、调换一下顺序,都会被拒。
这份清单针对的是自己调用 Messages API 写代码的开发者。
用 Claude Managed Agents 的,只需要改个模型名。
同样的 medium 档,已经不是当年的味道
既然思考关不掉,effort 就成了调控成本唯一的旋钮。
Opus 5.5 兼容从 low 到 max 五档。
官方说,现在开 medium 档,就能追平甚至超越以前 Opus 5 的 high 档,如果是 low 档处理简单任务,成本更是低得惊人。
听着像白捡的便宜,但官方立刻补了一句:在同一个档位下,Opus 5.5 每回合的思考量比 Opus 5 大得多,尤其是高档位。
也就是说,如果你把旧项目的 high 档原封不动搬过来,不仅回合变长,输出的 token 数也会狂飙。
同样叫 high,它想的东西已经完全不一样了。
一个接地气的建议是:从 medium 起步,用你自己的数据跑跑看,确实需要提智商的地方再往上调。
如果想让它少琢磨点,直接降档,这比你在提示词里苦口婆心地喊「别想太多」要管用得多。
消除 AI 味,全靠拉黑名单
最后,指南里还有个做前端页面的绝招。
如果你不给明确的外观方向,让模型自己发挥,它多半会搞出那种千篇一律的 AI 风界面。
这时候你如果在提示词里写「请避免通用的 AI 感」,它只会从一套 AI 模板换到另一套 AI 模板。
真正有效的办法,是直接拉黑名单。
官方示范里直接列出:不要奶油色或灰白背景,不要标题里的斜体强调词,不要 01/02 这种章节编号,不要等宽字体标签,不要胶囊形按钮。
模型能听懂具体的「我不要什么」,但听不懂抽象的「我要好看一点」。
翻完这份官方指南,最大的感触是:
模型一路狂奔,很多应用的脚手架却还停在上一代。
过去怕它不动脑,逼着它把推理一步步写出来,现在反倒得劝它少想点;过去费尽心思让它按时汇报,现在它汇报得太勤快,活儿反倒停在了半路。
一个 Agent 能不能把活干完,模型能力只占一半。另一半,看你怎么定义「完成」,怎么保存上下文,怎么分配推理预算。
下次你的 Agent 再干到一半就溜,别急着骂它偷懒,先回头翻翻你自己写的那段循环。
参考资料:
本文来源:https://www.ithome.com/1/007/442.htm
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
You asked an AI Agent to migrate a codebase overnight. The next morning, you eagerly opened the terminal, only to see this message:
"Completed migration of 3 interfaces. Next, I will handle the remaining two endpoints and add tests."
And then... nothing more. To get it to finish the rest, you have to type two more characters: "Continue." You expected it to work in one go, but instead it just drew you a "next steps" pie and clocked out on your behalf. This isn't just one person's bad luck.
As soon as Opus 5.5 was released, developers running Agents noticed that the model is more capable, but it loves to stop mid-task. If you don't nudge it, it won't move.
Anthropic saw this too. Just a few days after release, a companion prompt guide was posted, specifically patching this kind of issue.
In the opening troubleshooting checklist, the official guide directly calls out this "bailing halfway" behavior:
An unattended Agent reports its progress and then stops right in the middle.
The reason behind it might surprise you: Opus 5.5 loves reporting too much.
When working on long tasks, it proactively syncs progress with you. The problem is, after some reports, it stops acting. The API signal is `end_turn`, meaning "I'm done talking for this round."
But many Agent programs still running old logic only obey one strict rule: if the model stops calling tools, the task is done.
A progress report is thus mistaken for the final delivered work.
The official guide states this very clearly:
"A pure-text turn end should be treated as a report, never as proof of task completion."
So the real problem is that the AI never intended to slack off; it was your program that clocked out for it.
The Harmful "Good Student" Habit
The official guide categorizes this mid-task stoppage into four situations. If you run Agents often, you've likely encountered all of them.
First: talking without doing.
It writes a long summary, announces at the end what it will do next, but never actually calls any tool. The "next step" stays forever in words.
Second: over-politeness.
Midway through, it suddenly stops and asks, "If you don't mind, I'll continue with so-and-so next," then idles in place waiting for you—someone who isn't even at the computer—to reply.
Third: fake requests for approval.
It lists a bunch of decisions that supposedly need your sign-off, but by its own admission, these decisions don't actually affect its ability to continue the remaining work.
Fourth: reporting compulsion.
The model thinks the current turn has enough tokens, or it just completed a small milestone, so it insists on giving you a summary.
Ironically, in Opus 5.5's official marketing, "more proactive communication and clearer summaries" is exactly its core selling point.
Who would've thought these "good student" habits, when plugged into old unattended programs, would become the trigger for stoppage?
Official Three Moves: Take Back the Acceptance Power from the AI
How do you get it to keep going, without falling into an infinite loop?
The official guide offers three moves.
Move one: task checklist.
Break the big task into small items, maintain them via a todo tool or text, and let the model check them off as it works.
At the end of a turn, if there are still unfinished items on the checklist and the model hasn't explained what's blocking it, your app should automatically send a message naming the unfinished items and tell it to continue.
The official example for resuming: "Your task checklist still has incomplete items: migrate the remaining two endpoints and update their tests. Continue. If any item is blocked, explain where it's blocked."
Move two: a strict acceptance reviewer.
Define completion criteria in advance. At the end of each turn, feed the result to a smaller model to check against those criteria. Not meeting them? Send the reasons for non-compliance back as the next message and make it redo the work.
Move three: hard stop.
If the same task automatically resumes two or three times and still stalls, you must force a stop and hand it to a human for review. If a task is truly stuck, don't let it burn through your API quota for nothing.
In addition, your prompts need to keep up.
The official guide provides a ready-to-copy system prompt that essentially blocks both ends:
It must clearly state that the four stopping behaviors above are absolutely not allowed, and also clarify when it is allowed to stop—e.g., when the user is genuinely needed to proceed, or when it touches a deliberately protected core resource.
Why is old code suddenly throwing 400 errors?
If stopping halfway is just slow-walking, then these migration pitfalls directly crash your program.
Switching from Opus 5 to Opus 5.5 involves four API changes. Requests written for Opus 5, if sent unchanged to the new model, will be rejected outright with a 400 error.
1. The `thinking` parameter can no longer be turned off.
If you set `thinking` to `disabled`, or manually specify `budget_tokens`, the platform will reject the request. Either omit the `thinking` field entirely, or set it to `adaptive` and let the `effort` parameter control the depth of thinking.
2. `tool_choice` can no longer force tool invocation.
Setting `tool_choice` to `any` or specifying a specific tool will both result in a 400 error. The official recommendation is to use `auto`, combined with strict tool calling or structured output, and then describe in the prompt when to use which tool.
3. `thinking` blocks are bound to the model and context.
For accounts created after August 31, 2026, if you modify the system prompt, tools, or history messages mid-turn, replaying old `thinking` blocks will by default throw an error. The append-only usage (adding new content without rewriting old content) is unaffected.
4. The old computer-use tool is retired.
On Claude API and Google Cloud, switch to `computer_toolset_20260801`. On Amazon Bedrock, the old `computer_20251124` still works.
There are also hidden pitfalls that don't throw errors.
First: you can't see the work in progress.
On Opus 5, the progress text the model writes between two tool calls is ordinary text blocks.
On Opus 5.5, these texts are moved into `thinking` blocks, and by default the thinking blocks don't display content (`display` is `omitted`), so they come back empty.
If your UI only shows text blocks, a long task running looks like complete silence. Every request succeeds, but the user thinks it's hung.
The fix is to set `display` to `updates` (beta) to get only progress summaries; or set it to `summarized` to get both progress and reasoning summaries.
Second: responses get truncated.
`max_tokens` controls the total of thinking plus text. Limits you set when thinking was disabled may now be insufficient, causing responses to cut off mid-sentence.
Third: invisible reasoning still burns tokens.
Even if the thinking content isn't returned to you, it's still billed as output tokens.
In the code that handles returned results, there are two more places easy to forget to update.
One: when reading the result, you need to distinguish types. In the model's returned content, thinking and text are separate. Don't assume the first segment is the answer.
Two: during back-and-forth tool calls, the model's thinking record must be passed back exactly as-is. Deleting a segment, changing a few characters, or reordering will result in rejection.
This checklist is for developers who call the Messages API directly and write their own code.
If you use Claude Managed Agents, you just need to change the model name.
The same "medium" tier is no longer what it used to be.
Since thinking can't be turned off, `effort` becomes the only knob for controlling cost.
Opus 5.5 supports five tiers from `low` to `max`.
The official guide says, at the `medium` tier, it can now match or even surpass the old Opus 5 `high` tier. And if you use `low` for simple tasks, the cost is astonishingly low.
Sounds like a free lunch, but the guide immediately adds: at the same tier, Opus 5.5 does much more thinking per turn than Opus 5, especially at higher tiers.
In other words, if you migrate the old project's `high` tier unchanged, not only do turns get longer, but output token counts also skyrocket.
Calling it `high` doesn't mean it's thinking the same amount anymore.
A down-to-earth suggestion is: start from `medium`, run it with your own data, and only move up when you truly need more intelligence.
If you want it to think less, go down a tier. That's far more effective than pleading in the prompt, "Don't overthink."
Removing the "AI flavor" depends entirely on a blacklist.
Finally, the guide has a killer trick for front-end pages.
If you don't give clear visual direction and let the model do its own thing, it will most likely produce that generic "AI style" interface.
At that point, if you write in the prompt "Please avoid a generic AI feel," it will just switch from one AI template to another AI template.
The truly effective method is to directly use a blacklist.
The official example lists: no cream or off-white backgrounds, no italicized emphasis words in headings, no section numbering like 01/02, no monospace font labels, no pill-shaped buttons.
Models can understand specific "what I don't want," but they can't understand abstract "make it look nicer."
After going through this official guide, the biggest takeaway is:
The model is sprinting ahead, but many applications' scaffolding is still stuck in the previous generation.
In the past, we feared it wouldn't think enough, so we forced it to write out its reasoning step by step. Now we have to persuade it to think less. In the past, we worked hard to make it report progress on time. Now it reports so diligently that the work stalls halfway.
Whether an Agent can finish a job depends only half on model capability. The other half depends on how you define "done," how you preserve context, and how you allocate the reasoning budget.
Next time your Agent slips away halfway, don't rush to scold it for being lazy. First, go back and look at the loop you wrote yourself.
References:





