Add web search tool call content

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseExtensions.cs

@@ -225,6 +225,61 @@ private static void CoalesceImageResultContent(IList<AIContent> contents)
         }
     }
 
+    /// <summary>
+    /// Coalesces web search tool call content elements in the provided list of <see cref="AIContent"/> items.
+    /// Unlike other content coalescing methods, this will coalesce non-sequential items based on their CallId property,
+    /// merging data from all items with the same CallId into the first occurrence.
+    /// </summary>
+    private static void CoalesceWebSearchToolCallContent(IList<AIContent> contents)
+    {
+        Dictionary<string, int>? webSearchCallIndexById = null;
+        bool hasRemovals = false;
+
+        for (int i = 0; i < contents.Count; i++)
+        {
+            if (contents[i] is WebSearchToolCallContent webSearchCall && !string.IsNullOrEmpty(webSearchCall.CallId))
+            {
+                webSearchCallIndexById ??= new(StringComparer.Ordinal);
+
+                if (webSearchCallIndexById.TryGetValue(webSearchCall.CallId!, out int existingIndex))
+                {
+                    // Merge data from the new item into the existing one.
+                    var existing = (WebSearchToolCallContent)contents[existingIndex];
+
+                    if (webSearchCall.Queries is { Count: > 0 })
+                    {
+                        if (existing.Queries is null)
+                        {
+                            existing.Queries = webSearchCall.Queries;
+                        }
+                        else
+                        {
+                            foreach (var query in webSearchCall.Queries)
+                            {
+                                existing.Queries.Add(query);
+                            }
+                        }
+                    }
+
+                    existing.RawRepresentation ??= webSearchCall.RawRepresentation;
+                    existing.AdditionalProperties ??= webSearchCall.AdditionalProperties;
+
+                    contents[i] = null!;
+                    hasRemovals = true;
+                }
+                else
+                {
+                    webSearchCallIndexById[webSearchCall.CallId!] = i;
+                }
+            }
+        }
+
+        if (hasRemovals)
+        {
+            RemoveNullContents(contents);
+        }
+    }
+
     /// <summary>Coalesces sequential <see cref="AIContent"/> content elements.</summary>
     internal static void CoalesceContent(IList<AIContent> contents)
     {
@@ -262,6 +317,8 @@ internal static void CoalesceContent(IList<AIContent> contents)
 
         CoalesceImageResultContent(contents);
 
+        CoalesceWebSearchToolCallContent(contents);
+
         Coalesce<DataContent>(
             contents,
             mergeSingle: false,

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AIContent.cs

@@ -32,6 +32,8 @@ namespace Microsoft.Extensions.AI;
 // [JsonDerivedType(typeof(McpServerToolApprovalResponseContent), typeDiscriminator: "mcpServerToolApprovalResponse")]
 // [JsonDerivedType(typeof(CodeInterpreterToolCallContent), typeDiscriminator: "codeInterpreterToolCall")]
 // [JsonDerivedType(typeof(CodeInterpreterToolResultContent), typeDiscriminator: "codeInterpreterToolResult")]
+// [JsonDerivedType(typeof(WebSearchToolCallContent), typeDiscriminator: "webSearchToolCall")]
+// [JsonDerivedType(typeof(WebSearchToolResultContent), typeDiscriminator: "webSearchToolResult")]
 
 public class AIContent
 {

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/WebSearchResult.cs

@@ -0,0 +1,40 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents an individual web search result.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AIWebSearch, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class WebSearchResult
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebSearchResult"/> class.
+    /// </summary>
+    public WebSearchResult()
+    {
+    }
+
+    /// <summary>
+    /// Gets or sets the title of the web page.
+    /// </summary>
+    public string? Title { get; set; }
+
+    /// <summary>
+    /// Gets or sets the URL of the web page.
+    /// </summary>
+    public Uri? Url { get; set; }
+
+    /// <summary>
+    /// Gets or sets a text snippet or excerpt from the web page.
+    /// </summary>
+    public string? Snippet { get; set; }
+
+    /// <summary>Gets or sets additional properties for the result.</summary>
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/WebSearchToolCallContent.cs

@@ -0,0 +1,36 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a web search tool call invocation by a hosted service.
+/// </summary>
+/// <remarks>
+/// This content type represents when a hosted AI service invokes a web search tool.
+/// It is informational only and represents the call itself, not the result.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIWebSearch, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class WebSearchToolCallContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebSearchToolCallContent"/> class.
+    /// </summary>
+    public WebSearchToolCallContent()
+    {
+    }
+
+    /// <summary>
+    /// Gets or sets the tool call ID.
+    /// </summary>
+    public string? CallId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the search queries issued by the service.
+    /// </summary>
+    public IList<string>? Queries { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/WebSearchToolResultContent.cs

@@ -0,0 +1,40 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents the result of a web search tool invocation by a hosted service.
+/// </summary>
+/// <remarks>
+/// This content type represents the results found by a hosted AI service's web search tool.
+/// The results contain a list of <see cref="WebSearchResult"/> items, each describing a web page
+/// found during the search.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIWebSearch, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class WebSearchToolResultContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebSearchToolResultContent"/> class.
+    /// </summary>
+    public WebSearchToolResultContent()
+    {
+    }
+
+    /// <summary>
+    /// Gets or sets the tool call ID that this result corresponds to.
+    /// </summary>
+    public string? CallId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the web search results.
+    /// </summary>
+    /// <remarks>
+    /// Each item represents a web page found during the search.
+    /// </remarks>
+    public IList<WebSearchResult>? Results { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Defaults.cs

@@ -59,6 +59,8 @@ private static JsonSerializerOptions CreateDefaultOptions()
         AddAIContentType(options, typeof(McpServerToolApprovalResponseContent), typeDiscriminatorId: "mcpServerToolApprovalResponse", checkBuiltIn: false);
         AddAIContentType(options, typeof(CodeInterpreterToolCallContent), typeDiscriminatorId: "codeInterpreterToolCall", checkBuiltIn: false);
         AddAIContentType(options, typeof(CodeInterpreterToolResultContent), typeDiscriminatorId: "codeInterpreterToolResult", checkBuiltIn: false);
+        AddAIContentType(options, typeof(WebSearchToolCallContent), typeDiscriminatorId: "webSearchToolCall", checkBuiltIn: false);
+        AddAIContentType(options, typeof(WebSearchToolResultContent), typeDiscriminatorId: "webSearchToolResult", checkBuiltIn: false);
         AddAIContentType(options, typeof(ImageGenerationToolCallContent), typeDiscriminatorId: "imageGenerationToolCall", checkBuiltIn: false);
         AddAIContentType(options, typeof(ImageGenerationToolResultContent), typeDiscriminatorId: "imageGenerationToolResult", checkBuiltIn: false);
 
@@ -135,6 +137,8 @@ private static JsonSerializerOptions CreateDefaultOptions()
     [JsonSerializable(typeof(McpServerToolApprovalResponseContent))]
     [JsonSerializable(typeof(CodeInterpreterToolCallContent))]
     [JsonSerializable(typeof(CodeInterpreterToolResultContent))]
+    [JsonSerializable(typeof(WebSearchToolCallContent))]
+    [JsonSerializable(typeof(WebSearchToolResultContent))]
     [JsonSerializable(typeof(ImageGenerationToolCallContent))]
     [JsonSerializable(typeof(ImageGenerationToolResultContent))]
     [JsonSerializable(typeof(ResponseContinuationToken))]

src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs

@@ -620,9 +620,15 @@
         {
             foreach (AITool tool in tools)
             {
-                if (tool is AIFunctionDeclaration af)
+                switch (tool)
                 {
-                    result.Tools.Add(ToOpenAIChatTool(af, options));
+                    case AIFunctionDeclaration af:
+                        result.Tools.Add(ToOpenAIChatTool(af, options));
+                        break;
+
+                    case HostedWebSearchTool:
+                        result.WebSearchOptions ??= new();
+                        break;
                 }
             }
 

src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIResponsesChatClient.cs

@@ -244,6 +244,26 @@ internal static IEnumerable<ChatMessage> ToChatMessages(IEnumerable<ResponseItem
                     AddImageGenerationContents(imageGenItem, options, message.Contents);
                     break;
 
+                case WebSearchCallResponseItem wscri:
+                    _ = wscri.Patch.TryGetValue("$.action.query"u8, out string? wsQuery);
+
+                    message.Contents.Add(new WebSearchToolCallContent
+                    {
+                        CallId = wscri.Id,
+                        Queries = wsQuery is not null ? [wsQuery] : null,
+
+                        // We purposefully do not set the RawRepresentation on the WebSearchToolCallContent, only on the WebSearchToolResultContent, to avoid
+                        // the same WebSearchCallResponseItem being included on two different AIContent instances. When these are roundtripped, we want only one
+                        // WebSearchCallResponseItem sent back for the pair.
+                    });
+
+                    message.Contents.Add(new WebSearchToolResultContent
+                    {
+                        CallId = wscri.Id,
+                        RawRepresentation = wscri,
+                    });
+                    break;
+
                 default:
                     message.Contents.Add(new() { RawRepresentation = outputItem });
                     break;
@@ -436,6 +456,14 @@ ChatResponseUpdate CreateUpdate(AIContent? content = null) =>
                     });
                     break;
 
+                case StreamingResponseWebSearchCallInProgressUpdate webSearchInProgressUpdate:
+                    yield return CreateUpdate(new WebSearchToolCallContent
+                    {
+                        CallId = webSearchInProgressUpdate.ItemId,
+                        RawRepresentation = webSearchInProgressUpdate,
+                    });
+                    break;
+
                 case StreamingResponseOutputItemDoneUpdate outputItemDoneUpdate:
                     switch (outputItemDoneUpdate.Item)
                     {
@@ -472,6 +500,24 @@ ChatResponseUpdate CreateUpdate(AIContent? content = null) =>
                             yield return CreateUpdate(CreateCodeInterpreterResultContent(cicri));
                             break;
 
+                        case WebSearchCallResponseItem wscri:
+                            // The WebSearchToolCallContent has already been yielded as part of in-progress updates.
+                            // Yield a second one here with queries populated, which coalescing will merge with the first.
+                            _ = wscri.Patch.TryGetValue("$.action.query"u8, out string? wsStreamQuery);
+                            yield return CreateUpdate(new WebSearchToolCallContent
+                            {
+                                CallId = wscri.Id,
+                                Queries = wsStreamQuery is not null ? [wsStreamQuery] : null,
+                            });
+
+                            // Also yield the WebSearchToolResultContent.
+                            yield return CreateUpdate(new WebSearchToolResultContent
+                            {
+                                CallId = wscri.Id,
+                                RawRepresentation = wscri,
+                            });
+                            break;
+
                         // MessageResponseItems will have already had their content yielded as part of delta updates.
                         // However, those deltas didn't yield annotations. If there are any annotations, yield them now.
                         case MessageResponseItem mri when mri.Content is { Count: > 0 } mriContent && mriContent.Any(c => c.OutputTextAnnotations is { Count: > 0 }):

src/Shared/DiagnosticIds/DiagnosticIds.cs

@@ -56,6 +56,7 @@ internal static class Experiments
         internal const string AIChatReduction = AIExperiments;
         internal const string AIResponseContinuations = AIExperiments;
         internal const string AICodeInterpreter = AIExperiments;
+        internal const string AIWebSearch = AIExperiments;
         internal const string AIRealTime = AIExperiments;
 
         // These diagnostic IDs are defined by the OpenAI package for its experimental APIs.