feat(provider/azure): Responses API web search preview is enabled (#10370)

## Background
Web Search Preview has become available on Microsoft Azure OpenAI.
We enabled the use of `web_search_preview` from `@ai-sdk/openai` within
`@ai-sdk/azure`.

[https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/web-search?view=foundry-classic](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/web-search?view=foundry-classic)

## Summary

Using Next.js, it is now possible to perform web searches with both
`useChat` and `streamText`.

* We enabled Azure’s webSearchPreview tool by routing through the OpenAI
internal implementation.
* In `doGenerate`, the Zod type definition for `url_citation` was
updated to support annotations.
* In `doStream`, there were some missing pieces when switching between
`web_search` and `web_search_preview`.
* add description `web_search_preview` in azure provider web page.


## Manual Verification
* Added verification for `web_search_preview` in Azure’s CI/CD tests.

`packages/azure/src/__fixtures__/azure-web-search-preview-tool.1.chunks.txt`
  `packages/azure/src/__fixtures__/azure-web-search-preview-tool.1.json`
* Added tests for `generateText` and `streamText` in `examples/ai-core`.
`generateText` correctly includes the `url_citation` annotation, while
`streamText` currently does not output it.
  This is expected to be resolved once PR #10253 is merged.

`examples/ai-core/src/generate-text/azure-responses-web-search-preview.ts'

`examples/ai-core/src/stream-text/azure-responses-web-search-preview.ts'

* Added a working Next.js example demonstrating web search in
`examples/next-openai`.
  `http://localhost:3000/test-azure-web-search-preview`
  `examples/next-openai/app/test-azure-web-search-preview/page.tsx`
<img width="908" height="1032" alt="image"
src="https://github.com/user-attachments/assets/b51bf4b8-ffb2-4106-9859-a3b017128aae"
/>


## Future Work

Since `streamText` does not currently output annotations, we need to
confirm that this is resolved once PR #10253 is merged.

## Related Issues

#10253

---------

Co-authored-by: tsuzaki430 <[email protected]>

Author: tsuzaki430

.changeset/small-balloons-eat.md

@@ -0,0 +1,6 @@
+---
+'@ai-sdk/openai': patch
+'@ai-sdk/azure': patch
+---
+
+Azure OpenAI enabled web-search-preview

content/providers/01-ai-sdk-providers/04-azure.mdx

@@ -340,6 +340,49 @@ The following OpenAI-specific metadata is returned:
   not supported when using 'azure.chat' or 'azure.completion'
 </Note>
 
+#### Web Search Tool
+
+The Azure OpenAI responses API supports web search(preview) through the `azure.tools.webSearchPreview` tool.
+
+```ts
+const result = await generateText({
+  model: azure('gpt-4.1-mini'),
+  prompt: 'What happened in San Francisco last week?',
+  tools: {
+    web_search_preview: azure.tools.webSearchPreview({
+      // optional configuration:
+      searchContextSize: 'low',
+      userLocation: {
+        type: 'approximate',
+        city: 'San Francisco',
+        region: 'California',
+      },
+    }),
+  },
+  // Force web search tool (optional):
+  toolChoice: { type: 'tool', toolName: 'web_search_preview' },
+});
+
+console.log(result.text);
+
+// URL sources directly from `results`
+const sources = result.sources;
+for (const source of sources) {
+  console.log('source:', source);
+}
+```
+
+<Note>
+  The tool must be named `web_search_preview` when using Azure OpenAI's web
+  search(preview) functionality. This name is required by Azure OpenAI's API
+  specification and cannot be customized.
+</Note>
+
+<Note>
+  The 'web_search_preview' tool is only supported with the default responses
+  API, and is not supported when using 'azure.chat' or 'azure.completion'
+</Note>
+
 #### File Search Tool
 
 The Azure OpenAI provider supports file search through the `azure.tools.fileSearch` tool.

examples/ai-core/src/generate-text/azure-responses-web-search-preview.ts

@@ -0,0 +1,45 @@
+import { azure } from '@ai-sdk/azure';
+import { generateText } from 'ai';
+import 'dotenv/config';
+
+/**
+ * prepare
+ * Please add parameters in your .env file for initialize Azure OpenAI..
+ * AZURE_RESOURCE_NAME="<your_resource_name>"
+ * AZURE_API_KEY="<your_api_key>"
+ */
+
+async function main() {
+  // Basic text generation
+  const basicResult = await generateText({
+    model: azure.responses('gpt-4.1-mini'),
+    prompt: 'Summarize three major news stories from today.',
+    tools: {
+      web_search_preview: azure.tools.webSearchPreview({
+        searchContextSize: 'low',
+      }),
+    },
+  });
+
+  console.log('\n=== Basic Text Generation ===');
+  console.log(basicResult.text);
+  console.log('\n=== Other Outputs ===');
+  console.dir(basicResult.toolCalls, { depth: Infinity });
+  console.dir(basicResult.toolResults, { depth: Infinity });
+  console.log('\n=== Web Search Preview Annotations ===');
+  for (const part of basicResult.content) {
+    if (part.type === 'text') {
+      const annotations = part.providerMetadata?.openai?.annotations;
+      if (annotations) {
+        console.dir(annotations);
+      }
+    }
+  }
+  for (const step of basicResult.steps) {
+    if (step.warnings) {
+      console.log(step.warnings);
+    }
+  }
+}
+
+main().catch(console.error);

examples/ai-core/src/stream-text/azure-responses-web-search-preview.ts

@@ -0,0 +1,57 @@
+import { azure } from '@ai-sdk/azure';
+import { streamText } from 'ai';
+import 'dotenv/config';
+
+/**
+ * prepare
+ * Please add parameters in your .env file for initialize Azure OpenAI..
+ * AZURE_RESOURCE_NAME="<your_resource_name>"
+ * AZURE_API_KEY="<your_api_key>"
+ */
+
+async function main() {
+  // Basic text generation
+  const result = streamText({
+    model: azure.responses('gpt-4.1-mini'), // use your own deployment
+    prompt: 'Summarize three major news stories from today.',
+    tools: {
+      web_search_preview: azure.tools.webSearchPreview({
+        searchContextSize: 'low',
+      }),
+    },
+  });
+
+  console.log('\n=== Basic Text Generation ===');
+  for await (const textPart of result.textStream) {
+    process.stdout.write(textPart);
+  }
+  console.log('\n=== Other Outputs ===');
+  console.log(await result.toolCalls);
+  console.log(await result.toolResults);
+  console.log('\n=== Web Search Preview Annotations ===');
+  for await (const part of result.fullStream) {
+    switch (part.type) {
+      case 'text-end':
+        {
+          const annotations = part.providerMetadata?.openai?.annotations;
+          if (annotations) {
+            console.dir(annotations);
+          }
+        }
+        break;
+
+      case 'source':
+        if (part.sourceType === 'url') {
+          console.log(`\n[source: ${part.url}]`);
+        }
+        break;
+
+      case 'error':
+        console.log('error');
+        console.error(part.error);
+        break;
+    }
+  }
+}
+
+main().catch(console.error);

examples/next-openai/app/api/chat-azure-web-search-preview/route.ts

@@ -0,0 +1,40 @@
+import { azure } from '@ai-sdk/azure';
+import {
+  convertToModelMessages,
+  InferUITools,
+  streamText,
+  ToolSet,
+  UIDataTypes,
+  UIMessage,
+} from 'ai';
+
+const tools = {
+  web_search_preview: azure.tools.webSearchPreview({}),
+} satisfies ToolSet;
+
+export type AzureWebSearchPreviewMessage = UIMessage<
+  never,
+  UIDataTypes,
+  InferUITools<typeof tools>
+>;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: AzureWebSearchPreviewMessage[] } =
+    await req.json();
+
+  const prompt = convertToModelMessages(messages);
+
+  const result = streamText({
+    model: azure.responses('gpt-4.1-mini'),
+    prompt,
+    tools: {
+      web_search_preview: azure.tools.webSearchPreview({
+        searchContextSize: 'low',
+      }),
+    },
+  });
+
+  return result.toUIMessageStreamResponse({
+    sendSources: true,
+  });
+}

