@ai-sdk/workflow 1.0.0-canary.39 → 1.0.0-canary.41

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @ai-sdk/workflow
 
+## 1.0.0-canary.41
+
+### Patch Changes
+
+- 1d56275: feat(workflow): add `runtimeContext` and `toolsContext` to `WorkflowAgent`.
+
+  `runtimeContext` is shared agent state that flows through `prepareCall`, `prepareStep`, step results, and `onFinish`. `toolsContext` is a per-tool map; each tool receives its own validated entry as `context`, validated against `tool.contextSchema` when defined. The previous `experimental_context` option (and corresponding fields on related callbacks and option types) has been removed — use `runtimeContext` for shared state and `toolsContext` for per-tool values. Context values in `WorkflowAgent` should be serializable because they can cross workflow and step boundaries.
+
+## 1.0.0-canary.40
+
+### Patch Changes
+
+- Updated dependencies [fd4f578]
+- Updated dependencies [31f69de]
+- Updated dependencies [7c71ac6]
+- Updated dependencies [c0c8ca2]
+- Updated dependencies [5faf71c]
+- Updated dependencies [69254e0]
+- Updated dependencies [3015fc3]
+- Updated dependencies [eee1166]
+- Updated dependencies [7dbf992]
+  - ai@7.0.0-canary.125
+  - @ai-sdk/provider-utils@5.0.0-canary.34
+
 ## 1.0.0-canary.39
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { LanguageModelV4, SharedV4ProviderOptions, LanguageModelV4CallOptions, LanguageModelV4Prompt, LanguageModelV4StreamPart } from '@ai-sdk/provider';
+import { Context, HasRequiredKey, InferToolSetContext } from '@ai-sdk/provider-utils';
 import { ToolSet, LanguageModel, SystemModelMessage, ToolChoice, StopCondition, ActiveTools, LanguageModelResponseMetadata, LanguageModelUsage, FinishReason, ToolCallRepairFunction, StepResult, GenerateTextOnStepFinishCallback, ModelMessage, Experimental_LanguageModelStreamPart, UIMessage, UIMessageChunk, ChatTransport, PrepareSendMessagesRequest, PrepareReconnectToStreamRequest, ChatRequestOptions } from 'ai';
 export { Experimental_LanguageModelStreamPart as ModelCallStreamPart, Output, ToolCallRepairFunction } from 'ai';
 
@@ -18,11 +19,11 @@ type CompatibleLanguageModel = LanguageModelV4;
  * Alias for the AI SDK's GenerateTextOnStepFinishCallback, using
  * WorkflowAgent-consistent naming.
  */
-type WorkflowAgentOnStepFinishCallback<TTools extends ToolSet = ToolSet> = GenerateTextOnStepFinishCallback<TTools, any>;
+type WorkflowAgentOnStepFinishCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = GenerateTextOnStepFinishCallback<TTools, TRuntimeContext>;
 /**
  * Infer the type of the tools of a workflow agent.
  */
-type InferWorkflowAgentTools<WORKFLOW_AGENT> = WORKFLOW_AGENT extends WorkflowAgent<infer TOOLS> ? TOOLS : never;
+type InferWorkflowAgentTools<WORKFLOW_AGENT> = WORKFLOW_AGENT extends WorkflowAgent<infer TOOLS, any> ? TOOLS : never;
 /**
  * Infer the UI message type of a workflow agent.
  */
