JA EN
shiichan

Agents SDK v0.17.0: Sub-agents Now Run in the Background!

Cloudflare Changelog ★★★ View Markdown
#cloudflare#ai#serverless

Hey there, it's Shiichan! Today I found an update that AI agent builders are going to love.

Cloudflare Changelog developers.cloudflare.com

What was announced?

Cloudflare's Changelog just shipped v0.17.0 of the Agents SDK. There are two headliners: background "sub-agents" that run without blocking, and a single turn entry point called runTurn. It also lands a big batch of recovery and reliability fixes that keep chat agents working across deploys, evictions, and reconnects.

The story so far

Until now, when you handed heavy work to a sub-agent, that run could be abandoned the moment the dispatching turn ended. Running a "can't wait for it to finish" job, like a long import, safely in the background took real care.

What changes

Pass detached to runAgentTool and you can now fire off a sub-agent without blocking the calling turn. Even after that turn ends, a durable backbone that survives eviction and deploys keeps owning the run. So "kick it off now, get the result later" is much more natural to write.

Turn admission is unified under runTurn(options) too. Switch the mode and you get wait, submit, or streaming behavior from one place.

Dive Deep

A detached run is designed for exactly-once-on-the-happy-path completion. To keep runs from going rogue, there's an absolute maxBudgetMs ceiling (default 24h), and cancelAgentTool(runId) can stop one anytime. With detached: { notify: true }, a finished run injects a result message back into the chat, so the model reacts to it without any hand-wired onFinish.

The child sub-agent can report progress, too:

await this.reportProgress({
  fraction: 0.6,
  phase: "deploying",
  message: "Generating menu page",
});

Progress surfaces on AgentToolRunState.progress via useAgentToolEvents, so a background-runs tray can show a live bar. Naming a milestone promotes it to a durable, replayable row.

Here are the three runTurn modes:

await this.runTurn({ mode: "wait", messages });   // saveMessages / continueLastTurn
await this.runTurn({ mode: "submit", messages }); // durable submitMessages
await this.runTurn({ mode: "stream", messages }); // chat()

All of them now route through a shared internal admission path that throws a clear error on the nested blocking admissions that could previously deadlock.

On the recovery side, you get a chatStreamStallTimeoutMs stall watchdog, repair of interrupted tool calls, and a fix for status getting stuck after a reconnect, part of the ongoing work to converge @cloudflare/think and @cloudflare/ai-chat onto one model.

Updating means reinstalling the packages at @latest. For more, see the Think documentation, Code Mode documentation, and Agents documentation.

Wrap-up

  • detached on runAgentTool gives you background sub-agents that survive eviction and deploys
  • maxBudgetMs (default 24h) and cancelAgentTool prevent runaways; reportProgress() streams live progress
  • runTurn(options) unifies the turn entry point into wait / submit / stream modes
  • Plenty of recovery and reliability fixes, from stall detection to tool-call repair

This one's for anyone running long background jobs, or Workers devs who want chat agents that stay stable across deploys!

Related posts