examples/next-openai/app/test-azure-web-search-preview/page.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { Response } from '@/components/ai-elements/response';
+import ChatInput from '@/components/chat-input';
+import { ReasoningView } from '@/components/reasoning-view';
+import SourcesView from '@/components/sources-view';
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import { AzureWebSearchPreviewMessage } from '@/app/api/chat-azure-web-search-preview/route';
+import AzureWebSearchPreviewView from '@/components/tool/azure-web-search-preview-view';
+
+export default function TestOpenAIWebSearch() {
+  const { error, status, sendMessage, messages, regenerate } =
+    useChat<AzureWebSearchPreviewMessage>({
+      transport: new DefaultChatTransport({
+        api: '/api/chat-azure-web-search-preview',
+      }),
+      onError: error => {
+        console.error('Chat error:', error);
+      },
+    });
+
+  return (
+    <div className="flex flex-col py-24 mx-auto w-full max-w-md stretch">
+      <h1 className="mb-4 text-xl font-bold">
+        Azure OpenAI Web Search Preview
+      </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} />;
+              }
+              case 'tool-web_search_preview': {
+                return (
+                  <AzureWebSearchPreviewView invocation={part} key={index} />
+                );
+              }
+            }
+          })}
+
+          <SourcesView
+            sources={message.parts.filter(part => part.type === 'source-url')}
+          />
+        </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>
+  );
+}

