@ai-sdk/workflow 1.0.0-beta.1 → 1.0.0-beta.100

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { LanguageModelV4, SharedV4ProviderOptions, LanguageModelV4Prompt, LanguageModelV4CallOptions, LanguageModelV4StreamPart } from '@ai-sdk/provider';
-import { ToolSet, SystemModelMessage, ToolChoice, StepResult, StreamTextOnStepFinishCallback, ModelMessage, FinishReason, LanguageModelUsage, Experimental_LanguageModelStreamPart, StopCondition, LanguageModelResponseMetadata, ToolCallRepairFunction, UIMessage, UIMessageChunk, ChatTransport, PrepareSendMessagesRequest, PrepareReconnectToStreamRequest, ChatRequestOptions } from 'ai';
+import { LanguageModelV4, SharedV4ProviderOptions, LanguageModelV4CallOptions, LanguageModelV4Prompt, LanguageModelV4StreamPart } from '@ai-sdk/provider';
+import { Context, HasRequiredKey, InferToolSetContext } from '@ai-sdk/provider-utils';
+import { ToolSet, LanguageModel, Instructions, ToolChoice, TelemetryOptions as TelemetryOptions$1, StopCondition, ActiveTools, LanguageModelResponseMetadata, LanguageModelUsage, FinishReason, ToolCallRepairFunction, StepResult, GenerateTextOnStepEndCallback, ModelMessage, Experimental_LanguageModelStreamPart, UIMessage, UIMessageChunk, ChatTransport, PrepareSendMessagesRequest, PrepareReconnectToStreamRequest, ChatRequestOptions } from 'ai';
 export { Experimental_LanguageModelStreamPart as ModelCallStreamPart, Output, ToolCallRepairFunction } from 'ai';
 
 /**
@@ -13,10 +14,23 @@ export { Experimental_LanguageModelStreamPart as ModelCallStreamPart, Output, To
  */
 type CompatibleLanguageModel = LanguageModelV4;
 
+/**
+ * Callback function to be called after each step completes.
+ * Alias for the AI SDK's GenerateTextOnStepEndCallback, using
+ * WorkflowAgent-consistent naming.
+ */
+type WorkflowAgentOnStepEndCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = GenerateTextOnStepEndCallback<TTools, TRuntimeContext>;
+/**
+ * Callback function to be called after each step completes.
+ * Deprecated alias for `WorkflowAgentOnStepEndCallback`.
+ *
+ * @deprecated Use `WorkflowAgentOnStepEndCallback` instead.
+ */
+type WorkflowAgentOnStepFinishCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> = WorkflowAgentOnStepEndCallback<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.
  */
