@ai-sdk/workflow 1.0.38 → 1.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/workflow",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "type": "module",
   "description": "WorkflowAgent for building AI agents with AI SDK",
   "license": "Apache-2.0",
@@ -28,8 +28,8 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "@ai-sdk/provider": "4.0.4",
-    "@ai-sdk/provider-utils": "5.0.13",
-    "ai": "7.0.38"
+    "ai": "7.0.40",
+    "@ai-sdk/provider-utils": "5.0.14"
   },
   "devDependencies": {
     "@types/node": "22.19.19",

package/src/serializable-schema.ts

@@ -11,7 +11,13 @@
  * to use that interface directly.
  */
 import type { JSONSchema7 } from '@ai-sdk/provider';
-import { asSchema, jsonSchema } from '@ai-sdk/provider-utils';
+import {
+  asSchema,
+  type Experimental_SandboxSession as SandboxSession,
+  type InferToolSetContext,
+  jsonSchema,
+  type Tool,
+} from '@ai-sdk/provider-utils';
 import { tool, type ToolSet } from 'ai';
 import Ajv from 'ajv';
 
@@ -37,13 +43,25 @@ export type SerializableToolDef = {
  * (as JSON Schema) are preserved — execute functions are stripped since they
  * run outside the step.
  */
-export function serializeToolSet(
-  tools: ToolSet,
+export function serializeToolSet<TOOLS extends ToolSet>(
+  tools: TOOLS,
+  {
+    toolsContext = {} as InferToolSetContext<TOOLS>,
+    experimental_sandbox: sandbox,
+  }: {
+    toolsContext?: InferToolSetContext<TOOLS>;
+    experimental_sandbox?: SandboxSession;
+  } = {},
 ): Record<string, SerializableToolDef> {
   return Object.fromEntries(
     Object.entries(tools).map(([name, t]) => {
       const def: SerializableToolDef = {
-        description: t.description as string, // TODO support tools with function descriptions
+        description: resolveToolDescription({
+          tool: t,
+          toolName: name,
+          toolsContext,
+          experimental_sandbox: sandbox,
+        }),
         inputSchema: asSchema(t.inputSchema).jsonSchema as JSONSchema7,
       };
 
@@ -61,6 +79,27 @@ export function serializeToolSet(
   );
 }
 
+function resolveToolDescription<TOOLS extends ToolSet>({
+  tool,
+  toolName,
+  toolsContext,
+  experimental_sandbox: sandbox,
+}: {
+  tool: Tool;
+  toolName: string;
+  toolsContext: InferToolSetContext<TOOLS>;
+  experimental_sandbox?: SandboxSession;
+}): string | undefined {
+  return tool.description === undefined
+    ? undefined
+    : typeof tool.description === 'string'
+      ? tool.description
+      : tool.description({
+          context: toolsContext[toolName as keyof InferToolSetContext<TOOLS>],
+          experimental_sandbox: sandbox,
+        });
+}
+
 /**
  * Reconstructs tool objects from serializable tool definitions inside a step.
  *

package/src/stream-text-iterator.ts

@@ -9,6 +9,7 @@ import {
   experimental_filterActiveTools as filterActiveTools,
   type Experimental_LanguageModelStreamPart as ModelCallStreamPart,
   type Experimental_SandboxSession as SandboxSession,
+  type Instructions,
   type LanguageModel,
   type LanguageModelUsage,
   type ModelMessage,
@@ -40,6 +41,36 @@ import type {
 // Re-export for consumers
 export type { ProviderExecutedToolResult } from './do-stream-step.js';
 
+const prepareStepGenerationSettingKeys = [
+  'maxOutputTokens',
+  'temperature',
+  'topP',
+  'topK',
+  'presencePenalty',
+  'frequencyPenalty',
+  'stopSequences',
+  'seed',
+  'maxRetries',
+  'headers',
+  'reasoning',
+  'providerOptions',
+] as const satisfies readonly (keyof GenerationSettings)[];
+
+function mergePrepareStepGenerationSettings(
+  current: GenerationSettings,
+  overrides: Partial<GenerationSettings>,
+): GenerationSettings {
+  const definedOverrides: Partial<GenerationSettings> = {};
+
+  for (const key of prepareStepGenerationSettingKeys) {
+    if (overrides[key] !== undefined) {
+      Object.assign(definedOverrides, { [key]: overrides[key] });
+    }
+  }
+
+  return { ...current, ...definedOverrides };
+}
+
 /**
  * The value yielded by the stream text iterator when tool calls are requested.
  * Contains both the tool calls and the current conversation messages.
@@ -64,6 +95,8 @@ export interface StreamTextIteratorYieldValue {
 // This runs in the workflow context
 export async function* streamTextIterator({
   prompt,
+  initialInstructions,
+  initialMessages = prompt as unknown as ModelMessage[],
   tools = {},
   writable,
   model,
@@ -84,6 +117,8 @@ export async function* streamTextIterator({
   experimental_sandbox: sandbox,
 }: {
   prompt: LanguageModelV4Prompt;
+  initialInstructions?: Instructions;
+  initialMessages?: Array<ModelMessage>;
   tools: ToolSet;
   writable?: WritableStream<ModelCallStreamPart<ToolSet>>;
   model: LanguageModel;
@@ -150,6 +185,8 @@ export async function* streamTextIterator({
     if (prepareStep) {
       const prepareResult = await prepareStep({
         model: currentModel,
+        initialInstructions,
+        initialMessages,
         stepNumber,
         steps,
         messages: conversationPrompt,
@@ -202,79 +239,10 @@ export async function* streamTextIterator({
       if (prepareResult?.activeTools !== undefined) {
         currentActiveTools = prepareResult.activeTools;
       }
-      // Apply generation settings overrides
-      if (prepareResult?.maxOutputTokens !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          maxOutputTokens: prepareResult.maxOutputTokens,
-        };
-      }
-      if (prepareResult?.temperature !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          temperature: prepareResult.temperature,
-        };
-      }
-      if (prepareResult?.topP !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          topP: prepareResult.topP,
-        };
-      }
-      if (prepareResult?.topK !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          topK: prepareResult.topK,
-        };
-      }
-      if (prepareResult?.presencePenalty !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          presencePenalty: prepareResult.presencePenalty,
-        };
-      }
-      if (prepareResult?.frequencyPenalty !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          frequencyPenalty: prepareResult.frequencyPenalty,
-        };
-      }
-      if (prepareResult?.stopSequences !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          stopSequences: prepareResult.stopSequences,
-        };
-      }
-      if (prepareResult?.seed !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          seed: prepareResult.seed,
-        };
-      }
-      if (prepareResult?.maxRetries !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          maxRetries: prepareResult.maxRetries,
-        };
-      }
-      if (prepareResult?.headers !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          headers: prepareResult.headers,
-        };
-      }
-      if (prepareResult?.reasoning !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          reasoning: prepareResult.reasoning,
-        };
-      }
-      if (prepareResult?.providerOptions !== undefined) {
-        currentGenerationSettings = {
-          ...currentGenerationSettings,
-          providerOptions: prepareResult.providerOptions,
-        };
-      }
+      currentGenerationSettings = mergePrepareStepGenerationSettings(
+        currentGenerationSettings,
+        prepareResult ?? {},
+      );
       if (prepareResult?.toolChoice !== undefined) {
         currentToolChoice = prepareResult.toolChoice;
       }
@@ -322,7 +290,10 @@ export async function* streamTextIterator({
       // Serialize tools before crossing the step boundary — zod schemas
       // contain functions that can't be serialized by the workflow runtime.
       // Tools are reconstructed with Ajv validation inside doStreamStep.
-      const serializedTools = serializeToolSet(effectiveTools);
+      const serializedTools = serializeToolSet(effectiveTools, {
+        toolsContext: currentToolsContext as never,
+        experimental_sandbox: stepSandbox,
+      });
       const modelCallInfo = getModelInfo(currentModel);
 
       await telemetryDispatcher.onLanguageModelCallStart?.({

package/src/workflow-agent.ts

@@ -256,6 +256,16 @@ export interface PrepareStepInfo<
    */
   model: LanguageModel;
 
+  /**
+   * The initial instructions passed to the stream.
+   */
+  initialInstructions: Instructions | undefined;
+
+  /**
+   * The initial messages passed to the stream.
+   */
+  initialMessages: Array<ModelMessage>;
+
   /**
    * The current step number (0-indexed).
    */
@@ -371,6 +381,11 @@ export interface PrepareCallOptions<
   tools: TTools;
   instructions?: Instructions;
   toolChoice?: ToolChoice<TTools>;
+  stopWhen?:
+    | StopCondition<NoInfer<ToolSet>, any>
+    | Array<StopCondition<NoInfer<ToolSet>, any>>;
+  activeTools?: ActiveTools<NoInfer<TTools>>;
+  experimental_download?: DownloadFunction;
   telemetry?: TelemetryOptions<TRuntimeContext, TTools>;
   /**
    * Runtime context that flows through the agent loop.
@@ -837,7 +852,14 @@ export type WorkflowAgentStreamOptions<
       }
   ) & {
     /**
-     * Optional system prompt override. If provided, overrides the system prompt from the constructor.
+     * Instructions override for this stream call.
+     */
+    instructions?: Instructions;
+
+    /**
+     * Optional system prompt override.
+     *
+     * @deprecated Use `instructions` instead.
      */
     system?: string;
 
@@ -1324,7 +1346,8 @@ export class WorkflowAgent<
 
     // Call prepareCall to transform parameters before the agent loop
     let effectiveModel: LanguageModel = this.model;
-    let effectiveInstructions = options.system ?? this.instructions;
+    let effectiveInstructions =
+      options.instructions ?? options.system ?? this.instructions;
     let effectivePrompt: string | Array<ModelMessage> | undefined =
       options.prompt;
     let effectiveMessages: Array<ModelMessage> | undefined = options.messages;
@@ -1338,6 +1361,11 @@ export class WorkflowAgent<
         Context | undefined
       >;
     let effectiveToolChoiceFromPrepare = options.toolChoice ?? this.toolChoice;
+    let effectiveStopWhenFromPrepare = options.stopWhen ?? this.stopWhen;
+    let effectiveActiveToolsFromPrepare =
+      options.activeTools ?? this.activeTools;
+    let effectiveDownloadFromPrepare =
+      options.experimental_download ?? this.experimentalDownload;
     let effectiveTelemetryFromPrepare = options.telemetry ?? this.telemetry;
 
     // Resolve messages for prepareCall: use messages directly, or convert prompt
@@ -1354,6 +1382,9 @@ export class WorkflowAgent<
         tools: this.tools,
         instructions: effectiveInstructions,
         toolChoice: effectiveToolChoiceFromPrepare as ToolChoice<TBaseTools>,
+        stopWhen: effectiveStopWhenFromPrepare,
+        activeTools: effectiveActiveToolsFromPrepare,
+        experimental_download: effectiveDownloadFromPrepare,
         telemetry: effectiveTelemetryFromPrepare,
         runtimeContext: effectiveRuntimeContext,
         toolsContext: effectiveToolsContext as InferToolSetContext<TBaseTools>,
@@ -1378,6 +1409,12 @@ export class WorkflowAgent<
       if (prepared.toolChoice !== undefined)
         effectiveToolChoiceFromPrepare =
           prepared.toolChoice as ToolChoice<TBaseTools>;
+      if (prepared.stopWhen !== undefined)
+        effectiveStopWhenFromPrepare = prepared.stopWhen;
+      if (prepared.activeTools !== undefined)
+        effectiveActiveToolsFromPrepare = prepared.activeTools;
+      if (prepared.experimental_download !== undefined)
+        effectiveDownloadFromPrepare = prepared.experimental_download;
       if (prepared.telemetry !== undefined)
         effectiveTelemetryFromPrepare = prepared.telemetry;
       if (prepared.maxOutputTokens !== undefined)
@@ -1423,7 +1460,7 @@ export class WorkflowAgent<
         ? { prompt: effectivePrompt }
         : { messages: effectiveMessages! }),
     } as Prompt);
-    const download = options.experimental_download ?? this.experimentalDownload;
+    const download = effectiveDownloadFromPrepare;
     const sandbox = options.experimental_sandbox ?? this.experimentalSandbox;
 
     // Process tool approval responses before starting the agent loop.
@@ -1832,7 +1869,7 @@ export class WorkflowAgent<
     const effectiveToolChoice = effectiveToolChoiceFromPrepare;
 
     // Filter tools if activeTools is specified (stream-level overrides constructor default)
-    const effectiveActiveTools = options.activeTools ?? this.activeTools;
+    const effectiveActiveTools = effectiveActiveToolsFromPrepare;
     const effectiveTools =
       effectiveActiveTools && effectiveActiveTools.length > 0
         ? (filterActiveTools({
@@ -2100,8 +2137,9 @@ export class WorkflowAgent<
       tools: effectiveTools as ToolSet,
       writable: options.writable,
       prompt: modelPrompt,
-      stopConditions: options.stopWhen ?? this.stopWhen,
-
+      initialInstructions: effectiveInstructions,
+      initialMessages: prompt.messages,
+      stopConditions: effectiveStopWhenFromPrepare,
       onStepEnd: mergedOnStepEnd as any,
       onStepStart: mergedOnStepStart as any,
       onError: options.onError,