examples/next-openai/components/tool/azure-web-search-preview-view.tsx

@@ -0,0 +1,96 @@
+import { azure } from '@ai-sdk/azure';
+import { UIToolInvocation } from 'ai';
+
+export default function AzureWebSearchPreviewView({
+  invocation,
+}: {
+  invocation: UIToolInvocation<ReturnType<typeof azure.tools.webSearchPreview>>;
+}) {
+  switch (invocation.state) {
+    case 'input-available': {
+      return (
+        <div className="flex flex-col gap-2 p-3 bg-blue-50 rounded border-l-4 border-blue-400 shadow">
+          <div className="flex items-center font-semibold text-blue-700">
+            <span className="inline-block mr-2 bg-blue-200 text-blue-900 rounded px-2 py-0.5 text-xs font-mono tracking-wider">
+              SEARCH
+            </span>
+            Searching the web...
+          </div>
+        </div>
+      );
+    }
+    case 'output-available': {
+      const output = invocation.output;
+
+      switch (output.action?.type) {
+        case 'search':
+          return (
+            <div className="flex flex-col gap-2 p-3 bg-blue-50 rounded border-l-4 border-blue-400 shadow">
+              <div className="flex items-center font-semibold text-blue-700">
+                <span className="inline-block mr-2 bg-blue-200 text-blue-900 rounded px-2 py-0.5 text-xs font-mono tracking-wider">
+                  SEARCH
+                </span>
+                Searched the web
+              </div>
+              <div className="pl-5 text-sm text-blue-800">
+                <span className="font-semibold">Query:</span>{' '}
+                <span className="inline-block bg-white border border-blue-100 rounded px-2 py-0.5 font-mono">
+                  {output.action.query}
+                </span>
+              </div>
+            </div>
+          );
+        case 'openPage':
+          return (
+            <div className="flex flex-col gap-2 p-3 bg-green-50 rounded border-l-4 border-green-500 shadow">
+              <div className="flex items-center font-semibold text-green-800">
+                <span className="inline-block mr-2 bg-green-200 text-green-900 rounded px-2 py-0.5 text-xs font-mono tracking-wider">
+                  OPEN PAGE
+                </span>
+                Opened a page
+              </div>
+              <div className="pl-5 text-sm text-green-900 break-all">
+                <span className="font-semibold">URL:</span>{' '}
+                <a
+                  href={output.action.url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="underline hover:text-green-700"
+                >
+                  {output.action.url}
+                </a>
+              </div>
+            </div>
+          );
+        case 'find':
+          return (
+            <div className="flex flex-col gap-2 p-3 bg-yellow-50 rounded border-l-4 border-yellow-500 shadow">
+              <div className="flex items-center font-semibold text-yellow-800">
+                <span className="inline-block mr-2 bg-yellow-200 text-yellow-900 rounded px-2 py-0.5 text-xs font-mono tracking-wider">
+                  FIND
+                </span>
+                Searched for pattern in page
+              </div>
+              <div className="pl-5 text-sm text-yellow-900">
+                <span className="font-semibold">Pattern:</span>{' '}
+                <span className="inline-block bg-white border border-yellow-100 rounded px-2 py-0.5 font-mono">
+                  {output.action.pattern}
+                </span>
+              </div>
+              <div className="pl-5 text-sm text-yellow-900 break-all">
+                <span className="font-semibold">In URL:</span>{' '}
+                <a
+                  href={output.action.url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="underline hover:text-yellow-700"
+                >
+                  {output.action.url}
+                </a>
+              </div>
+            </div>
+          );
+      }
+    }
+  }
+}