@@ -46,41 +60,12 @@ interface OutputSpecification<OUTPUT, PARTIAL> {
  * Provider-specific options type. This is equivalent to SharedV4ProviderOptions from @ai-sdk/provider.
  */
 type ProviderOptions = SharedV4ProviderOptions;
-/**
- * Telemetry settings for observability.
- */
-interface TelemetrySettings {
-    /**
-     * Enable or disable telemetry. Defaults to true.
-     */
-    isEnabled?: boolean;
-    /**
-     * Identifier for this function. Used to group telemetry data by function.
-     */
-    functionId?: string;
-    /**
-     * Additional information to include in the telemetry data.
-     */
-    metadata?: Record<string, string | number | boolean | Array<string | number | boolean> | null | undefined>;
-    /**
-     * Enable or disable input recording. Enabled by default.
-     *
-     * You might want to disable input recording to avoid recording sensitive
-     * information, to reduce data transfers, or to increase performance.
-     */
-    recordInputs?: boolean;
-    /**
-     * Enable or disable output recording. Enabled by default.
-     *
-     * You might want to disable output recording to avoid recording sensitive
-     * information, to reduce data transfers, or to increase performance.
-     */
-    recordOutputs?: boolean;
-    /**
-     * Custom tracer for the telemetry.
-     */
-    tracer?: unknown;
-}
+type WorkflowAgentToolsContextParameter<TTools extends ToolSet> = HasRequiredKey<InferToolSetContext<TTools>> extends true ? {
+    toolsContext: InferToolSetContext<TTools>;
+} : {
+    toolsContext?: never;
+};
+type TelemetryOptions<TRuntimeContext extends Context = Context, TTools extends ToolSet = ToolSet> = TelemetryOptions$1<TRuntimeContext, TTools>;
 /**
  * A transformation that is applied to the stream.
  */
@@ -176,12 +161,12 @@ 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.
      */
-    model: string | CompatibleLanguageModel | (() => Promise<CompatibleLanguageModel>);
+    model: LanguageModel;
     /**
      * The current step number (0-indexed).
      */
@@ -189,27 +174,35 @@ 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.
      */
-    experimental_context: unknown;
+    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.
+     */
+    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.
-     * The function should return a LanguageModelV4 instance.
      */
-    model?: string | CompatibleLanguageModel | (() => Promise<CompatibleLanguageModel>);
+    model?: LanguageModel;
     /**
      * Override the system message for this step.
      */
@@ -229,26 +222,39 @@ 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> {
-    model: string | CompatibleLanguageModel | (() => Promise<CompatibleLanguageModel>);
+interface PrepareCallOptions<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context> extends Partial<GenerationSettings> {
+    model: LanguageModel;
     tools: TTools;
-    instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
+    instructions?: Instructions;
     toolChoice?: ToolChoice<TTools>;
-    experimental_telemetry?: TelemetrySettings;
-    experimental_context?: unknown;
+    telemetry?: TelemetryOptions<TRuntimeContext, TTools>;
+    /**
+     * 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[];
 }
 /**
@@ -257,22 +263,26 @@ 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.
+     */
+    id?: string;
     /**
      * The model provider to use for the agent.
      *
      * This should be a string compatible with the Vercel AI Gateway (e.g., 'anthropic/claude-opus'),
-     * or a step function that returns a LanguageModelV4 instance.
+     * or a LanguageModelV4 instance from a provider.
      */
-    model: string | CompatibleLanguageModel | (() => Promise<CompatibleLanguageModel>);
+    model: LanguageModel;
     /**
      * A set of tools available to the agent.
      * Tools can be implemented as workflow steps for automatic retries and persistence,
@@ -283,7 +293,7 @@ interface WorkflowAgentOptions<TTools extends ToolSet = ToolSet> extends Generat
      * Agent instructions. Can be a string, a SystemModelMessage, or an array of SystemModelMessages.
      * Supports provider-specific options (e.g., caching) when using the SystemModelMessage form.
      */
-    instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
+    instructions?: Instructions;
     /**
      * Optional system prompt to guide the agent's behavior.
      * @deprecated Use `instructions` instead.
@@ -294,17 +304,56 @@ interface WorkflowAgentOptions<TTools extends ToolSet = ToolSet> extends Generat
      */
     toolChoice?: ToolChoice<TTools>;
     /**
-     * Optional telemetry configuration (experimental).
+     * Optional telemetry configuration.
      */
-    experimental_telemetry?: TelemetrySettings;
+    telemetry?: TelemetryOptions<TRuntimeContext, TTools>;
     /**
-     * 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.
      *
-     * Per-stream `experimental_context` values passed to `stream()` override this default.
-     * Experimental (can break in patch releases).
-     * @default undefined
+     * 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.
+     *
+     * 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.
+     *
+     * Per-stream `stopWhen` values passed to `stream()` override this default.
+     */
+    stopWhen?: StopCondition<NoInfer<ToolSet>, any> | Array<StopCondition<NoInfer<ToolSet>, any>>;
+    /**
+     * Default set of active tools that limits which tools the model can call,
+     * without changing the tool call and result types in the result.
+     *
+     * Per-stream `activeTools` values passed to `stream()` override this default.
+     */
+    activeTools?: ActiveTools<NoInfer<TTools>>;
+    /**
+     * Default output specification for structured outputs.
+     * Use `Output.object({ schema })` for structured output or `Output.text()` for text output.
+     *
+     * Per-stream `output` values passed to `stream()` override this default.
+     */
+    output?: OutputSpecification<any, any>;
+    /**
+     * Default function that attempts to repair a tool call that failed to parse.
+     *
+     * Per-stream `experimental_repairToolCall` values passed to `stream()` override this default.
+     */
+    experimental_repairToolCall?: ToolCallRepairFunction<TTools>;
+    /**
+     * Default custom download function to use for URLs.
+     *
+     * Per-stream `experimental_download` values passed to `stream()` override this default.
+     */
+    experimental_download?: DownloadFunction;
     /**
      * Default callback function called before each step in the agent loop.
      * Use this to modify settings, manage context, or inject messages dynamically
@@ -312,46 +361,58 @@ 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?: StreamTextOnStepFinishCallback<ToolSet, any>;
+    onStepEnd?: WorkflowAgentOnStepEndCallback<TTools, TRuntimeContext>;
+    /**
+     * Callback function to be called after each step completes.
+     *
+     * @deprecated Use `onStepEnd` instead.
+     */
+    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools, TRuntimeContext>;
     /**
      * Callback that is called when the LLM response and all request tool executions are finished.
      */
-    onFinish?: StreamTextOnFinishCallback<ToolSet>;
+    onEnd?: WorkflowAgentOnEndCallback<TTools, TRuntimeContext>;
+    /**
+     * Callback that is called when the LLM response and all request tool executions are finished.
+     *
+     * @deprecated Use `onEnd` instead.
+     */
+    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.
      */
-    experimental_onToolCallStart?: WorkflowAgentOnToolCallStartCallback;
+    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback<TTools>;
     /**
      * Callback called after a tool execution completes.
      */
-    experimental_onToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
+    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 StreamTextOnFinishCallback<TTools extends ToolSet = ToolSet, OUTPUT = never> = (event: {
+type WorkflowAgentOnEndCallback<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.
      */
@@ -364,30 +425,44 @@ type StreamTextOnFinishCallback<TTools extends ToolSet = ToolSet, OUTPUT = never
      * The finish reason from the last step.
      */
     readonly finishReason: FinishReason;
+    /**
+     * The total token usage across all steps.
+     */
+    readonly usage: LanguageModelUsage;
     /**
      * The total token usage across all steps.
      */
     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.
      */
     readonly output: OUTPUT;
 }) => PromiseLike<void> | void;
+/**
+ * Callback that is called when the LLM response and all request tool executions are finished.
+ *
+ * @deprecated Use `WorkflowAgentOnEndCallback` instead.
+ */
+type WorkflowAgentOnFinishCallback<TTools extends ToolSet = ToolSet, TRuntimeContext extends Context = Context, OUTPUT = never> = WorkflowAgentOnEndCallback<TTools, TRuntimeContext, OUTPUT>;
 /**
  * Callback that is invoked when an error occurs during streaming.
  */
-type StreamTextOnErrorCallback = (event: {
+type WorkflowAgentOnErrorCallback = (event: {
     error: unknown;
 }) => PromiseLike<void> | void;
 /**
  * Callback that is set using the `onAbort` option.
  */
-type StreamTextOnAbortCallback<TTools extends ToolSet = ToolSet> = (event: {
+type WorkflowAgentOnAbortCallback<TTools extends ToolSet = ToolSet> = (event: {
     /**
      * Details for all previously finished steps.
      */
@@ -396,49 +471,114 @@ type StreamTextOnAbortCallback<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: string | CompatibleLanguageModel | (() => Promise<CompatibleLanguageModel>);
+    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 = (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 */
-    readonly model: string | CompatibleLanguageModel | (() => Promise<CompatibleLanguageModel>);
+    readonly model: LanguageModel;
     /** The messages being sent for this step */
     readonly messages: ModelMessage[];
+    /** Results from all previously finished steps */
+    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 WorkflowAgentOnToolCallStartCallback = (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 WorkflowAgentOnToolCallFinishCallback = (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 */
+    readonly output: unknown;
+    readonly error?: never;
+} | {
     /** The tool call that was executed */
     readonly toolCall: ToolCall;
-    /** The tool result (undefined if execution failed) */
-    readonly result?: unknown;
-    /** The error if execution failed */
-    readonly error?: unknown;
+    /** 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: false;
+    /** The error that occurred */
+    readonly error: unknown;
+    readonly output?: never;
 }) => PromiseLike<void> | void;
 /**
  * Options for the {@link WorkflowAgent.stream} method.
  */
-interface WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never> extends 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.
+     *
+     * You can either use `prompt` or `messages` but not both.
+     */
+    prompt: string | Array<ModelMessage>;
+    /**
+     * A list of messages.
+     *
+     * You can either use `prompt` or `messages` but not both.
+     */
+    messages?: never;
+} | {
     /**
      * The conversation messages to process. Should follow the AI SDK's ModelMessage format.
+     *
+     * You can either use `prompt` or `messages` but not both.
      */
-    messages: ModelMessage[];
+    messages: Array<ModelMessage>;
+    /**
+     * A prompt. It can be either a text prompt or a list of messages.
+     *
+     * You can either use `prompt` or `messages` but not both.
+     */
+    prompt?: never;
+}) & {
     /**
      * Optional system prompt override. If provided, overrides the system prompt from the constructor.
      */
@@ -471,12 +611,6 @@ interface WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT =
      * When the condition is an array, any of the conditions can be met to stop the generation.
      */
     stopWhen?: StopCondition<NoInfer<ToolSet>, any> | Array<StopCondition<NoInfer<ToolSet>, any>>;
-    /**
-     * Maximum number of sequential LLM calls (steps), e.g. when you use tool calls.
-     * A maximum number can be set to prevent infinite loops in the case of misconfigured tools.
-     * By default, it's unlimited (the agent loops until completion).
-     */
-    maxSteps?: number;
     /**
      * The tool choice strategy. Default: 'auto'.
      * Overrides the toolChoice from the constructor if provided.
@@ -486,17 +620,34 @@ interface WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT =
      * Limits the tools that are available for the model to call without
      * changing the tool call and result types in the result.
      */
-    activeTools?: Array<keyof NoInfer<TTools>>;
+    activeTools?: ActiveTools<NoInfer<TTools>>;
     /**
-     * Optional telemetry configuration (experimental).
+     * Optional telemetry configuration.
      */
-    experimental_telemetry?: TelemetrySettings;
+    telemetry?: TelemetryOptions<TRuntimeContext, TTools>;
     /**
-     * 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.
      */
-    experimental_context?: unknown;
+    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.
+     */
+    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.
@@ -546,37 +697,50 @@ interface WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT =
     /**
      * Callback function to be called after each step completes.
      */
-    onStepFinish?: StreamTextOnStepFinishCallback<TTools, any>;
+    onStepEnd?: WorkflowAgentOnStepEndCallback<TTools, TRuntimeContext>;
+    /**
+     * Callback function to be called after each step completes.
+     *
+     * @deprecated Use `onStepEnd` instead.
+     */
+    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools, TRuntimeContext>;
     /**
      * Callback that is invoked when an error occurs during streaming.
      * You can use it to log errors.
      */
-    onError?: StreamTextOnErrorCallback;
+    onError?: WorkflowAgentOnErrorCallback;
+    /**
+     * Callback that is called when the LLM response and all request tool executions
+     * (for tools that have an `execute` function) are finished.
+     */
+    onEnd?: WorkflowAgentOnEndCallback<TTools, TRuntimeContext, OUTPUT>;
     /**
      * Callback that is called when the LLM response and all request tool executions
      * (for tools that have an `execute` function) are finished.
+     *
+     * @deprecated Use `onEnd` instead.
      */
-    onFinish?: StreamTextOnFinishCallback<TTools, OUTPUT>;
+    onFinish?: WorkflowAgentOnFinishCallback<TTools, TRuntimeContext, OUTPUT>;
     /**
      * Callback that is called when the operation is aborted.
      */
-    onAbort?: StreamTextOnAbortCallback<TTools>;
+    onAbort?: WorkflowAgentOnAbortCallback<TTools>;
     /**
      * 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.
      */
-    experimental_onToolCallStart?: WorkflowAgentOnToolCallStartCallback;
+    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback<TTools>;
     /**
      * Callback called after a tool execution completes.
      */
-    experimental_onToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
+    onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback<TTools>;
     /**
      * Callback function called before each step in the agent loop.
      * Use this to modify settings, manage context, or inject messages dynamically.
@@ -595,7 +759,7 @@ interface WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT =
      * }
      * ```
      */
-    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.
@@ -612,7 +776,7 @@ interface WorkflowAgentStreamOptions<TTools extends ToolSet = ToolSet, OUTPUT =
      * @default false
      */
     preventClose?: boolean;
-}
+};
 /**
  * A tool call made by the model. Matches the AI SDK's tool call shape.
  */
@@ -711,7 +875,11 @@ 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.
+     */
+    readonly id: string | undefined;
     private model;
     /**
      * The tool set configured for this agent.
@@ -721,18 +889,24 @@ 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?;
+    private experimentalRepairToolCall?;
+    private experimentalDownload?;
     private prepareStep?;
-    private constructorOnStepFinish?;
-    private constructorOnFinish?;
+    private constructorOnStepEnd?;
+    private constructorOnEnd?;
     private constructorOnStart?;
     private constructorOnStepStart?;
-    private constructorOnToolCallStart?;
-    private constructorOnToolCallFinish?;
+    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>>;
 }
 
 /**
@@ -901,4 +1075,4 @@ declare class WorkflowChatTransport<UI_MESSAGE extends UIMessage> implements Cha
     private onFinish;
 }
 
-export { type CompatibleLanguageModel, type DownloadFunction, type GenerationSettings, type InferWorkflowAgentTools, type InferWorkflowAgentUIMessage, type OutputSpecification, type PrepareCallCallback, type PrepareCallOptions, type PrepareCallResult, type PrepareStepCallback, type PrepareStepInfo, type PrepareStepResult, type ProviderOptions, type ReconnectToStreamOptions, type SendMessagesOptions, type StreamTextOnAbortCallback, type StreamTextOnErrorCallback, type StreamTextOnFinishCallback, type StreamTextTransform, type TelemetrySettings, WorkflowAgent, type WorkflowAgentOnStartCallback, type WorkflowAgentOnStepStartCallback, type WorkflowAgentOnToolCallFinishCallback, type WorkflowAgentOnToolCallStartCallback, type WorkflowAgentOptions, type WorkflowAgentStreamOptions, type WorkflowAgentStreamResult, WorkflowChatTransport, type WorkflowChatTransportOptions, createModelCallToUIChunkTransform, toUIMessageChunk };
+export { type CompatibleLanguageModel, type DownloadFunction, type GenerationSettings, type InferWorkflowAgentTools, type InferWorkflowAgentUIMessage, type OutputSpecification, type PrepareCallCallback, type PrepareCallOptions, type PrepareCallResult, type PrepareStepCallback, type PrepareStepInfo, type PrepareStepResult, type ProviderOptions, type ReconnectToStreamOptions, type SendMessagesOptions, type StreamTextTransform, type TelemetryOptions, WorkflowAgent, type WorkflowAgentOnAbortCallback, type WorkflowAgentOnEndCallback, type WorkflowAgentOnErrorCallback, type WorkflowAgentOnFinishCallback, type WorkflowAgentOnStartCallback, type WorkflowAgentOnStepEndCallback, type WorkflowAgentOnStepFinishCallback, type WorkflowAgentOnStepStartCallback, type WorkflowAgentOnToolExecutionEndCallback, type WorkflowAgentOnToolExecutionStartCallback, type WorkflowAgentOptions, type WorkflowAgentStreamOptions, type WorkflowAgentStreamResult, WorkflowChatTransport, type WorkflowChatTransportOptions, createModelCallToUIChunkTransform, toUIMessageChunk };