Skip to content

Upgrading: several finishWith tools in forced completion ​

Forced completion and Final Step now offer every finishWith tool, on every runtime. Before, they expected only the agent's first one: once forced, an agent with several finishWith tools could finish only through the first. Guide: Finishing Agents.

An agent with one finishWith tool (or none, finishing through __finish__) sends the same forced request as before.

What changes for an agent with several finishWith tools ​

  • forced_tool. The forced call sends the finishWith tools only, with toolChoice: 'required'. When the model's thinking is history-bound, it sends every tool with the new set-shaped choice { type: 'tools', toolNames }.
  • native_output. The forced call asks for the completion envelope, { "completion": { "tool": "<name>", "input": { … } } }, one branch per tool (format name completion), and the run completes through the tool the answer names. With a strict finishWith tool among them, the call sends no format, as for one strict tool. checkCompletionSupport checks the envelope at entry, so a model that cannot take it is refused before anything is written (framework_completion_schema_unsupported; DBOS runs no such check, and every DBOS forced call is forced_tool).
  • Final Step. The instruction names every tool ("call one of A or B now"), and the phase's tools row keeps all of them on.
  • One call. A forced reply is still exactly one call: one call to any of the tools completes the run; two finishing calls in one forced reply are a miss.
  • A finishWith tool your app switched off with a tools row before the phase began is not offered.

What breaks ​

No field below keeps its old name (user ruling 2026-11-15: no backwards compatibility).

BeforeNow
ForcedCompletionState.expectedToolName: stringexpectedToolNames: string[] (non-empty); expectedToolStrict is true when any of them is strict
forced_completion stream chunk expectedToolNameexpectedToolNames: string[]
Correction message metadata.forcedCompletion.expectedToolNameexpectedToolNames
Context-format inputs final_step / completion_correction: toolNametoolNames: string[] (a ContextFormat.render of your own reads it)
finalStepInstruction(toolName, trigger)finalStepInstruction(toolNames, trigger)
planStepProcessing(…, { forcedCompletion: { expectedToolName } }){ forcedCompletion: { expectedToolNames } }
LLMAdapter.finalStepToolChoice(config, toolName)finalStepToolChoice(config, toolNames)
LLMToolChoiceadds { type: 'tools'; toolNames: string[] }: a custom adapter maps it (to 'required' at least)
ForcedCompletionDirective (forced_tool) toolChoice was always namednamed, 'required' or { type: 'tools', toolNames }
resolveExpectedToolName(tools), resolveExpectedTool(tools)resolveExpectedTools(tools, { active? }) → { expectedToolNames, expectedToolStrict? }

New exports: resolveExpectedTools, completionOutputFormat, parseCompletionEnvelope, COMPLETION_ENVELOPE_NAME.

A client that reads the forced_completion chunk reads expectedToolNames. The AI SDK UI stream never carried the field, so a stock useChat client is unaffected.

Deploying ​

  • Drain in-flight Temporal workflows before you deploy. A workflow's recorded runLLMStep result carries the old expectedToolName, so a history recorded by an earlier release does not replay under this one (there is no wf.patched branch for it).
  • Stored sessions are not migrated (user ruling 2026-11-15). A session an earlier release saved in a pending forced phase carries expectedToolName, which this release does not read: a store that validates the phase on load (Postgres, for one) drops it and the run goes on as an ordinary step; elsewhere its next forced call fails. Let such runs finish before you deploy (CF Workflows instances and DBOS workflows in a forced phase too), or start with a fresh store.
  • Deploy the release to everything that reads the forced_completion chunk or a stored session at the same time.

Released under the MIT License.