@@ -52,6 +53,11 @@ interface OutputSpecification<OUTPUT, PARTIAL> {
  * Provider-specific options type. This is equivalent to SharedV4ProviderOptions from @ai-sdk/provider.
  */
 type ProviderOptions = SharedV4ProviderOptions;
+type WorkflowAgentToolsContextParameter<TTools extends ToolSet> = HasRequiredKey<InferToolSetContext<TTools>> extends true ? {
+    toolsContext: InferToolSetContext<TTools>;
+} : {
+    toolsContext?: never;
+};
 /**
  * Telemetry settings for observability.
  */
@@ -182,7 +188,7 @@ interface GenerationSettings {
 /**
  * Information passed to the prepareStep callback.
  */
-interface PrepareStepInfo<TTools extends ToolSet = ToolSet> {
+interface PrepareStepInfo<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> {
     /**
      * The current model configuration (string or function).
      * The function should return a LanguageModelV4 instance.
@@ -195,22 +201,31 @@ interface PrepareStepInfo<TTools extends ToolSet = ToolSet> {
     /**
      * All previous steps with their results.
      */
-    steps: StepResult<TTools, any>[];
+    steps: StepResult<TTools, TRuntimeContext>[];
     /**
      * The messages that will be sent to the model.
      * This is the LanguageModelV4Prompt format used internally.
      */
     messages: LanguageModelV4Prompt;
     /**
-     * The context passed via the experimental_context setting (experimental).
+     * The runtime context that flows through the agent loop.
+     * Treat the value as immutable; return a new `runtimeContext` from
+     * `prepareStep` to update it for the current and subsequent steps.
+     */
+    runtimeContext: TRuntimeContext;
+    /**
+     * Per-tool context, keyed by tool name. Each tool receives only its own
+     * validated entry as `context` during execution.
+     * Treat the value as immutable; return a new `toolsContext` from
+     * `prepareStep` to update it for the current and subsequent steps.
      */
-    experimental_context: unknown;
+    toolsContext: InferToolSetContext<TTools>;
 }
 /**
  * Return type from the prepareStep callback.
  * All properties are optional - only return the ones you want to override.
  */
-interface PrepareStepResult extends Partial<GenerationSettings> {
+interface PrepareStepResult<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> extends Partial<GenerationSettings> {
     /**
      * Override the model for this step.
      */
@@ -234,20 +249,25 @@ interface PrepareStepResult extends Partial<GenerationSettings> {
      */
     activeTools?: string[];
     /**
-     * Context that is passed into tool execution. Experimental.
-     * Changing the context will affect the context in this step and all subsequent steps.
+     * Updated runtime context for the current and subsequent steps.
+     * Returning a value replaces the agent's runtime context.
      */
-    experimental_context?: unknown;
+    runtimeContext?: TRuntimeContext;
+    /**
+     * Updated per-tool context for the current and subsequent steps.
+     * Returning a value replaces the agent's tools context.
+     */
+    toolsContext?: InferToolSetContext<TTools>;
 }
 /**
  * Callback function called before each step in the agent loop.
  * Use this to modify settings, manage context, or implement dynamic behavior.
  */
-type PrepareStepCallback<TTools extends ToolSet = ToolSet> = (info: PrepareStepInfo<TTools>) => PrepareStepResult | Promise<PrepareStepResult>;
+type PrepareStepCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = (info: PrepareStepInfo<TTools, TRuntimeContext>) => PrepareStepResult<TTools, TRuntimeContext> | undefined | Promise<PrepareStepResult<TTools, TRuntimeContext> | undefined>;
 /**
  * Options passed to the prepareCall callback.
  */
-interface PrepareCallOptions<TTools extends ToolSet = ToolSet> extends Partial<GenerationSettings> {
+interface PrepareCallOptions<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> extends Partial<GenerationSettings> {
     model: LanguageModel;
     tools: TTools;
     instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
@@ -257,7 +277,15 @@ interface PrepareCallOptions<TTools extends ToolSet = ToolSet> extends Partial<G
      * @deprecated Use `telemetry` instead. This alias will be removed in a future major release.
      */
     experimental_telemetry?: TelemetryOptions;
-    experimental_context?: unknown;
+    /**
+     * Runtime context that flows through the agent loop.
+     * Treat as immutable; return a new `runtimeContext` to update it for the call.
+     */
+    runtimeContext?: TRuntimeContext;
+    /**
+     * Per-tool context, keyed by tool name.
+     */
+    toolsContext?: InferToolSetContext<TTools>;
     messages: ModelMessage[];
 }
 /**
@@ -266,15 +294,15 @@ interface PrepareCallOptions<TTools extends ToolSet = ToolSet> extends Partial<G
  * Note: `tools` cannot be overridden via prepareCall because they are
  * bound at construction time for type safety.
  */
-type PrepareCallResult<TTools extends ToolSet = ToolSet> = Partial<Omit<PrepareCallOptions<TTools>, 'tools'>>;
+type PrepareCallResult<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = Partial<Omit<PrepareCallOptions<TTools, TRuntimeContext>, 'tools'>>;
 /**
  * Callback called once before the agent loop starts to transform call parameters.
  */
-type PrepareCallCallback<TTools extends ToolSet = ToolSet> = (options: PrepareCallOptions<TTools>) => PrepareCallResult<TTools> | Promise<PrepareCallResult<TTools>>;
+type PrepareCallCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = (options: PrepareCallOptions<TTools, TRuntimeContext>) => PrepareCallResult<TTools, TRuntimeContext> | Promise<PrepareCallResult<TTools, TRuntimeContext>>;
 /**
  * Configuration options for creating a {@link WorkflowAgent} instance.
  */
-interface WorkflowAgentOptions<TTools extends ToolSet = ToolSet> extends GenerationSettings {
+type WorkflowAgentOptions<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = GenerationSettings & WorkflowAgentToolsContextParameter<TTools> & {
     /**
      * The id of the agent.
      */
@@ -317,13 +345,19 @@ interface WorkflowAgentOptions<TTools extends ToolSet = ToolSet> extends Generat
      */
     experimental_telemetry?: TelemetryOptions;
     /**
-     * Default context that is passed into tool execution for every stream call on this agent.
+     * Default runtime context for every stream call on this agent.
+     *
+     * The runtime context flows through `prepareStep`, lifecycle callbacks,
+     * and step results.
+     * Treat as immutable; return a new `runtimeContext` from `prepareStep`
+     * to update it between steps.
      *
-     * Per-stream `experimental_context` values passed to `stream()` override this default.
-     * Experimental (can break in patch releases).
-     * @default undefined
+     * In workflow context, keep values serializable so they can cross workflow
+     * and step boundaries.
+     *
+     * Per-stream `runtimeContext` values passed to `stream()` override this default.
      */
-    experimental_context?: unknown;
+    runtimeContext?: TRuntimeContext;
     /**
      * Default stop condition for the agent loop. When the condition is an array,
      * any of the conditions can be met to stop the generation.
@@ -364,46 +398,46 @@ interface WorkflowAgentOptions<TTools extends ToolSet = ToolSet> extends Generat
      *
      * Per-stream `prepareStep` values passed to `stream()` override this default.
      */
-    prepareStep?: PrepareStepCallback<TTools>;
+    prepareStep?: PrepareStepCallback<TTools, TRuntimeContext>;
     /**
      * Callback function to be called after each step completes.
      */
-    onStepFinish?: WorkflowAgentOnStepFinishCallback<ToolSet>;
+    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools, TRuntimeContext>;
     /**
      * Callback that is called when the LLM response and all request tool executions are finished.
      */
-    onFinish?: WorkflowAgentOnFinishCallback<ToolSet>;
+    onFinish?: WorkflowAgentOnFinishCallback<TTools, TRuntimeContext>;
     /**
      * Callback called when the agent starts streaming, before any LLM calls.
      */
-    experimental_onStart?: WorkflowAgentOnStartCallback;
+    experimental_onStart?: WorkflowAgentOnStartCallback<TTools, TRuntimeContext>;
     /**
      * Callback called before each step (LLM call) begins.
      */
-    experimental_onStepStart?: WorkflowAgentOnStepStartCallback;
+    experimental_onStepStart?: WorkflowAgentOnStepStartCallback<TTools, TRuntimeContext>;
     /**
      * Callback called before a tool's execute function runs.
      */
-    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback;
+    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback<TTools>;
     /**
      * Callback called after a tool execution completes.
      */
-    onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback;
+    onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback<TTools>;
     /**
      * Prepare the parameters for the stream call.
      * Called once before the agent loop starts. Use this to transform
      * model, tools, instructions, or other settings based on runtime context.
      */
-    prepareCall?: PrepareCallCallback<TTools>;
-}
+    prepareCall?: PrepareCallCallback<TTools, TRuntimeContext>;
+};
 /**
  * Callback that is called when the LLM response and all request tool executions are finished.
  */
-type WorkflowAgentOnFinishCallback<TTools extends ToolSet = ToolSet, OUTPUT = never> = (event: {
+type WorkflowAgentOnFinishCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context, OUTPUT = never> = (event: {
     /**
      * Details for all steps.
      */
-    readonly steps: StepResult<TTools, any>[];
+    readonly steps: StepResult<TTools, TRuntimeContext>[];
     /**
      * The final messages including all tool calls and results.
      */
@@ -421,9 +455,13 @@ type WorkflowAgentOnFinishCallback<TTools extends ToolSet = ToolSet, OUTPUT = ne
      */
     readonly totalUsage: LanguageModelUsage;
     /**
-     * Context that is passed into tool execution.
+     * The runtime context at the end of the agent loop.
+     */
+    readonly runtimeContext: TRuntimeContext;
+    /**
+     * The per-tool context at the end of the agent loop.
      */
-    readonly experimental_context: unknown;
+    readonly toolsContext: InferToolSetContext<TTools>;
     /**
      * The generated structured output. It uses the `output` specification.
      * Only available when `output` is specified.
@@ -448,16 +486,20 @@ type WorkflowAgentOnAbortCallback<TTools extends ToolSet = ToolSet> = (event: {
 /**
  * Callback that is called when the agent starts streaming, before any LLM calls.
  */
-type WorkflowAgentOnStartCallback = (event: {
+type WorkflowAgentOnStartCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = (event: {
     /** The model being used */
     readonly model: LanguageModel;
     /** The messages being sent */
     readonly messages: ModelMessage[];
+    /** Shared runtime context for this agent loop */
+    readonly runtimeContext: TRuntimeContext;
+    /** Per-tool context map for this agent loop */
+    readonly toolsContext: InferToolSetContext<TTools>;
 }) => PromiseLike<void> | void;
 /**
  * Callback that is called before each step (LLM call) begins.
  */
-type WorkflowAgentOnStepStartCallback<TTools extends ToolSet = ToolSet> = (event: {
+type WorkflowAgentOnStepStartCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = (event: {
     /** The current step number (0-based) */
     readonly stepNumber: number;
     /** The model being used for this step */
@@ -465,29 +507,41 @@ type WorkflowAgentOnStepStartCallback<TTools extends ToolSet = ToolSet> = (event
     /** The messages being sent for this step */
     readonly messages: ModelMessage[];
     /** Results from all previously finished steps */
-    readonly steps: ReadonlyArray<StepResult<TTools, any>>;
+    readonly steps: ReadonlyArray<StepResult<TTools, TRuntimeContext>>;
+    /** Shared runtime context for this step */
+    readonly runtimeContext: TRuntimeContext;
+    /** Per-tool context map for this step */
+    readonly toolsContext: InferToolSetContext<TTools>;
 }) => PromiseLike<void> | void;
 /**
  * Callback that is called before a tool's execute function runs.
  */
-type WorkflowAgentOnToolExecutionStartCallback = (event: {
+type WorkflowAgentOnToolExecutionStartCallback<TTools extends ToolSet = ToolSet> = (event: {
     /** The tool call being executed */
     readonly toolCall: ToolCall;
     /** The current step number (0-based) */
     readonly stepNumber: number;
+    /** Messages sent to the language model for the step that produced the call */
+    readonly messages: ModelMessage[];
+    /** Tool-specific context passed to the tool */
+    readonly toolContext: InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>] | undefined;
 }) => PromiseLike<void> | void;
 /**
  * Callback that is called after a tool execution completes.
  * Uses a discriminated union pattern: check `success` to determine
  * whether `output` or `error` is available.
  */
-type WorkflowAgentOnToolExecutionEndCallback = (event: {
+type WorkflowAgentOnToolExecutionEndCallback<TTools extends ToolSet = ToolSet> = (event: {
     /** The tool call that was executed */
     readonly toolCall: ToolCall;
     /** The current step number (0-based) */
     readonly stepNumber: number;
     /** Execution time in milliseconds */
     readonly durationMs: number;
+    /** Messages sent to the language model for the step that produced the call */
+    readonly messages: ModelMessage[];
+    /** Tool-specific context passed to the tool */
+    readonly toolContext: InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>] | undefined;
     /** Whether the tool call succeeded */
     readonly success: true;
     /** The tool result */
@@ -500,6 +554,10 @@ type WorkflowAgentOnToolExecutionEndCallback = (event: {
     readonly stepNumber: number;
     /** Execution time in milliseconds */
     readonly durationMs: number;
+    /** Messages sent to the language model for the step that produced the call */
+    readonly messages: ModelMessage[];
+    /** Tool-specific context passed to the tool */
+    readonly toolContext: InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>] | undefined;
     /** Whether the tool call succeeded */
     readonly success: false;
     /** The error that occurred */
@@ -509,7 +567,7 @@ type WorkflowAgentOnToolExecutionEndCallback = (event: {
 /**
  * Options for the {@link WorkflowAgent.stream} method.
  */
-type WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never> = Partial<GenerationSettings> & ({
+type WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context, OUTPUT = never, PARTIAL_OUTPUT = never> = Partial<GenerationSettings> & ({
     /**
      * A prompt. It can be either a text prompt or a list of messages.
      *
@@ -589,11 +647,28 @@ type WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT = never
      */
     experimental_telemetry?: TelemetryOptions;
     /**
-     * Context that is passed into tool execution.
-     * Experimental (can break in patch releases).
-     * @default undefined
+     * Runtime context that flows through the agent loop.
+     *
+     * Treat as immutable; return a new `runtimeContext` from `prepareStep`
+     * to update it between steps.
+     *
+     * In workflow context, keep values serializable so they can cross workflow
+     * and step boundaries.
+     *
+     * Overrides the constructor-level `runtimeContext` if provided.
+     */
+    runtimeContext?: TRuntimeContext;
+    /**
+     * Per-tool context, keyed by tool name. Each tool receives only its own
+     * validated entry as `context` during execution. Tools that declare a
+     * `contextSchema` validate their entry against the schema.
+     *
+     * In workflow context, keep values serializable so they can cross workflow
+     * and step boundaries.
+     *
+     * Overrides the constructor-level `toolsContext` if provided.
      */
-    experimental_context?: unknown;
+    toolsContext?: InferToolSetContext<TTools>;
     /**
      * Optional specification for parsing structured outputs from the LLM response.
      * Use `Output.object({ schema })` for structured output or `Output.text()` for text output.
@@ -643,7 +718,7 @@ type WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT = never
     /**
      * Callback function to be called after each step completes.
      */
-    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools>;
+    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools, TRuntimeContext>;
     /**
      * Callback that is invoked when an error occurs during streaming.
      * You can use it to log errors.
@@ -653,7 +728,7 @@ type WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT = never
      * Callback that is called when the LLM response and all request tool executions
      * (for tools that have an `execute` function) are finished.
      */
-    onFinish?: WorkflowAgentOnFinishCallback<TTools, OUTPUT>;
+    onFinish?: WorkflowAgentOnFinishCallback<TTools, TRuntimeContext, OUTPUT>;
     /**
      * Callback that is called when the operation is aborted.
      */
@@ -661,19 +736,19 @@ type WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT = never
     /**
      * Callback called when the agent starts streaming, before any LLM calls.
      */
-    experimental_onStart?: WorkflowAgentOnStartCallback;
+    experimental_onStart?: WorkflowAgentOnStartCallback<TTools, TRuntimeContext>;
     /**
      * Callback called before each step (LLM call) begins.
      */
-    experimental_onStepStart?: WorkflowAgentOnStepStartCallback;
+    experimental_onStepStart?: WorkflowAgentOnStepStartCallback<TTools, TRuntimeContext>;
     /**
      * Callback called before a tool's execute function runs.
      */
-    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback;
+    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback<TTools>;
     /**
      * Callback called after a tool execution completes.
      */
-    onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback;
+    onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback<TTools>;
     /**
      * Callback function called before each step in the agent loop.
      * Use this to modify settings, manage context, or inject messages dynamically.
@@ -692,7 +767,7 @@ type WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT = never
      * }
      * ```
      */
-    prepareStep?: PrepareStepCallback<TTools>;
+    prepareStep?: PrepareStepCallback<TTools, TRuntimeContext>;
     /**
      * Timeout in milliseconds for the stream operation.
      * When specified, creates an AbortSignal that will abort the operation after the given time.
@@ -808,7 +883,7 @@ interface WorkflowAgentStreamResult<TTools extends ToolSet = ToolSet, OUTPUT = n
  * });
  * ```
  */
-declare class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
+declare class WorkflowAgent<TBaseTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> {
     /**
      * The id of the agent.
      */
@@ -822,7 +897,8 @@ declare class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     private generationSettings;
     private toolChoice?;
     private telemetry?;
-    private experimentalContext;
+    private runtimeContext?;
+    private toolsContext?;
     private stopWhen?;
     private activeTools?;
     private output?;
@@ -836,9 +912,9 @@ declare class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     private constructorOnToolExecutionStart?;
     private constructorOnToolExecutionEnd?;
     private prepareCall?;
-    constructor(options: WorkflowAgentOptions<TBaseTools>);
+    constructor(options: WorkflowAgentOptions<TBaseTools, TRuntimeContext>);
     generate(): void;
-    stream<TTools extends TBaseTools = TBaseTools, OUTPUT = never, PARTIAL_OUTPUT = never>(options: WorkflowAgentStreamOptions<TTools, OUTPUT, PARTIAL_OUTPUT>): Promise<WorkflowAgentStreamResult<TTools, OUTPUT>>;
+    stream<TTools extends TBaseTools = TBaseTools, OUTPUT = never, PARTIAL_OUTPUT = never>(options: WorkflowAgentStreamOptions<TTools, TRuntimeContext, OUTPUT, PARTIAL_OUTPUT>): Promise<WorkflowAgentStreamResult<TTools, OUTPUT>>;
 }
 
 /**