# `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
    // experimental_sandbox, // optional: passed through to tool execution
    // ...other UIMessageStreamOptions like sendSources, 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: 'experimental_sandbox',
      type: 'Experimental_Sandbox',
      isRequired: false,
      description:
        'Optional experimental sandbox environment that is passed through to tool execution. Tools can access it from their execution context.',
    },
    {
      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: 'onStepFinish',
      type: 'GenerateTextOnStepFinishCallback',
      isRequired: false,
      description:
        'Callback invoked after each agent step (LLM/tool call) completes. Useful for tracking token usage or logging intermediate steps.',
    },
    {
      name: '...UIMessageStreamOptions',
      type: 'UIMessageStreamOptions',
      isRequired: false,
      description:
        'Other UI message output options—such as `sendSources` and more.',
    },
    {
      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: '(options: { stream: ReadableStream<string> }) => PromiseLike<void> | void',
      isRequired: false,
      description:
        'Optional function to consume the SSE stream. When provided, this function will be called with the SSE stream to handle consumption.',
    },
  ]}
/>

## 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,
    // experimental_sandbox, // optional
    sendSources: 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), passing through options such as `experimental_sandbox`.
- 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.
- Pass `experimental_sandbox` when your agent tools need an experimental sandbox environment during execution.
- 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)
- [`createAgentUIStream`](/docs/reference/ai-sdk-core/create-agent-ui-stream)


## Navigation

- [generateText](/v7/docs/reference/ai-sdk-core/generate-text)
- [streamText](/v7/docs/reference/ai-sdk-core/stream-text)
- [embed](/v7/docs/reference/ai-sdk-core/embed)
- [embedMany](/v7/docs/reference/ai-sdk-core/embed-many)
- [rerank](/v7/docs/reference/ai-sdk-core/rerank)
- [generateImage](/v7/docs/reference/ai-sdk-core/generate-image)
- [transcribe](/v7/docs/reference/ai-sdk-core/transcribe)
- [generateSpeech](/v7/docs/reference/ai-sdk-core/generate-speech)
- [experimental_generateVideo](/v7/docs/reference/ai-sdk-core/generate-video)
- [uploadFile](/v7/docs/reference/ai-sdk-core/upload-file)
- [uploadSkill](/v7/docs/reference/ai-sdk-core/upload-skill)
- [Agent (Interface)](/v7/docs/reference/ai-sdk-core/agent)
- [ToolLoopAgent](/v7/docs/reference/ai-sdk-core/tool-loop-agent)
- [createAgentUIStream](/v7/docs/reference/ai-sdk-core/create-agent-ui-stream)
- [createAgentUIStreamResponse](/v7/docs/reference/ai-sdk-core/create-agent-ui-stream-response)
- [pipeAgentUIStreamToResponse](/v7/docs/reference/ai-sdk-core/pipe-agent-ui-stream-to-response)
- [tool](/v7/docs/reference/ai-sdk-core/tool)
- [dynamicTool](/v7/docs/reference/ai-sdk-core/dynamic-tool)
- [createMCPClient](/v7/docs/reference/ai-sdk-core/create-mcp-client)
- [MCP Apps](/v7/docs/reference/ai-sdk-core/mcp-apps)
- [Experimental_StdioMCPTransport](/v7/docs/reference/ai-sdk-core/mcp-stdio-transport)
- [jsonSchema](/v7/docs/reference/ai-sdk-core/json-schema)
- [zodSchema](/v7/docs/reference/ai-sdk-core/zod-schema)
- [valibotSchema](/v7/docs/reference/ai-sdk-core/valibot-schema)
- [Output](/v7/docs/reference/ai-sdk-core/output)
- [filterActiveTools](/v7/docs/reference/ai-sdk-core/filter-active-tools)
- [ModelMessage](/v7/docs/reference/ai-sdk-core/model-message)
- [UIMessage](/v7/docs/reference/ai-sdk-core/ui-message)
- [validateUIMessages](/v7/docs/reference/ai-sdk-core/validate-ui-messages)
- [safeValidateUIMessages](/v7/docs/reference/ai-sdk-core/safe-validate-ui-messages)
- [Experimental_Sandbox](/v7/docs/reference/ai-sdk-core/sandbox)
- [createProviderRegistry](/v7/docs/reference/ai-sdk-core/provider-registry)
- [customProvider](/v7/docs/reference/ai-sdk-core/custom-provider)
- [cosineSimilarity](/v7/docs/reference/ai-sdk-core/cosine-similarity)
- [wrapLanguageModel](/v7/docs/reference/ai-sdk-core/wrap-language-model)
- [wrapImageModel](/v7/docs/reference/ai-sdk-core/wrap-image-model)
- [LanguageModelV4Middleware](/v7/docs/reference/ai-sdk-core/language-model-v2-middleware)
- [extractReasoningMiddleware](/v7/docs/reference/ai-sdk-core/extract-reasoning-middleware)
- [simulateStreamingMiddleware](/v7/docs/reference/ai-sdk-core/simulate-streaming-middleware)
- [defaultSettingsMiddleware](/v7/docs/reference/ai-sdk-core/default-settings-middleware)
- [addToolInputExamplesMiddleware](/v7/docs/reference/ai-sdk-core/add-tool-input-examples-middleware)
- [extractJsonMiddleware](/v7/docs/reference/ai-sdk-core/extract-json-middleware)
- [isStepCount](/v7/docs/reference/ai-sdk-core/is-step-count)
- [hasToolCall](/v7/docs/reference/ai-sdk-core/has-tool-call)
- [isLoopFinished](/v7/docs/reference/ai-sdk-core/loop-finished)
- [simulateReadableStream](/v7/docs/reference/ai-sdk-core/simulate-readable-stream)
- [smoothStream](/v7/docs/reference/ai-sdk-core/smooth-stream)
- [generateId](/v7/docs/reference/ai-sdk-core/generate-id)
- [createIdGenerator](/v7/docs/reference/ai-sdk-core/create-id-generator)
- [DefaultGeneratedFile](/v7/docs/reference/ai-sdk-core/default-generated-file)


[Full Sitemap](/sitemap.md)