ai 7.0.0-beta.111 → 7.0.0-beta.113

package/docs/02-foundations/03-prompts.mdx

@@ -45,6 +45,14 @@ const result = await generateText({
 System prompts are the initial set of instructions given to models that help guide and constrain the models' behaviors and responses.
 You can set system prompts using the `system` property.
 System prompts work with both the `prompt` and the `messages` properties.
+System messages in `prompt` or `messages` are rejected by default; use the `system` property for system instructions, or set `allowSystemInMessages: true` when you need to send existing message histories that contain system messages.
+
+<Note type="warning">
+  Opting in with `allowSystemInMessages` can create a prompt injection risk
+  where users can override or set the system prompt by injecting system
+  messages. In most cases, only trusted server-side code should set system
+  instructions via the `system` or `instructions` property.
+</Note>
 
 ```ts highlight="3-6"
 const result = await generateText({
@@ -59,11 +67,6 @@ const result = await generateText({
 });
 ```
 
-<Note>
-  When you use a message prompt, you can also use system messages instead of a
-  system prompt.
-</Note>
-
 ## Message Prompts
 
 A message prompt is an array of user, assistant, and tool messages.
@@ -118,10 +121,9 @@ const { text } = await generateText({
 For granular control over applying provider options at the message level, you can pass `providerOptions` to the message object:
 
 ```ts
-import { ModelMessage } from 'ai';
-
-const messages: ModelMessage[] = [
-  {
+const result = await generateText({
+  model: __MODEL__,
+  system: {
     role: 'system',
     content: 'Cached system message',
     providerOptions: {
@@ -129,7 +131,8 @@ const messages: ModelMessage[] = [
       anthropic: { cacheControl: { type: 'ephemeral' } },
     },
   },
-];
+  prompt: 'Invent a new holiday and describe its traditions.',
+});
 ```
 
 #### Message Part Level

package/docs/03-agents/01-overview.mdx

@@ -15,6 +15,21 @@ These components work together:
   - **Context management** - Maintaining conversation history and deciding what the model sees (input) at each step
   - **Stopping conditions** - Determining when the loop (task) is complete
 
+## Agent State and Context
+
+Agents often need server-side state that should not be placed directly in the
+prompt, such as tenant settings, request IDs, feature flags, credentials, or
+progress through a task.
+
+Use `runtimeContext` as the agent's shared runtime state. It flows through the
+agent loop, is available in `prepareStep` and lifecycle callbacks, and can be
+updated between steps. Use `toolsContext` for per-tool values such as API keys
+or scoped permissions; each tool receives only its own typed `context` based on
+its `contextSchema`.
+
+Learn more in [Runtime and Tool
+Context](/docs/ai-sdk-core/runtime-and-tool-context).
+
 ## ToolLoopAgent Class
 
 The ToolLoopAgent class handles these three components. Here's an agent that uses multiple tools in a loop to accomplish a task:
@@ -90,5 +105,6 @@ Agents are flexible and powerful, but non-deterministic. When you need reliable,
 ## Next Steps
 
 - **[Building Agents](/docs/agents/building-agents)** - Guide to creating agents with the ToolLoopAgent
+- **[Runtime and Tool Context](/docs/ai-sdk-core/runtime-and-tool-context)** - How to pass shared agent state and per-tool context
 - **[Workflow Patterns](/docs/agents/workflows)** - Structured patterns using core functions for complex workflows
 - **[Loop Control](/docs/agents/loop-control)** - Execution control with stopWhen and prepareStep

package/docs/03-agents/02-building-agents.mdx

@@ -77,9 +77,73 @@ const codeAgent = new ToolLoopAgent({
 });
 ```
 
-You can also require approval before a tool executes. Use `needsApproval` on the
-tool itself for the default behavior, or set `toolNeedsApproval` on the
-`ToolLoopAgent` when approval should be configured per agent:
+### Context and Agent State
+
+Use `runtimeContext` as the agent's shared runtime state. It flows through the
+agent loop and is available in `prepareStep`, lifecycle callbacks, and final
+results. If a tool needs server-side values such as credentials, scoped
+permissions, or default settings, pass them through `toolsContext` and declare
+them with the tool's `contextSchema`.
+
+```ts highlight="8-15,21-31,37-49"
+import { ToolLoopAgent, tool } from 'ai';
+import { z } from 'zod';
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    searchTickets: tool({
+      description: 'Search support tickets',
+      inputSchema: z.object({
+        query: z.string(),
+      }),
+      contextSchema: z.object({
+        apiKey: z.string(),
+        accountId: z.string(),
+      }),
+      execute: async ({ query }, { context }) =>
+        searchTickets(query, context.accountId, context.apiKey),
+    }),
+  },
+  prepareStep: async ({ runtimeContext }) => {
+    if (runtimeContext.escalated) {
+      return { temperature: 0.1 };
+    }
+
+    return {};
+  },
+});
+
+const result = await agent.generate({
+  prompt: 'Find open billing tickets for this account.',
+  runtimeContext: {
+    requestId: 'req_abc',
+    escalated: false,
+  },
+  toolsContext: {
+    searchTickets: {
+      apiKey: process.env.SUPPORT_API_KEY!,
+      accountId: 'acct_123',
+    },
+  },
+});
+```
+
+For the full model, including sensitive context filtering and where each context
+value is available, see [Runtime and Tool
+Context](/docs/ai-sdk-core/runtime-and-tool-context).
+
+You can also require approval before a tool executes. Configure approval on the
+`ToolLoopAgent` with `toolApproval`. The older `needsApproval` property on
+tools is deprecated for `ToolLoopAgent`. `toolApproval` can be a
+`GenericToolApprovalFunction` (one callback for every tool call) or a per-tool
+object of statuses and/or `SingleToolApprovalFunction` handlers. For the
+default execution path, use `'not-applicable'` or return `undefined` from an
+approval function. Use `'user-approval'` for manual review, or `'approved'` /
+`'denied'` when you want explicit automatic approval records in the output. For
+automatic approvals and denials, you can also return an object such as
+`{ type: 'denied', reason: 'blocked by policy' }` to attach a reason to the
+approval response:
 
 ```ts
 const agent = new ToolLoopAgent({
@@ -93,8 +157,8 @@ const agent = new ToolLoopAgent({
       execute: async ({ code }) => ({ output: code }),
     }),
   },
-  toolNeedsApproval: {
-    runCode: true,
+  toolApproval: {
+    runCode: 'user-approval',
   },
 });
 ```
@@ -364,21 +428,21 @@ These are useful for logging, observability, debugging, and custom telemetry.
 const result = await myAgent.generate({
   prompt: 'Research and summarize the latest AI trends',
 
-  experimental_onStart({ model, functionId }) {
-    console.log('Agent started', { model: model.modelId, functionId });
+  experimental_onStart({ modelId }) {
+    console.log('Agent started', { modelId });
   },
 
-  experimental_onStepStart({ stepNumber, model }) {
-    console.log(`Step ${stepNumber} starting`, { model: model.modelId });
+  experimental_onStepStart({ stepNumber, modelId }) {
+    console.log(`Step ${stepNumber} starting`, { modelId });
   },
 
   experimental_onToolExecutionStart({ toolCall }) {
     console.log(`Tool call starting: ${toolCall.toolName}`);
   },
 
-  experimental_onToolExecutionEnd({ toolCall, durationMs, success }) {
+  experimental_onToolExecutionEnd({ toolCall, durationMs, toolOutput }) {
     console.log(`Tool call finished: ${toolCall.toolName} (${durationMs}ms)`, {
-      success,
+      success: toolOutput.type === 'tool-result',
     });
   },
 
@@ -402,10 +466,10 @@ const result = await myAgent.generate({
 
 The available lifecycle callbacks are:
 
-- **`experimental_onStart`**: Called once when the agent operation begins, before any LLM calls. Receives model info, prompt, settings, and `runtimeContext`.
+- **`experimental_onStart`**: Called once when the agent operation begins, before any LLM calls. Receives model info, messages, settings, and `runtimeContext`.
 - **`experimental_onStepStart`**: Called before each step (LLM call). Receives the step number, model, messages being sent, tools, and prior steps.
-- **`experimental_onToolExecutionStart`**: Called right before a tool's `execute` function runs. Receives the tool call object with tool name, call ID, and input.
-- **`experimental_onToolExecutionEnd`**: Called right after a tool's `execute` function completes or errors. Receives the tool call, `durationMs`, and a `success` discriminator (`output` when successful, `error` when failed).
+- **`experimental_onToolExecutionStart`**: Called right before a tool's `execute` function runs. Receives the tool call object, messages, and `toolContext`.
+- **`experimental_onToolExecutionEnd`**: Called right after a tool's `execute` function completes or errors. Receives the tool call, `durationMs`, and a `toolOutput` discriminated union (`type: 'tool-result'` with `output`, or `type: 'tool-error'` with `error`).
 - **`onStepFinish`**: Called after each step finishes. Receives step results including usage, finish reason, and tool calls.
 - **`onFinish`**: Called when all steps are finished and the response is complete. Receives all step results, total usage, and `runtimeContext`.
 

package/docs/03-agents/06-subagents.mdx

@@ -334,7 +334,9 @@ export function Chat() {
 
 ### No Tool Approvals in Subagents
 
-Subagent tools cannot use `needsApproval`. All tools must execute automatically without user confirmation.
+Subagent tools cannot use approval flows such as `toolApproval` (or the
+deprecated `needsApproval`). All tools must execute automatically without user
+confirmation.
 
 ### Subagent Context is Isolated
 

package/docs/03-agents/07-workflow-agent.mdx

@@ -302,7 +302,11 @@ Tools without `'use step'` still work but run as regular in-memory functions wit
 
 ## Tool Approval
 
-Tools can require human approval before execution. When a tool has `needsApproval` set, the agent pauses and emits an approval request to the writable stream. The workflow suspends until the user approves or denies:
+For `WorkflowAgent`, human approval is configured on the tool definition with
+`needsApproval`. This is specific to `WorkflowAgent`; for `generateText`,
+`streamText`, and `ToolLoopAgent`, use `toolApproval` instead. When a workflow
+tool has `needsApproval` set, the agent pauses and emits an approval request to
+the writable stream. The workflow suspends until the user approves or denies:
 
 ```ts
 const agent = new WorkflowAgent({
@@ -426,7 +430,7 @@ Agents provide lifecycle callbacks for logging, observability, and custom teleme
 const agent = new WorkflowAgent({
   model: "anthropic/claude-sonnet-4-6",
 
-  experimental_onStart({ model, messages }) {
+  experimental_onStart({ modelId, messages }) {
     console.log("Agent started");
   },
 
@@ -438,7 +442,7 @@ const agent = new WorkflowAgent({
     console.log(`Calling tool: ${toolCall.toolName}`);
   },
 
-  experimental_onToolExecutionEnd({ toolCall, result, error }) {
+  experimental_onToolExecutionEnd({ toolCall, toolOutput }) {
     console.log(`Tool finished: ${toolCall.toolName}`);
   },
 
@@ -466,6 +470,129 @@ const myAgent = new WorkflowAgent({
 export type MyAgentUIMessage = InferWorkflowAgentUIMessage<typeof myAgent>;
 ```
 
+## Migrating from `DurableAgent`
+
+`WorkflowAgent` replaces the Workflow DevKit's [`DurableAgent`](https://workflow-sdk.dev/docs/api-reference/workflow-ai/durable-agent). The two share the same core idea — a durable agent loop that runs inside a workflow — but `WorkflowAgent` moves the class into the AI SDK, tightens typing, and introduces first-class tool approval. If you are using `DurableAgent` today, follow the steps below to switch.
+
+### Change the import and class name
+
+`DurableAgent` was exported from `workflow/ai`. `WorkflowAgent` is exported from `@ai-sdk/workflow`, alongside its helpers.
+
+```diff
+- import { DurableAgent } from 'workflow/ai';
++ import { WorkflowAgent, type ModelCallStreamPart } from '@ai-sdk/workflow';
+
+- const agent = new DurableAgent({
++ const agent = new WorkflowAgent({
+    model: 'anthropic/claude-sonnet-4-6',
+    instructions: 'You are a helpful assistant.',
+    tools: { /* ... */ },
+  });
+```
+
+Install the new package alongside `workflow`:
+
+```bash
+npm install @ai-sdk/workflow
+```
+
+### Write `ModelCallStreamPart`, not `UIMessageChunk`
+
+`DurableAgent` wrote `UIMessageChunk` objects directly to the writable returned by `getWritable()`. `WorkflowAgent` writes the lower-level `ModelCallStreamPart` shape and leaves the conversion to a transform at the response boundary. This keeps the durable stream provider-shaped and avoids baking a UI protocol into the workflow payload.
+
+```diff
+  // Inside the workflow
+  await agent.stream({
+    messages,
+-   writable: getWritable<UIMessageChunk>(),
++   writable: getWritable<ModelCallStreamPart>(),
+  });
+```
+
+```diff
+  // Inside the route handler
++ import { createModelCallToUIChunkTransform } from '@ai-sdk/workflow';
+
+  return createUIMessageStreamResponse({
+-   stream: run.readable,
++   stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()),
+  });
+```
+
+### Replace `maxSteps` with `stopWhen`
+
+`DurableAgent` accepted `maxSteps` directly. `WorkflowAgent` uses the AI SDK's shared `stopWhen` conditions so the same stop logic works across `ToolLoopAgent`, `generateText`, and `streamText`.
+
+```diff
++ import { isStepCount } from 'ai';
+
+  await agent.stream({
+    messages,
+-   maxSteps: 10,
++   stopWhen: isStepCount(10),
+  });
+```
+
+See [Loop Control](/docs/agents/loop-control) for the full list of stop conditions.
+
+### Replace `experimental_output` with `output`
+
+```diff
++ import { Output } from '@ai-sdk/workflow';
+
+  await agent.stream({
+    messages,
+-   experimental_output: Output.object({ schema }),
++   output: Output.object({ schema }),
+  });
+```
+
+The returned value is now on `result.output` (previously `result.experimental_output`).
+
+### WorkflowAgent: Use `needsApproval` for human-in-the-loop tools
+
+With `DurableAgent`, tool approval was implemented by calling a Hook from inside the tool's `execute` function. `WorkflowAgent` makes approval a first-class tool property — the agent emits the approval request, suspends the workflow, and resumes automatically when the user responds.
+
+```diff
+  bookFlight: tool({
+    description: 'Book a flight',
+    inputSchema: z.object({ flightId: z.string() }),
++   needsApproval: true,
+-   execute: async (input) => {
+-     const approved = await waitForApprovalHook(input);
+-     if (!approved) throw new Error('Denied');
+-     return bookFlightStep(input);
+-   },
++   execute: bookFlightStep,
+  }),
+```
+
+`needsApproval` also accepts an async function so you can decide per-input
+whether approval is required (see [Tool Approval](#tool-approval) above).
+
+### `uiMessages` / `collectUIMessages` is gone
+
+`DurableAgent.stream()` returned accumulated `uiMessages` when `collectUIMessages: true` was set. `WorkflowAgent.stream()` returns `ModelMessage[]` on `result.messages` instead — persist those and convert them at the edge with `convertToModelMessages` / `convertToUIMessages` as needed.
+
+```diff
+  const result = await agent.stream({
+    messages,
+    writable: getWritable<ModelCallStreamPart>(),
+-   collectUIMessages: true,
+  });
+
+- return { uiMessages: result.uiMessages };
++ return { messages: result.messages };
+```
+
+### No `generate()` method
+
+`WorkflowAgent` only exposes `stream()`. If you were calling `agent.generate()`, switch to `stream()` and read `result.messages` / `result.output` once the promise resolves.
+
+### Everything else
+
+Other options carry over with the same names: `prepareStep`, `onStepFinish`, `onFinish`, `onError`, `toolChoice`, `activeTools`, `timeout`, `experimental_context`, `experimental_repairToolCall`, and the usual generation settings (`temperature`, `maxOutputTokens`, `topP`, …). `WorkflowAgent` additionally adds `prepareCall` (runs once before the loop) and the `experimental_onStart` / `experimental_onStepStart` / `experimental_onToolExecutionStart` / `experimental_onToolExecutionEnd` lifecycle callbacks documented above.
+
 ## Next Steps
 
 - [WorkflowAgent API Reference](/docs/reference/ai-sdk-workflow/workflow-agent) for detailed parameter documentation

package/docs/03-agents/index.mdx

@@ -11,12 +11,14 @@ The following section shows you how to build agents with the AI SDK - systems wh
   cards={[
     {
       title: 'Overview',
-      description: 'Learn what agents are and why to use the ToolLoopAgent.',
+      description:
+        'Learn what agents are, how they manage state, and why to use the ToolLoopAgent.',
       href: '/docs/agents/overview',
     },
     {
       title: 'Building Agents',
-      description: 'Complete guide to creating agents with the ToolLoopAgent.',
+      description:
+        'Create ToolLoopAgent instances with tools, runtime context, and loop control.',
       href: '/docs/agents/building-agents',
     },
     {

package/docs/03-ai-sdk-core/05-generating-text.mdx

@@ -127,21 +127,35 @@ const result = await generateText({
     // ... your tools
   },
 
-  experimental_onStart({ model, settings, functionId }) {
-    console.log('Generation started', { model, functionId });
+  experimental_onStart({ modelId }) {
+    console.log('Generation started', { modelId });
   },
 
-  experimental_onStepStart({ stepNumber, model, promptMessages }) {
-    console.log(`Step ${stepNumber} starting`, { model: model.modelId });
+  experimental_onStepStart({ stepNumber, modelId, messages }) {
+    console.log(`Step ${stepNumber} starting`, { modelId });
   },
 
-  experimental_onToolExecutionStart({ toolName, toolCallId, input }) {
-    console.log(`Tool call starting: ${toolName}`, { toolCallId });
+  experimental_onLanguageModelCallStart({ modelId, messages }) {
+    console.log('Model call starting', { modelId, messageCount: messages.length });
   },
 
-  experimental_onToolExecutionEnd({ toolName, durationMs, error }) {
-    console.log(`Tool call finished: ${toolName} (${durationMs}ms)`, {
-      success: !error,
+  experimental_onLanguageModelCallEnd({ modelId, finishReason, content }) {
+    console.log('Model call finished', {
+      modelId,
+      finishReason,
+      contentParts: content.length,
+    });
+  },
+
+  experimental_onToolExecutionStart({ toolCall }) {
+    console.log(`Tool call starting: ${toolCall.toolName}`, {
+      toolCallId: toolCall.toolCallId,
+    });
+  },
+
+  experimental_onToolExecutionEnd({ toolCall, durationMs, toolOutput }) {
+    console.log(`Tool call finished: ${toolCall.toolName} (${durationMs}ms)`, {
+      success: toolOutput.type === 'tool-result',
     });
   },
 
@@ -153,11 +167,13 @@ const result = await generateText({
 
 The available lifecycle callbacks are:
 
-- **`experimental_onStart`**: Called once when the `generateText` operation begins, before any LLM calls. Receives model info, prompt, settings, and `runtimeContext`.
-- **`experimental_onStepStart`**: Called before each step (LLM call). Receives the step number, model, prompt messages being sent, tools, and prior steps.
-- **`experimental_onToolExecutionStart`**: Called right before a tool's `execute` function runs. Receives the tool name, call ID, and input.
-- **`experimental_onToolExecutionEnd`**: Called right after a tool's `execute` function completes or errors. Receives the tool name, call ID, input, output (or undefined on error), error (or undefined on success), and `durationMs`.
-- **`onStepFinish`**: Called after each step finishes. Now also includes `stepNumber` (zero-based index of the completed step).
+- **`experimental_onStart`**: Called once when the `generateText` operation begins, before any LLM calls. Receives model info, messages, settings, and `runtimeContext`.
+- **`experimental_onStepStart`**: Called before each step (LLM call). Receives the step number, model, messages being sent, tools, and prior steps.
+- **`experimental_onLanguageModelCallStart`**: Called immediately before the provider model call begins. Useful when you want to observe the model invocation separately from later tool execution.
+- **`experimental_onLanguageModelCallEnd`**: Called after the model response has been normalized and parsed, but before any client-side tool execution begins. Receives the model-call content parts, usage, and finish reason.
+- **`experimental_onToolExecutionStart`**: Called right before a tool's `execute` function runs. Receives the tool call object, messages, and `toolContext`.
+- **`experimental_onToolExecutionEnd`**: Called right after a tool's `execute` function completes or errors. Receives the tool call object, `durationMs`, and a `toolOutput` discriminated union (`type: 'tool-result'` with `output`, or `type: 'tool-error'` with `error`).
+- **`onStepFinish`**: Called after each step finishes. Includes `stepNumber` (zero-based index of the completed step).
 
 ## `streamText`
 
@@ -319,12 +335,24 @@ const result = streamText({
     // ... your tools
   },
 
-  experimental_onStart({ model, system, prompt, messages }) {
-    console.log('Streaming started', { model, prompt });
+  experimental_onStart({ modelId, system, messages }) {
+    console.log('Streaming started', { modelId });
+  },
+
+  experimental_onStepStart({ stepNumber, modelId, messages }) {
+    console.log(`Step ${stepNumber} starting`, { modelId });
+  },
+
+  experimental_onLanguageModelCallStart({ modelId, messages }) {
+    console.log('Model call starting', { modelId, messageCount: messages.length });
   },
 
-  experimental_onStepStart({ stepNumber, model, messages }) {
-    console.log(`Step ${stepNumber} starting`, { model: model.modelId });
+  experimental_onLanguageModelCallEnd({ modelId, finishReason, content }) {
+    console.log('Model call finished', {
+      modelId,
+      finishReason,
+      contentParts: content.length,
+    });
   },
 
   experimental_onToolExecutionStart({ toolCall }) {
@@ -333,9 +361,9 @@ const result = streamText({
     });
   },
 
-  experimental_onToolExecutionEnd({ toolCall, durationMs, success, error }) {
+  experimental_onToolExecutionEnd({ toolCall, durationMs, toolOutput }) {
     console.log(`Tool call finished: ${toolCall.toolName} (${durationMs}ms)`, {
-      success,
+      success: toolOutput.type === 'tool-result',
     });
   },
 
@@ -347,10 +375,12 @@ const result = streamText({
 
 The available lifecycle callbacks are:
 
-- **`experimental_onStart`**: Called once when the `streamText` operation begins, before any LLM calls. Receives model info, prompt, settings, and `runtimeContext`.
+- **`experimental_onStart`**: Called once when the `streamText` operation begins, before any LLM calls. Receives model info, messages, settings, and `runtimeContext`.
 - **`experimental_onStepStart`**: Called before each step (LLM call). Receives the step number, model, messages being sent, tools, and prior steps.
-- **`experimental_onToolExecutionStart`**: Called right before a tool's `execute` function runs. Receives the tool call object, messages, and the tool-specific context for that call.
-- **`experimental_onToolExecutionEnd`**: Called right after a tool's `execute` function completes or errors. Receives the tool call object, `durationMs`, and a discriminated union with `success`/`output` or `success`/`error`.
+- **`experimental_onLanguageModelCallStart`**: Called immediately before the provider model call begins. Useful when you want to observe the model invocation separately from later tool execution.
+- **`experimental_onLanguageModelCallEnd`**: Called after the model response has been normalized and parsed, but before any client-side tool execution begins. Receives the model-call content parts, usage, and finish reason.
+- **`experimental_onToolExecutionStart`**: Called right before a tool's `execute` function runs. Receives the tool call object, messages, and `toolContext`.
+- **`experimental_onToolExecutionEnd`**: Called right after a tool's `execute` function completes or errors. Receives the tool call object, `durationMs`, and a `toolOutput` discriminated union (`type: 'tool-result'` with `output`, or `type: 'tool-error'` with `error`).
 - **`onStepFinish`**: Called after each step finishes. Receives the finish reason, usage, and other step details.
 
 ### `fullStream` property