feat(agent): support experimental stream transforms (#10504)

## Background

Stream transformation such as stream smoothing were not supported when
using the agent abstraction.

## Summary

Add `experimental_transform` support to `Agent.stream` and related
functions.

Not implemented as a property on `Agent` because transformations
specific to streaming and not available for generate.

## Manual Verification

Ran `examples/next-openai` with
http://localhost:3000/chat-openai-smooth-stream

Author: lgrammel

.changeset/little-gifts-drive.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat(agent): support experimental stream transforms

content/docs/07-reference/01-ai-sdk-core/16-tool-loop-agent.mdx

@@ -272,6 +272,13 @@ for await (const chunk of stream.textStream) {
       description:
         'An optional abort signal that can be used to cancel the call.',
     },
+    {
+      name: 'experimental_transform',
+      type: 'StreamTextTransform | Array<StreamTextTransform>',
+      isOptional: true,
+      description:
+        'Optional stream transformation(s). They are applied in the order provided and must maintain the stream structure. See `streamText` docs for details.',
+    },
   ]}
 />
 

examples/next-openai/agent/openai-basic-agent.ts

@@ -0,0 +1,18 @@
+import { openai, OpenAIResponsesProviderOptions } from '@ai-sdk/openai';
+import { ToolLoopAgent, InferAgentUIMessage } from 'ai';
+
+export const openaiBasicAgent = new ToolLoopAgent({
+  model: openai('gpt-5-mini'),
+  providerOptions: {
+    openai: {
+      reasoningEffort: 'medium',
+      reasoningSummary: 'detailed',
+      // store: false,
+    } satisfies OpenAIResponsesProviderOptions,
+  },
+  onStepFinish: ({ request }) => {
+    console.dir(request.body, { depth: Infinity });
+  },
+});
+
+export type OpenAIBasicMessage = InferAgentUIMessage<typeof openaiBasicAgent>;

examples/next-openai/app/api/chat-openai-smooth-stream/route.ts

@@ -0,0 +1,12 @@
+import { openaiBasicAgent } from '@/agent/openai-basic-agent';
+import { createAgentUIStreamResponse, smoothStream } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  return createAgentUIStreamResponse({
+    agent: openaiBasicAgent,
+    messages,
+    experimental_transform: smoothStream(),
+  });
+}

examples/next-openai/app/chat-openai-smooth-stream/page.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { OpenAIBasicMessage } from '@/agent/openai-basic-agent';
+import { Response } from '@/components/ai-elements/response';
+import ChatInput from '@/components/chat-input';
+import { ReasoningView } from '@/components/reasoning-view';
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+export default function TestOpenAISmoothStream() {
+  const { error, status, sendMessage, messages, regenerate } =
+    useChat<OpenAIBasicMessage>({
+      transport: new DefaultChatTransport({
+        api: '/api/chat-openai-smooth-stream',
+      }),
+    });
+
+  return (
+    <div className="flex flex-col py-24 mx-auto w-full max-w-md stretch">
+      <h1 className="mb-4 text-xl font-bold">OpenAI Smooth Stream</h1>
+
+      {messages.map(message => (
+        <div key={message.id} className="whitespace-pre-wrap">
+          {message.role === 'user' ? 'User: ' : 'AI: '}
+          {message.parts.map((part, index) => {
+            switch (part.type) {
+              case 'text': {
+                return <Response key={index}>{part.text}</Response>;
+              }
+              case 'reasoning': {
+                return <ReasoningView part={part} key={index} />;
+              }
+            }
+          })}
+        </div>
+      ))}
+
+      {error && (
+        <div className="mt-4">
+          <div className="text-red-500">An error occurred.</div>
+          <button
+            type="button"
+            className="px-4 py-2 mt-4 text-blue-500 rounded-md border border-blue-500"
+            onClick={() => regenerate()}
+          >
+            Retry
+          </button>
+        </div>
+      )}
+
+      <ChatInput status={status} onSubmit={text => sendMessage({ text })} />
+    </div>
+  );
+}

packages/ai/src/agent/agent.ts

@@ -1,9 +1,13 @@
 import { ModelMessage } from '@ai-sdk/provider-utils';
 import { GenerateTextResult } from '../generate-text/generate-text-result';
 import { Output } from '../generate-text/output';
+import { StreamTextTransform } from '../generate-text/stream-text';
 import { StreamTextResult } from '../generate-text/stream-text-result';
 import { ToolSet } from '../generate-text/tool-set';
 
+/**
+ * Parameters for calling an agent.
+ */
 export type AgentCallParameters<CALL_OPTIONS> = ([CALL_OPTIONS] extends [never]
   ? { options?: never }
   : { options: CALL_OPTIONS }) &
@@ -45,6 +49,23 @@ export type AgentCallParameters<CALL_OPTIONS> = ([CALL_OPTIONS] extends [never]
     abortSignal?: AbortSignal;
   };
 
