ai 7.0.37 → 7.0.39

package/docs/03-ai-sdk-harnesses/06-workflow-utilities.mdx

@@ -8,29 +8,35 @@ description: Run HarnessAgent turns as durable Workflow DevKit workflows.
 `@ai-sdk/workflow-harness` provides helpers for running `HarnessAgent` turns
 inside a [workflow](https://vercel.com/docs/workflow).
 
-The package provides a serializable state machine and a slice runner that you
-call from your own `'use workflow'` and `'use step'` functions.
+The package provides a serializable state machine and runners for time-sliced
+and semantic agent step turns. You call the appropriate runner from your own
+`'use workflow'` and `'use step'` functions.
 
-The core harness and workflow files are framework-independent. The HTTP handler
-and Next.js configuration shown below are examples of how to expose the workflow
-from one app framework; adapt those parts to your runtime and Workflow SDK
-integration.
+The core harness and workflow files are framework-independent. The HTTP handlers
+shown below use Next.js as one example; adapt them to your runtime and Workflow
+SDK integration. If you use Next.js, ensure you have
+[configured your project for Workflow](https://workflow-sdk.dev/docs/getting-started/next)
+before following the examples.
 
 ## Installation
 
 <InstallPackages packages="@ai-sdk/workflow-harness workflow" />
 
-Install the core harness package, a harness adapter, and a sandbox provider as
-shown in [HarnessAgent](/docs/ai-sdk-harnesses/harness-agent).
+In addition to the workflow specific packages, install the core harness package,
+a harness adapter, and a sandbox provider as shown in
+[HarnessAgent](/docs/ai-sdk-harnesses/harness-agent).
 
-## Using a Durable Harness Agent
+## Configuring the Harness Agent
 
-The agent can be configured in the usual way.
+The agent can be configured in the usual way, for the most part. When using
+semantic agent steps, set `stopWhen` to `isStepCount(1)` so one call to
+`stream()` completes one agent step. Omit it when using time slices.
 
-```ts filename='harness-workflow/agent.ts'
+```ts filename='harness-workflow/agent.ts' highlight="13-17"
 import { HarnessAgent } from '@ai-sdk/harness/agent';
 import { claudeCode } from '@ai-sdk/harness-claude-code';
 import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
+import { isStepCount } from 'ai';
 
 export const agent = new HarnessAgent({
   harness: claudeCode,
@@ -39,92 +45,210 @@ export const agent = new HarnessAgent({
     ports: [4000],
   }),
   instructions: 'You are a helpful coding assistant.',
+  /*
+   * Only needed for semantic agent-step workflows.
+   * Omit this for time-sliced workflows.
+   */
+  stopWhen: isStepCount(1),
 });
 ```
 
-With the agent definition file in place, start with the two workflow-specific
-pieces: a slice step that runs one time-boxed part of the harness turn, and a
-workflow that calls that step until the turn finishes.
+## Using Semantic Agent Steps
 
-```ts filename='harness-workflow/run-slice-step.ts'
+Semantic agent steps persist the harness turn after each agent step. Configure
+the shared agent with the highlighted `stopWhen` option shown above, then call
+`runHarnessAgentStep()` from a Workflow step.
+
+### Defining the Agent Step
+
+Keep the Workflow step in its own module and import the agent dynamically inside
+the step body. This keeps the agent, sandbox provider, and other Node.js
+dependencies out of the workflow bundle.
+
+```ts filename='harness-workflow/agent-step.ts'
 import {
-  runHarnessAgentSlice,
+  runHarnessAgentStep,
   type HarnessWorkflowState,
 } from '@ai-sdk/workflow-harness';
 
-export async function runSlice(
+export async function agentStep(
   state: HarnessWorkflowState,
 ): Promise<HarnessWorkflowState> {
   'use step';
 
   const { agent } = await import('./agent');
 
-  return runHarnessAgentSlice({
+  return runHarnessAgentStep({
     agent,
     state,
   });
 }
 ```
 
+### Defining the Semantic Agent Step Workflow
+
+Create the workflow state and keep scheduling `agentStep()` while the agent has
+more work.
+
 ```ts filename='harness-workflow/workflow.ts'
-import { runSlice } from './run-slice-step';
+import { agentStep } from './agent-step';
 import {
   createHarnessWorkflowState,
   finalizeHarnessWorkflow,
   type HarnessWorkflowInput,
 } from '@ai-sdk/workflow-harness';
 
-export async function codingWorkflow(
-  input: Pick<HarnessWorkflowInput, 'prompt' | 'sessionId'>,
-) {
+export async function agentWorkflow(input: {
+  messages: NonNullable<HarnessWorkflowInput['messages']>;
+  sessionId: string;
+}) {
   'use workflow';
 
   let state = createHarnessWorkflowState(input);
 
-  while (state.status === 'running' || state.status === 'timed_out') {
-    state = await runSlice(state);
-  }
+  do {
+    state = await agentStep(state);
+  } while (state.status === 'ready_for_next_step');
 
   return finalizeHarnessWorkflow(state);
 }
 ```
 
-### Starting the Workflow
+<Note>
+  This example covers the workflow execution foundation only. For multi-turn
+  conversations, you must persist the harness session's `resumeFrom` state
+  between workflow runs. See [Resume Persistence](#resume-persistence).
+</Note>
+
+Each `ready_for_next_step` result carries `continueFrom`, which lets the next
+Workflow step continue the same unfinished turn. When the turn finishes,
+`finalizeHarnessWorkflow()` returns its result or throws if the workflow failed.
 
-Start the workflow from server-side code. You can return `run.readable` from an
-HTTP endpoint, consume it directly, or expose it through your framework's
-streaming response primitive.
+### Starting the Semantic Agent Step Workflow
 
-```ts filename='server/start-coding-workflow.ts'
-import { codingWorkflow } from '../harness-workflow/workflow';
+Start the workflow from server-side code. This Next.js route converts the AI SDK
+UI messages, starts `agentWorkflow()`, and returns the workflow's AI SDK UI
+message stream. Passing the converted messages lets `HarnessAgent` distinguish a
+new user turn from tool approval and tool result continuations.
+
+```ts filename='app/api/harness-workflow/route.ts'
+import { agentWorkflow } from '../../../harness-workflow/workflow';
+import {
+  convertToModelMessages,
+  createUIMessageStreamResponse,
+  type UIMessage,
+  type UIMessageChunk,
+} from 'ai';
 import { start } from 'workflow/api';
 
-export async function startCodingWorkflow({
-  prompt,
-  sessionId,
-}: {
-  prompt: string;
+export async function POST(request: Request) {
+  const body: {
+    id?: string;
+    messages: UIMessage[];
+  } = await request.json();
+
+  if (!body.id) {
+    return new Response('Missing chat ID', { status: 400 });
+  }
+
+  const messages = await convertToModelMessages(body.messages);
+  const run = await start(agentWorkflow, [
+    {
+      messages,
+      sessionId: body.id,
+    },
+  ]);
+
+  return createUIMessageStreamResponse({
+    stream: run.readable as ReadableStream<UIMessageChunk>,
+  });
+}
+```
+
+The `sessionId` gives the sandbox a stable identity across workflow runs. Keep
+`agent.ts`, `agent-step.ts`, `workflow.ts`, and the route in separate modules so
+the workflow bundle does not include Node-heavy agent, sandbox, or framework
+dependencies.
+
+## Using Time Slices
+
+Time slices persist a long-running harness turn at wall-clock boundaries. Omit
+the highlighted `stopWhen` option from the shared agent, then call
+`runHarnessAgentTimeSlice()` from a Workflow step. It uses a 750-second budget
+by default; pass `timeSliceSeconds` to choose a different budget.
+
+### Defining the Time Slice Step
+
+As with semantic agent steps, keep the Workflow step in its own module and
+import the agent dynamically inside the step body.
+
+```ts filename='harness-workflow/time-slice-step.ts'
+import {
+  runHarnessAgentTimeSlice,
+  type HarnessWorkflowState,
+} from '@ai-sdk/workflow-harness';
+
+export async function timeSliceStep(
+  state: HarnessWorkflowState,
+): Promise<HarnessWorkflowState> {
+  'use step';
+
+  const { agent } = await import('./agent');
+
+  return runHarnessAgentTimeSlice({
+    agent,
+    state,
+  });
+}
+```
+
+### Defining the Time-Sliced Workflow
+
+Create the workflow state and keep scheduling `timeSliceStep()` while the agent
+has more work.
+
+```ts filename='harness-workflow/workflow.ts'
+import { timeSliceStep } from './time-slice-step';
+import {
+  createHarnessWorkflowState,
+  finalizeHarnessWorkflow,
+  type HarnessWorkflowInput,
+} from '@ai-sdk/workflow-harness';
+
+export async function timeSliceWorkflow(input: {
+  messages: NonNullable<HarnessWorkflowInput['messages']>;
   sessionId: string;
 }) {
-  const run = await start(codingWorkflow, [{ prompt, sessionId }]);
+  'use workflow';
+
+  let state = createHarnessWorkflowState(input);
+
+  do {
+    state = await timeSliceStep(state);
+  } while (state.status === 'ready_for_next_step');
 
-  return run.readable;
+  return finalizeHarnessWorkflow(state);
 }
 ```
 
-This is the core workflow/harness integration. Add resume persistence when you
-need a multi-turn chat to reattach to the same native harness session across
-workflow runs.
+<Note>
+  This example covers the workflow execution foundation only. For multi-turn
+  conversations, you must persist the harness session's `resumeFrom` state
+  between workflow runs. See [Resume Persistence](#resume-persistence).
+</Note>
+
+Each `ready_for_next_step` result carries `continueFrom`, which lets the next
+Workflow step continue the same unfinished turn. When the turn finishes,
+`finalizeHarnessWorkflow()` returns its result or throws if the workflow failed.
 
-### HTTP Route Example
+### Starting the Time-Sliced Workflow
 
-This example uses a Next.js `Request`/`Response` handler and AI SDK UI message
-streams. For other frameworks, the workflow related code is similar: derive the
-newest user message, call `start(codingWorkflow, [...])`, and return the run's
-readable stream.
+Start the workflow from server-side code. As with semantic agent steps, pass the
+converted messages so `HarnessAgent` can distinguish a new user turn from tool
+approval and tool result continuations.
 
 ```ts filename='app/api/harness-workflow/route.ts'
-import { codingWorkflow } from '../../../harness-workflow/workflow';
+import { timeSliceWorkflow } from '../../../harness-workflow/workflow';
 import {
   convertToModelMessages,
   createUIMessageStreamResponse,
@@ -133,15 +257,6 @@ import {
 } from 'ai';
 import { start } from 'workflow/api';
 
-function latestUserMessage(
-  messages: Awaited<ReturnType<typeof convertToModelMessages>>,
-) {
-  for (let index = messages.length - 1; index >= 0; index--) {
-    const message = messages[index];
-    if (message.role === 'user') return message;
-  }
-}
-
 export async function POST(request: Request) {
   const body: {
     id?: string;
@@ -152,14 +267,10 @@ export async function POST(request: Request) {
     return new Response('Missing chat ID', { status: 400 });
   }
 
-  const prompt = latestUserMessage(await convertToModelMessages(body.messages));
-  if (!prompt) {
-    return new Response('No user message to run', { status: 400 });
-  }
-
-  const run = await start(codingWorkflow, [
+  const messages = await convertToModelMessages(body.messages);
+  const run = await start(timeSliceWorkflow, [
     {
-      prompt,
+      messages,
       sessionId: body.id,
     },
   ]);
@@ -170,23 +281,21 @@ export async function POST(request: Request) {
 }
 ```
 
-If you use Next.js, wrap your config with `withWorkflow()` so Workflow SDK
-transforms `'use workflow'` and `'use step'` modules. Other frameworks have
-their own Workflow SDK setup.
-
-```js filename='next.config.js'
-const { withWorkflow } = require('workflow/next');
-
-const nextConfig = {};
-
-module.exports = withWorkflow(nextConfig, {});
-```
+The `sessionId` gives the sandbox a stable identity across workflow runs. Keep
+`agent.ts`, `time-slice-step.ts`, `workflow.ts`, and the route in separate
+modules so the workflow bundle does not include Node-heavy agent, sandbox, or
+framework dependencies.
 
 ## Resume Persistence
 
-Persist only the opaque `resumeFrom` state returned after a finished turn. The
-example below uses Workflow steps because filesystem access must stay out of the
-workflow function itself. Use durable storage instead of local files in
+Workflow automatically persists the `HarnessWorkflowState` returned by each
+step, including `continueFrom`, for the duration of the current workflow run.
+To continue the native harness session across separate user-turn workflow runs,
+persist the opaque `resumeFrom` state by `sessionId`.
+
+The storage implementation is the same for semantic agent steps and time
+slices. This example uses Workflow steps because filesystem access must stay out
+of the workflow function itself. Use durable storage instead of local files in
 production.
 
 ```ts filename='harness-workflow/resume-store.ts'
@@ -244,29 +353,33 @@ export async function persistResumeStep({
 }
 ```
 
-Load the resume state before the first slice and persist the new one after the
-turn finishes:
+Load the previous `resumeFrom` state before creating the workflow state, then
+persist the updated value after the execution loop. The integration points are
+the same for both workflow approaches.
+
+### Semantic Agent Step Workflow
 
 ```ts filename='harness-workflow/workflow.ts'
+import { agentStep } from './agent-step';
 import { loadResumeStep, persistResumeStep } from './resume-store';
-import { runSlice } from './run-slice-step';
 import {
   createHarnessWorkflowState,
   finalizeHarnessWorkflow,
   type HarnessWorkflowInput,
 } from '@ai-sdk/workflow-harness';
 
-export async function codingWorkflow(
-  input: Pick<HarnessWorkflowInput, 'prompt' | 'sessionId'>,
-) {
+export async function agentWorkflow(input: {
+  messages: NonNullable<HarnessWorkflowInput['messages']>;
+  sessionId: string;
+}) {
   'use workflow';
 
   const resumeFrom = await loadResumeStep(input.sessionId);
   let state = createHarnessWorkflowState({ ...input, resumeFrom });
 
-  while (state.status === 'running' || state.status === 'timed_out') {
-    state = await runSlice(state);
-  }
+  do {
+    state = await agentStep(state);
+  } while (state.status === 'ready_for_next_step');
 
   await persistResumeStep({
     sessionId: state.sessionId,
@@ -277,48 +390,38 @@ export async function codingWorkflow(
 }
 ```
 
-The harness `sessionId` gives the sandbox a stable identity across workflow runs
-and lets the workflow load the previous turn's resume state before sending the
-next user message.
-
-A harness session owns its native conversation history, so the route sends only
-the newest user message. Do not replay the full UI message history into the
-harness.
+### Time-Sliced Workflow
 
-## How It Works
-
-Each user turn is represented by a `HarnessWorkflowState`:
-
-- `createHarnessWorkflowState()` creates the initial state for the turn.
-- `runHarnessAgentSlice()` streams one time-boxed slice of the turn.
-- If the slice times out, the harness turn is suspended non-destructively and
-  the returned state contains `continueFrom` for the next slice.
-- If the turn finishes, the helper closes the workflow output stream and returns
-  `resumeFrom` for the next user turn.
-- `finalizeHarnessWorkflow()` returns the final result or throws when the
-  workflow failed.
+```ts filename='harness-workflow/workflow.ts'
+import { loadResumeStep, persistResumeStep } from './resume-store';
+import { timeSliceStep } from './time-slice-step';
+import {
+  createHarnessWorkflowState,
+  finalizeHarnessWorkflow,
+  type HarnessWorkflowInput,
+} from '@ai-sdk/workflow-harness';
 
-The workflow output stream receives AI SDK UI message chunks, so a route can
-return `run.readable` through `createUIMessageStreamResponse()`.
+export async function timeSliceWorkflow(input: {
+  messages: NonNullable<HarnessWorkflowInput['messages']>;
+  sessionId: string;
+}) {
+  'use workflow';
 
-## File Boundaries
+  const resumeFrom = await loadResumeStep(input.sessionId);
+  let state = createHarnessWorkflowState({ ...input, resumeFrom });
 
-Keep the `workflow` entrypoints separate from the agent definition:
+  do {
+    state = await timeSliceStep(state);
+  } while (state.status === 'ready_for_next_step');
 
-- `agent.ts` defines the `HarnessAgent`.
-- `run-slice-step.ts` is a `'use step'` module and imports the agent
-  dynamically inside the step body.
-- `workflow.ts` contains the `'use workflow'` function and imports only
-  workflow-safe helpers and step modules.
-- your route or server entrypoint starts the workflow. It can import `ai`
-  helpers such as `convertToModelMessages()` and
-  `createUIMessageStreamResponse()`.
+  await persistResumeStep({
+    sessionId: state.sessionId,
+    resumeState: state.resumeFrom,
+  });
 
-Do not define the workflow function in the same module as the route handler,
-server entrypoint, or agent. The Workflow DevKit compiles the module graph
-reachable from a `'use workflow'` directive. Keeping the graph small prevents
-Node-heavy agent, sandbox, and framework dependencies from being pulled into the
-workflow bundle.
+  return finalizeHarnessWorkflow(state);
+}
+```
 
 ## Related
 

package/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx

@@ -3210,7 +3210,7 @@ To see `streamText` in action, check out [these examples](#examples).
       name: 'textStream',
       type: 'AsyncIterableStream<string>',
       description:
-        'A text stream that returns only the generated text deltas. You can use it as either an AsyncIterable or a ReadableStream. When an error occurs, the stream will throw the error.',
+        'A text stream that returns only the generated text deltas. You can use it as either an AsyncIterable or a ReadableStream. Error parts are not surfaced in this stream. Use the `onError` callback or `stream` to observe them.',
     },
     {
       name: 'finalStep',

package/docs/07-reference/01-ai-sdk-core/11-stream-translate.mdx

@@ -0,0 +1,176 @@
+---
+title: experimental_streamTranslate
+description: API Reference for experimental_streamTranslate.
+---
+
+# `experimental_streamTranslate()`
+
+<Note type="warning">
+  `experimental_streamTranslate` is an experimental feature.
+</Note>
+
+Streams a speech-to-speech translation from live raw audio. Models translate
+live source audio into target-language audio and text.
+
+`experimental_streamTranslate` is built on the speech translation model
+specification (`Experimental_SpeechTranslationModelV4`). Provider
+implementations of the specification ship separately — see your provider's
+documentation for available translation models.
+
+```ts
+import { experimental_streamTranslate as streamTranslate } from 'ai';
+
+const result = streamTranslate({
+  // any provider model instance that implements the experimental
+  // speech translation model specification (Experimental_SpeechTranslationModelV4):
+  model: translationModel,
+  audio: audioStream, // ReadableStream<Uint8Array | string>
+  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
+  targetLanguage: 'es',
+});
+
+for await (const part of result.fullStream) {
+  if (part.type === 'output-text-delta') {
+    process.stdout.write(part.delta);
+  }
+}
+
+console.log(await result.translationText);
+```
+
+## Import
+
+<Snippet
+  text={`import { experimental_streamTranslate as streamTranslate } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'model',
+      type: 'Experimental_SpeechTranslationModelV4',
+      description:
+        'The speech translation model to use. Translation is a streaming-only modality. Pass a provider model instance that implements the experimental speech translation model specification. String model IDs resolve through the global provider (AI Gateway by default) when it supports speech translation models.',
+    },
+    {
+      name: 'audio',
+      type: 'ReadableStream<Uint8Array | string>',
+      description:
+        'Raw audio chunks to translate. `Uint8Array` chunks contain raw audio bytes; `string` chunks contain base64-encoded raw audio bytes.',
+    },
+    {
+      name: 'inputAudioFormat',
+      type: '{ type: string; rate?: number }',
+      description:
+        'The input audio format for the raw audio chunks, e.g. `{ type: "audio/pcm", rate: 24000 }`. Supported types are provider-specific (e.g. `audio/pcm`, `audio/pcmu`, `audio/pcma`).',
+    },
+    {
+      name: 'targetLanguage',
+      type: 'string',
+      description:
+        'The language to translate the audio into, as a BCP-47-style language tag (e.g. `en`, `es`, `fr-CA`). Supported values are provider-specific and validated by the provider.',
+    },
+    {
+      name: 'sourceLanguage',
+      type: 'string',
+      isOptional: true,
+      description:
+        'The language of the source audio, as a BCP-47-style language tag. When absent, providers auto-detect the source language.',
+    },
+    {
+      name: 'outputAudioFormat',
+      type: '{ type: string; rate?: number }',
+      isOptional: true,
+      description:
+        'The desired audio format for translated audio chunks. When absent, the provider default output format is used.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'Record<string, JSONObject>',
+      isOptional: true,
+      description: 'Additional provider-specific options.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description: 'An optional abort signal to cancel the call.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description:
+        'Additional HTTP/WebSocket headers, if supported by the provider.',
+    },
+    {
+      name: 'includeRawChunks',
+      type: 'boolean',
+      isOptional: true,
+      description:
+        'When true, the provider includes raw provider chunks in the stream as `raw` parts.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'fullStream',
+      type: 'AsyncIterableStream<TranslationStreamPart>',
+      description:
+        'A single-consumer live stream of translation parts: `audio`, `output-text-delta`, `output-text-final`, `source-transcript-delta`, `source-transcript-partial`, `source-transcript-final`, `raw`, and `error`. Access it once, before any result promise, when both stream parts and final results are needed. Accessing a result promise first consumes the stream internally and makes `fullStream` unavailable.',
+    },
+    {
+      name: 'sourceText',
+      type: 'Promise<string>',
+      description: 'The final source-language transcript of the input audio.',
+    },
+    {
+      name: 'translationText',
+      type: 'Promise<string>',
+      description:
+        'The final translated text in the target language. May resolve to an empty string for providers that produce only audio output.',
+    },
+    {
+      name: 'durationInSeconds',
+      type: 'Promise<number | undefined>',
+      description: 'The duration of the source audio in seconds, if available.',
+    },
+    {
+      name: 'usage',
+      type: 'Promise<Experimental_SpeechTranslationModelV4Usage | undefined>',
+      description:
+        'Usage information for the translation call, if reported by the provider: `inputAudioSeconds`, `inputAudioTokens`, `outputAudioTokens`, `inputTextTokens`, `outputTextTokens` (all optional numbers).',
+    },
+    {
+      name: 'warnings',
+      type: 'Promise<Warning[]>',
+      description:
+        'Warnings for the call, e.g. unsupported settings. Resolves at stream start, or with an empty array at finish if no stream-start was emitted.',
+    },
+    {
+      name: 'response',
+      type: 'Promise<SpeechTranslationModelResponseMetadata>',
+      description: 'Response metadata (timestamp, model ID, headers).',
+    },
+    {
+      name: 'providerMetadata',
+      type: 'Promise<Record<string, JSONObject>>',
+      description: 'Additional provider-specific metadata.',
+    },
+  ]}
+/>
+
+<Note>
+  The result promises settle as the stream is consumed. If you stop consuming
+  `fullStream` early (e.g. `break` out of the loop), the underlying provider
+  connection is closed and pending result promises reject.
+</Note>