ai 6.0.31 → 6.0.33

package/docs/07-reference/01-ai-sdk-core/17-create-agent-ui-stream.mdx

@@ -0,0 +1,148 @@
+---
+title: createAgentUIStream
+description: API Reference for the createAgentUIStream utility.
+---
+
+# `createAgentUIStream`
+
+The `createAgentUIStream` function executes an [Agent](/docs/reference/ai-sdk-core/agent), consumes an array of UI messages, and streams the agent's output as UI message chunks via an async iterable. This enables real-time, incremental rendering of AI assistant output with full access to tool use, intermediate reasoning, and interactive UI features in your own runtime—perfect for building chat APIs, dashboards, or bots powered by agents.
+
+## Import
+
+<Snippet text={`import { createAgentUIStream } from "ai"`} prompt={false} />
+
+## Usage
+
+```ts
+import { ToolLoopAgent, createAgentUIStream } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: 'You are a helpful assistant.',
+  tools: { weather: weatherTool, calculator: calculatorTool },
+});
+
+export async function* streamAgent(
+  uiMessages: unknown[],
+  abortSignal?: AbortSignal,
+) {
+  const stream = await createAgentUIStream({
+    agent,
+    uiMessages,
+    abortSignal,
+    // ...other options (see below)
+  });
+
+  for await (const chunk of stream) {
+    yield chunk; // Each chunk is a UI message output from the agent.
+  }
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'agent',
+      type: 'Agent',
+      isRequired: true,
+      description:
+        'The agent to run. Must define its `tools` and implement `.stream({ prompt, ... })`.',
+    },
+    {
+      name: 'uiMessages',
+      type: 'unknown[]',
+      isRequired: true,
+      description:
+        'Array of input UI message objects (e.g., user/assistant/chat history). These will be validated and converted for the agent.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isRequired: false,
+      description:
+        'Optional abort signal to cancel the stream early (for example, if the client disconnects).',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isRequired: false,
+      description:
+        'Timeout in milliseconds. Can be specified as a number or as an object with a totalMs property. The call will be aborted if it takes longer than the specified timeout. Can be used alongside abortSignal.',
+    },
+    {
+      name: 'options',
+      type: 'CALL_OPTIONS',
+      isRequired: false,
+      description:
+        'Optional agent call options, only needed if your agent expects extra configuration (see agent generic parameters).',
+    },
+    {
+      name: 'experimental_transform',
+      type: 'StreamTextTransform | StreamTextTransform[]',
+      isRequired: false,
+      description:
+        'Optional transformations to apply to the agent output stream (experimental).',
+    },
+    {
+      name: '...UIMessageStreamOptions',
+      type: 'UIMessageStreamOptions',
+      isRequired: false,
+      description:
+        'Additional options to control the output stream, such as including sources or usage data.',
+    },
+  ]}
+/>
+
+## Returns
+
+A `Promise<AsyncIterableStream<UIMessageChunk>>`, where each yielded chunk is a UI message output from the agent (see [`UIMessage`](/docs/reference/ai-sdk-core/ui-message)). This can be consumed with any async iterator loop, or piped to a streaming HTTP response, socket, or any other sink.
+
+## Example
+
+```ts
+import { createAgentUIStream } from 'ai';
+
+const controller = new AbortController();
+
+const stream = await createAgentUIStream({
+  agent,
+  uiMessages: [{ role: 'user', content: 'What is the weather in SF today?' }],
+  abortSignal: controller.signal,
+  sendStart: true,
+  // ...other UIMessageStreamOptions
+});
+
+for await (const chunk of stream) {
+  // Each chunk is a UI message update — stream it to your client, dashboard, logs, etc.
+  console.log(chunk);
+}
+
+// Call controller.abort() to cancel the agent operation early.
+```
+
+## How It Works
+
+1. **UI Message Validation:** The input `uiMessages` array is validated and normalized using the agent's `tools` definition. Any invalid messages cause an error.
+2. **Conversion to Model Messages:** The validated UI messages are converted into model-specific message format, as required by the agent.
+3. **Agent Streaming:** The agent's `.stream({ prompt, ... })` method is invoked with the converted model messages, optional call options, abort signal, and any experimental transforms.
+4. **UI Message Stream Building:** The result stream is converted and exposed as a streaming async iterable of UI message chunks for you to consume.
+
+## Notes
+
+- The agent **must** implement the `.stream({ prompt, ... })` method and define its supported `tools` property.
+- This utility returns an async iterable for maximal streaming flexibility. For HTTP responses, see [`createAgentUIStreamResponse`](/docs/reference/ai-sdk-core/create-agent-ui-stream-response) (Web) or [`pipeAgentUIStreamToResponse`](/docs/reference/ai-sdk-core/pipe-agent-ui-stream-to-response) (Node.js).
+- The `uiMessages` parameter is named `uiMessages`, **not** just `messages`.
+- You can provide advanced options via [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options) (for example, to include sources or usage).
+- To cancel the stream, pass an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) via the `abortSignal` parameter.
+
+## See Also
+
+- [`Agent`](/docs/reference/ai-sdk-core/agent)
+- [`ToolLoopAgent`](/docs/reference/ai-sdk-core/tool-loop-agent)
+- [`UIMessage`](/docs/reference/ai-sdk-core/ui-message)
+- [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options)
+- [`createAgentUIStreamResponse`](/docs/reference/ai-sdk-core/create-agent-ui-stream-response)
+- [`pipeAgentUIStreamToResponse`](/docs/reference/ai-sdk-core/pipe-agent-ui-stream-to-response)

package/docs/07-reference/01-ai-sdk-core/18-create-agent-ui-stream-response.mdx

@@ -0,0 +1,168 @@
+---
+title: createAgentUIStreamResponse
+description: API Reference for the createAgentUIStreamResponse utility.
+---
+
+# `createAgentUIStreamResponse`
+
+The `createAgentUIStreamResponse` function executes an [Agent](/docs/reference/ai-sdk-core/agent), runs its streaming output as a UI message stream, and returns an HTTP [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object whose body is the live, streaming UI message output. This is designed for API routes that deliver real-time agent results, such as chat endpoints or streaming tool-use operations.
+
+## Import
+
+<Snippet
+  text={`import { createAgentUIStreamResponse } from "ai"`}
+  prompt={false}
+/>
+
+## Usage
+
+```ts
+import { ToolLoopAgent, createAgentUIStreamResponse } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: 'You are a helpful assistant.',
+  tools: { weather: weatherTool, calculator: calculatorTool },
+});
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  // Optional: support cancellation (aborts on disconnect, etc.)
+  const abortController = new AbortController();
+
+  return createAgentUIStreamResponse({
+    agent,
+    uiMessages: messages,
+    abortSignal: abortController.signal, // optional
+    // ...other UIMessageStreamOptions like sendSources, includeUsage, experimental_transform, etc.
+  });
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'agent',
+      type: 'Agent',
+      isRequired: true,
+      description:
+        'The agent instance to stream responses from. Must implement `.stream({ prompt, ... })` and define the `tools` property.',
+    },
+    {
+      name: 'uiMessages',
+      type: 'unknown[]',
+      isRequired: true,
+      description:
+        'Array of input UI messages provided to the agent (e.g., user and assistant messages).',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isRequired: false,
+      description:
+        'Optional abort signal to cancel streaming, e.g., on client disconnect. This should be an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isRequired: false,
+      description:
+        'Timeout in milliseconds. Can be specified as a number or as an object with a totalMs property. The call will be aborted if it takes longer than the specified timeout. Can be used alongside abortSignal.',
+    },
+    {
+      name: 'options',
+      type: 'CALL_OPTIONS',
+      isRequired: false,
+      description:
+        'Optional agent call options, for agents with generic parameter `CALL_OPTIONS`.',
+    },
+    {
+      name: 'experimental_transform',
+      type: 'StreamTextTransform | StreamTextTransform[]',
+      isRequired: false,
+      description:
+        'Optional stream transforms to post-process text output—the same as in lower-level streaming APIs.',
+    },
+    {
+      name: '...UIMessageStreamOptions',
+      type: 'UIMessageStreamOptions',
+      isRequired: false,
+      description:
+        'Other UI message output options—such as `sendSources`, `includeUsage`, and more. See [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options).',
+    },
+    {
+      name: 'headers',
+      type: 'HeadersInit',
+      isRequired: false,
+      description: 'Optional HTTP headers to include in the Response object.',
+    },
+    {
+      name: 'status',
+      type: 'number',
+      isRequired: false,
+      description: 'Optional HTTP status code.',
+    },
+    {
+      name: 'statusText',
+      type: 'string',
+      isRequired: false,
+      description: 'Optional HTTP status text.',
+    },
+    {
+      name: 'consumeSseStream',
+      type: 'boolean',
+      isRequired: false,
+      description:
+        'If true, consume the stream as SSE (server-sent events) instead of default streaming.',
+    },
+  ]}
+/>
+
+## Returns
+
+A `Promise<Response>` whose `body` is a streaming UI message output from the agent. Use this as the return value of API/server handlers in serverless, Next.js, Express, Hono, or edge runtime contexts.
+
+## Example: Next.js API Route Handler
+
+```ts
+import { createAgentUIStreamResponse } from 'ai';
+import { MyCustomAgent } from '@/agent/my-custom-agent';
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  return createAgentUIStreamResponse({
+    agent: MyCustomAgent,
+    uiMessages: messages,
+    sendSources: true, // (optional)
+    includeUsage: true, // (optional)
+    // headers, status, abortSignal, and other UIMessageStreamOptions also supported
+  });
+}
+```
+
+## How It Works
+
+- 1. **UI Message Validation:** Validates the incoming `uiMessages` array according to the agent's specified tools and requirements.
+- 2. **Model Message Conversion:** Converts validated UI messages into the internal model message format for the agent.
+- 3. **Streaming Agent Output:** Invokes the agent’s `.stream({ prompt, ... })` to get a stream of chunks (steps/UI messages).
+- 4. **HTTP Response Creation:** Wraps the output stream as a readable HTTP `Response` object that streams UI message chunks to the client.
+
+## Notes
+
+- Your agent **must** implement `.stream({ prompt, ... })` and define a `tools` property (even if it's just `{}`) to work with this function.
+- **Server Only:** This API should only be called in backend/server-side contexts (API routes, edge/serverless/server route handlers, etc.). Not for browser use.
+- Additional options (`headers`, `status`, UI stream options, transforms, etc.) are available for advanced scenarios.
+- This leverages [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) so your platform/client must support HTTP streaming consumption.
+
+## See Also
+
+- [`Agent`](/docs/reference/ai-sdk-core/agent)
+- [`ToolLoopAgent`](/docs/reference/ai-sdk-core/tool-loop-agent)
+- [`UIMessage`](/docs/reference/ai-sdk-core/ui-message)
+- [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options)
+- [`createAgentUIStream`](/docs/reference/ai-sdk-core/create-agent-ui-stream)

package/docs/07-reference/01-ai-sdk-core/18-pipe-agent-ui-stream-to-response.mdx

@@ -0,0 +1,144 @@
+---
+title: pipeAgentUIStreamToResponse
+description: API Reference for the pipeAgentUIStreamToResponse utility.
+---
+
+# `pipeAgentUIStreamToResponse`
+
+The `pipeAgentUIStreamToResponse` function runs an [Agent](/docs/reference/ai-sdk-core/agent) and streams the resulting UI message output directly to a Node.js [`ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) object. This is ideal for building real-time streaming API endpoints (for chat, tool use, etc.) in Node.js-based frameworks like Express, Hono, or custom Node servers.
+
+## Import
+
+<Snippet
+  text={`import { pipeAgentUIStreamToResponse } from "ai"`}
+  prompt={false}
+/>
+
+## Usage
+
+```ts
+import { pipeAgentUIStreamToResponse } from 'ai';
+import { MyAgent } from './agent';
+
+export async function handler(req, res) {
+  const { messages } = JSON.parse(req.body);
+
+  await pipeAgentUIStreamToResponse({
+    response: res, // Node.js ServerResponse
+    agent: MyAgent,
+    uiMessages: messages, // Required: array of input UI messages
+    // abortSignal: optional AbortSignal for cancellation
+    // status: 200,
+    // headers: { ... },
+    // ...other optional UI message stream options
+  });
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'response',
+      type: 'ServerResponse',
+      isRequired: true,
+      description:
+        'The Node.js ServerResponse object to pipe UI message stream output into.',
+    },
+    {
+      name: 'agent',
+      type: 'Agent',
+      isRequired: true,
+      description:
+        'An agent instance implementing `.stream({ prompt, ... })` and defining a `tools` property.',
+    },
+    {
+      name: 'uiMessages',
+      type: 'unknown[]',
+      isRequired: true,
+      description:
+        'Array of input UI messages sent to the agent (such as user/assistant message objects).',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isRequired: false,
+      description:
+        'Optional abort signal to cancel streaming (e.g., on client disconnect). Supply an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal), for example from an `AbortController`.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isRequired: false,
+      description:
+        'Timeout in milliseconds. Can be specified as a number or as an object with a totalMs property. The call will be aborted if it takes longer than the specified timeout. Can be used alongside abortSignal.',
+    },
+    {
+      name: 'options',
+      type: 'CALL_OPTIONS',
+      isRequired: false,
+      description:
+        'Optional agent call options, for agents configured with generic parameter `CALL_OPTIONS`.',
+    },
+    {
+      name: 'experimental_transform',
+      type: 'StreamTextTransform | StreamTextTransform[]',
+      isRequired: false,
+      description:
+        'Optional stream text transformation(s) applied to agent output.',
+    },
+    {
+      name: '...UIMessageStreamResponseInit & UIMessageStreamOptions',
+      type: 'object',
+      isRequired: false,
+      description:
+        'Options for streaming headers, status, SSE stream config, and additional UI message stream control.',
+    },
+  ]}
+/>
+
+## Returns
+
+A `Promise<void>`. The function completes when the UI message stream has been fully sent to the provided ServerResponse.
+
+## Example: Express Route Handler
+
+```ts
+import { pipeAgentUIStreamToResponse } from 'ai';
+import { openaiWebSearchAgent } from './openai-web-search-agent';
+
+app.post('/chat', async (req, res) => {
+  // Use req.body.messages as input UI messages
+  await pipeAgentUIStreamToResponse({
+    response: res,
+    agent: openaiWebSearchAgent,
+    uiMessages: req.body.messages,
+    // abortSignal: yourController.signal
+    // status: 200,
+    // headers: { ... },
+    // ...more options
+  });
+});
+```
+
+## How It Works
+
+1. **Runs the Agent:** Calls the agent’s `.stream` method with the provided UI messages and options, converting them into model messages as needed.
+2. **Streams UI Message Output:** Pipes the agent output as a UI message stream to the `ServerResponse`, sending data via streaming HTTP responses (including appropriate headers).
+3. **Abort Signal Handling:** If `abortSignal` is supplied, streaming is cancelled as soon as the signal is triggered (such as on client disconnect).
+4. **No Response Return:** Unlike Edge/serverless APIs that return a `Response`, this function writes bytes directly to the ServerResponse and does not return a response object.
+
+## Notes
+
+- **Abort Handling:** For best robustness, use an `AbortSignal` (for example, wired to Express/Hono client disconnects) to ensure quick cancellation of agent computation and streaming.
+- **Node.js Only:** Only works with Node.js [ServerResponse](https://nodejs.org/api/http.html#class-httpserverresponse) objects (e.g., in Express, Hono’s node adapter, etc.), not Edge/serverless/web Response APIs.
+- **Streaming Support:** Make sure your client (and any proxies) correctly support streaming HTTP responses for full effect.
+- **Parameter Names:** The property for input messages is `uiMessages` (not `messages`) for consistency with SDK agent utilities.
+
+## See Also
+
+- [`createAgentUIStreamResponse`](/docs/reference/ai-sdk-core/create-agent-ui-stream-response)
+- [`Agent`](/docs/reference/ai-sdk-core/agent)
+- [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options)
+- [`UIMessage`](/docs/reference/ai-sdk-core/ui-message)

package/docs/07-reference/01-ai-sdk-core/20-tool.mdx

@@ -0,0 +1,196 @@
+---
+title: tool
+description: Helper function for tool type inference
+---
+
+# `tool()`
+
+Tool is a helper function that infers the tool input for its `execute` method.
+
+It does not have any runtime behavior, but it helps TypeScript infer the types of the input for the `execute` method.
+
+Without this helper function, TypeScript is unable to connect the `inputSchema` property to the `execute` method,
+and the argument types of `execute` cannot be inferred.
+
+```ts highlight={"1,4,9,10"}
+import { tool } from 'ai';
+import { z } from 'zod';
+
+export const weatherTool = tool({
+  description: 'Get the weather in a location',
+  inputSchema: z.object({
+    location: z.string().describe('The location to get the weather for'),
+  }),
+  // location below is inferred to be a string:
+  execute: async ({ location }) => ({
+    location,
+    temperature: 72 + Math.floor(Math.random() * 21) - 10,
+  }),
+});
+```
+
+## Import
+
+<Snippet text={`import { tool } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'tool',
+      type: 'Tool',
+      description: 'The tool definition.',
+      properties: [
+        {
+          type: 'Tool',
+          parameters: [
+            {
+              name: 'description',
+              isOptional: true,
+              type: 'string',
+              description:
+                'Information about the purpose of the tool including details on how and when it can be used by the model.',
+            },
+            {
+              name: 'inputSchema',
+              type: 'Zod Schema | JSON Schema',
+              description:
+                'The schema of the input that the tool expects. The language model will use this to generate the input. It is also used to validate the output of the language model. Use descriptions to make the input understandable for the language model. You can either pass in a Zod schema or a JSON schema (using the `jsonSchema` function).',
+            },
+            {
+              name: 'inputExamples',
+              isOptional: true,
+              type: 'Array<{ input: INPUT }>',
+              description:
+                'An optional list of input examples that show the language model what the input should look like.',
+            },
+            {
+              name: 'strict',
+              isOptional: true,
+              type: 'boolean',
+              description:
+                'Strict mode setting for the tool. Providers that support strict mode will use this setting to determine how the input should be generated. Strict mode will always produce valid inputs, but it might limit what input schemas are supported.',
+            },
+            {
+              name: 'execute',
+              isOptional: true,
+              type: 'async (input: INPUT, options: ToolExecutionOptions) => RESULT | Promise<RESULT> | AsyncIterable<RESULT>',
+              description:
+                'An async function that is called with the arguments from the tool call and produces a result or a results iterable. If an iterable is provided, all results but the last one are considered preliminary. If not provided, the tool will not be executed automatically.',
+              properties: [
+                {
+                  type: 'ToolExecutionOptions',
+                  parameters: [
+                    {
+                      name: 'toolCallId',
+                      type: 'string',
+                      description:
+                        'The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.',
+                    },
+                    {
+                      name: 'messages',
+                      type: 'ModelMessage[]',
+                      description:
+                        'Messages that were sent to the language model to initiate the response that contained the tool call. The messages do not include the system prompt nor the assistant response that contained the tool call.',
+                    },
+                    {
+                      name: 'abortSignal',
+                      type: 'AbortSignal',
+                      isOptional: true,
+                      description:
+                        'An optional abort signal that indicates that the overall operation should be aborted.',
+                    },
+                    {
+                      name: 'experimental_context',
+                      type: 'unknown',
+                      isOptional: true,
+                      description:
+                        'Context that is passed into tool execution. Experimental (can break in patch releases).',
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              name: 'outputSchema',
+              isOptional: true,
+              type: 'Zod Schema | JSON Schema',
+              description:
+                'The schema of the output that the tool produces. Used for validation and type inference.',
+            },
+            {
+              name: 'toModelOutput',
+              isOptional: true,
+              type: '({toolCallId: string; input: INPUT; output: OUTPUT}) => ToolResultOutput | PromiseLike<ToolResultOutput>',
+              description:
+                'Optional conversion function that maps the tool result to an output that can be used by the language model. If not provided, the tool result will be sent as a JSON object.',
+            },
+            {
+              name: 'onInputStart',
+              isOptional: true,
+              type: '(options: ToolExecutionOptions) => void | PromiseLike<void>',
+              description:
+                'Optional function that is called when the argument streaming starts. Only called when the tool is used in a streaming context.',
+            },
+            {
+              name: 'onInputDelta',
+              isOptional: true,
+              type: '(options: { inputTextDelta: string } & ToolExecutionOptions) => void | PromiseLike<void>',
+              description:
+                'Optional function that is called when an argument streaming delta is available. Only called when the tool is used in a streaming context.',
+            },
+            {
+              name: 'onInputAvailable',
+              isOptional: true,
+              type: '(options: { input: INPUT } & ToolExecutionOptions) => void | PromiseLike<void>',
+              description:
+                'Optional function that is called when a tool call can be started, even if the execute function is not provided.',
+            },
+            {
+              name: 'providerOptions',
+              isOptional: true,
+              type: 'ProviderOptions',
+              description:
+                'Additional provider-specific metadata. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.',
+            },
+            {
+              name: 'type',
+              isOptional: true,
+              type: "'function' | 'provider-defined'",
+              description:
+                'The type of the tool. Defaults to "function" for regular tools. Use "provider-defined" for provider-specific tools.',
+            },
+            {
+              name: 'id',
+              isOptional: true,
+              type: 'string',
+              description:
+                'The ID of the tool for provider-defined tools. Should follow the format `<provider-name>.<unique-tool-name>`. Required when type is "provider-defined".',
+            },
+            {
+              name: 'name',
+              isOptional: true,
+              type: 'string',
+              description:
+                'The name of the tool that the user must use in the tool set. Required when type is "provider-defined".',
+            },
+            {
+              name: 'args',
+              isOptional: true,
+              type: 'Record<string, unknown>',
+              description:
+                'The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool. Required when type is "provider-defined".',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+The tool that was passed in.