+/**
+ * Parameters for streaming an output from an agent.
+ */
+export type AgentStreamParameters<
+  CALL_OPTIONS,
+  TOOLS extends ToolSet,
+> = AgentCallParameters<CALL_OPTIONS> & {
+  /**
+   * Optional stream transformations.
+   * They are applied in the order they are provided.
+   * The stream transformations must maintain the stream structure for streamText to work correctly.
+   */
+  experimental_transform?:
+    | StreamTextTransform<TOOLS>
+    | Array<StreamTextTransform<TOOLS>>;
+};
+
 /**
  * An Agent receives a prompt (text or messages) and generates or streams an output
  * that consists of steps, tool calls, data parts, etc.
@@ -84,6 +105,6 @@ export interface Agent<
    * Streams an output from the agent (streaming).
    */
   stream(
-    options: AgentCallParameters<CALL_OPTIONS>,
+    options: AgentStreamParameters<CALL_OPTIONS, TOOLS>,
   ): PromiseLike<StreamTextResult<TOOLS, OUTPUT>>;
 }

packages/ai/src/agent/create-agent-ui-stream-response.ts

@@ -1,4 +1,4 @@
-import { UIMessageStreamOptions } from '../generate-text';
+import { StreamTextTransform, UIMessageStreamOptions } from '../generate-text';
 import { Output } from '../generate-text/output';
 import { ToolSet } from '../generate-text/tool-set';
 import { createUIMessageStreamResponse } from '../ui-message-stream';
@@ -30,6 +30,9 @@ export async function createAgentUIStreamResponse<
   agent: Agent<CALL_OPTIONS, TOOLS, OUTPUT>;
   messages: unknown[];
   options?: CALL_OPTIONS;
+  experimental_transform?:
+    | StreamTextTransform<TOOLS>
+    | Array<StreamTextTransform<TOOLS>>;
 } & UIMessageStreamResponseInit &
   UIMessageStreamOptions<
     UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>

packages/ai/src/agent/create-agent-ui-stream.ts

@@ -1,4 +1,4 @@
-import { UIMessageStreamOptions } from '../generate-text';
+import { StreamTextTransform, UIMessageStreamOptions } from '../generate-text';
 import { Output } from '../generate-text/output';
 import { ToolSet } from '../generate-text/tool-set';
 import { InferUIMessageChunk } from '../ui-message-stream';
@@ -25,11 +25,15 @@ export async function createAgentUIStream<
   agent,
   messages,
   options,
+  experimental_transform,
   ...uiMessageStreamOptions
 }: {
   agent: Agent<CALL_OPTIONS, TOOLS, OUTPUT>;
   messages: unknown[];
   options?: CALL_OPTIONS;
+  experimental_transform?:
+    | StreamTextTransform<TOOLS>
+    | Array<StreamTextTransform<TOOLS>>;
 } & UIMessageStreamOptions<
   UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>
 >): Promise<
@@ -51,6 +55,7 @@ export async function createAgentUIStream<
   const result = await agent.stream({
     prompt: modelMessages,
     options: options as CALL_OPTIONS,
+    experimental_transform,
   });
 
   return result.toUIMessageStream(uiMessageStreamOptions);

packages/ai/src/agent/pipe-agent-ui-stream-to-response.ts

@@ -1,5 +1,5 @@
 import { ServerResponse } from 'node:http';
-import { UIMessageStreamOptions } from '../generate-text';
+import { StreamTextTransform, UIMessageStreamOptions } from '../generate-text';
 import { Output } from '../generate-text/output';
 import { ToolSet } from '../generate-text/tool-set';
 import { pipeUIMessageStreamToResponse } from '../ui-message-stream';
@@ -31,6 +31,9 @@ export async function pipeAgentUIStreamToResponse<
   agent: Agent<CALL_OPTIONS, TOOLS, OUTPUT>;
   messages: unknown[];
   options?: CALL_OPTIONS;
+  experimental_transform?:
+    | StreamTextTransform<TOOLS>
+    | Array<StreamTextTransform<TOOLS>>;
 } & UIMessageStreamResponseInit &
   UIMessageStreamOptions<
     UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>

packages/ai/src/agent/tool-loop-agent.test-d.ts

@@ -4,7 +4,7 @@ import { Output } from '../generate-text';
 import { MockLanguageModelV3 } from '../test/mock-language-model-v3';
 import { AsyncIterableStream } from '../util/async-iterable-stream';
 import { DeepPartial } from '../util/deep-partial';
-import { AgentCallParameters } from './agent';
+import { AgentCallParameters, AgentStreamParameters } from './agent';
 import { ToolLoopAgent } from './tool-loop-agent';
 
 describe('ToolLoopAgent', () => {
@@ -78,7 +78,7 @@ describe('ToolLoopAgent', () => {
       });
 
       expectTypeOf<Parameters<typeof agent.stream>[0]>().toEqualTypeOf<
-        AgentCallParameters<{ callOption: string }>
+        AgentStreamParameters<{ callOption: string }, {}>
       >();
     });
 
@@ -88,7 +88,7 @@ describe('ToolLoopAgent', () => {
       });
 
       expectTypeOf<Parameters<typeof agent.stream>[0]>().toEqualTypeOf<
-        AgentCallParameters<never>
+        AgentStreamParameters<never, {}>
       >();
     });