devlooped · kzu · Jul 7, 2025 · Jul 7, 2025
diff --git a/readme.md b/readme.md
@@ -62,6 +62,25 @@ var options = new ChatOptions
 var response = await grok.GetResponseAsync(messages, options);
 ```
 
+We also provide an OpenAI-compatible `WebSearchTool` that can be used to restrict 
+the search to a specific country in a way that works with both Grok and OpenAI:
+
+```csharp
+var options = new ChatOptions
+{
+    Tools = [new WebSearchTool("AR")] // 👈 search in Argentina
+};
+```
+
+This is equivalent to the following when used with a Grok client:
+```csharp
+var options = new ChatOptions
+{
+    //                                           👇 search in Argentina
+    Tools = [new GrokSearchTool(GrokSearch.On) { Country = "AR" }] 
+};
+```
+
 ### Advanced Live Search
 
 To configure advanced live search options, beyond the `On|Auto|Off` settings 
@@ -127,9 +146,34 @@ var options = new ChatOptions
 };
 
 var response = await chat.GetResponseAsync(messages, options);
+```
+
+### Web Search
 
+Similar to the Grok client, we provide the `WebSearchTool` to enable search customization 
+in OpenAI too:
+
+```csharp
+var options = new ChatOptions
+{
+    //                          👇 search in Argentina, Bariloche region
+    Tools = [new WebSearchTool("AR")
+    {
+        Region = "Bariloche",   // 👈 Bariloche region
+        TimeZone = "America/Argentina/Buenos_Aires", // 👈 IANA timezone
+        ContextSize = WebSearchContextSize.High      // 👈 high search context size
+    }]
+};
 ```
 
+> [!NOTE]
+> This enables all features supported by the [Web search](https://platform.openai.com/docs/guides/tools-web-search) 
+> feature in OpenAI.
+
+If advanced search settings are not needed, you can use the built-in M.E.AI `HostedWebSearchTool` 
+instead, which is a more generic tool and provides the basics out of the box.
+
+
 ## Observing Request/Response
 
 The underlying HTTP pipeline provided by the Azure SDK allows setting up 

diff --git a/src/AI.Tests/GrokTests.cs b/src/AI.Tests/GrokTests.cs
@@ -1,6 +1,8 @@
 using System.Text.Json.Nodes;
+using Devlooped.Extensions.AI.Grok;
 using Microsoft.Extensions.AI;
 using static ConfigurationExtensions;
+using OpenAIClientOptions = OpenAI.OpenAIClientOptions;
 
 namespace Devlooped.Extensions.AI;
 
@@ -51,7 +53,7 @@ public async Task GrokInvokesToolAndSearch()
         var requests = new List<JsonNode>();
         var responses = new List<JsonNode>();
 
-        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAI.OpenAIClientOptions
+        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAIClientOptions
                     .Observable(requests.Add, responses.Add)
                     .WriteTo(output))
             .AsBuilder()
@@ -105,7 +107,7 @@ public async Task GrokInvokesHostedSearchTool()
         var requests = new List<JsonNode>();
         var responses = new List<JsonNode>();
 
-        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAI.OpenAIClientOptions
+        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAIClientOptions
             .Observable(requests.Add, responses.Add)
             .WriteTo(output));
 
@@ -185,7 +187,7 @@ public async Task GrokInvokesSpecificSearchUrl()
         var requests = new List<JsonNode>();
         var responses = new List<JsonNode>();
 
-        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAI.OpenAIClientOptions
+        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAIClientOptions
             .Observable(requests.Add, responses.Add)
             .WriteTo(output));
 

diff --git a/src/AI.Tests/OpenAITests.cs b/src/AI.Tests/OpenAITests.cs
@@ -1,6 +1,8 @@
 using System.Text.Json.Nodes;
+using Devlooped.Extensions.AI.OpenAI;
 using Microsoft.Extensions.AI;
 using OpenAI;
+using OpenAI.Responses;
 using static ConfigurationExtensions;
 
 namespace Devlooped.Extensions.AI;
@@ -66,4 +68,56 @@ public async Task OpenAIThinks()
             Assert.Equal("medium", search["effort"]?.GetValue<string>());
         });
     }
+
+    [SecretsFact("OPENAI_API_KEY")]
+    public async Task WebSearchCountryHighContext()
+    {
+        var messages = new Chat()
+        {
+            { "system", "Sos un asistente del Cerro Catedral, usas la funcionalidad de Live Search en el sitio oficial." },
+            { "system", $"Hoy es {DateTime.Now.ToString("o")}." },
+            { "system",
+                """
+                Web search sources: 
+                https://catedralaltapatagonia.com/parte-de-nieve/
+                https://catedralaltapatagonia.com/tarifas/
+                https://catedralaltapatagonia.com/
+
+                DO NOT USE https://partediario.catedralaltapatagonia.com/partediario for web search, it's **OBSOLETE**.
+                """},
+            { "user", "Cuanto cuesta el pase diario en el Catedral hoy?" },
+        };
+
+        var requests = new List<JsonNode>();
+        var responses = new List<JsonNode>();
+
+        var chat = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
+            OpenAIClientOptions.Observable(requests.Add, responses.Add).WriteTo(output));
+
+        var options = new ChatOptions
+        {
+            Tools = [new WebSearchTool("AR")
+            {
+                Region = "Bariloche",
+                TimeZone = "America/Argentina/Buenos_Aires",
+                ContextSize = WebSearchContextSize.High
+            }]
+        };
+
+        var response = await chat.GetResponseAsync(messages, options);
+        var text = response.Text;
+
+        var raw = Assert.IsType<OpenAIResponse>(response.RawRepresentation);
+        Assert.NotEmpty(raw.OutputItems.OfType<WebSearchCallResponseItem>());
+
+        var assistant = raw.OutputItems.OfType<MessageResponseItem>().Where(x => x.Role == MessageRole.Assistant).FirstOrDefault();
+        Assert.NotNull(assistant);
+
+        var content = Assert.Single(assistant.Content);
+        Assert.NotEmpty(content.OutputTextAnnotations);
+        Assert.Contains(content.OutputTextAnnotations,
+            x => x.Kind == ResponseMessageAnnotationKind.UriCitation &&
+                x.UriCitationUri.StartsWith("https://catedralaltapatagonia.com/tarifas/"));
+
+    }
 }
diff --git a/src/AI.Tests/RetrievalTests.cs b/src/AI.Tests/RetrievalTests.cs
@@ -11,11 +11,11 @@ public class RetrievalTests(ITestOutputHelper output)
     [InlineData("gpt-4.1-nano", "What's the battery life in an iPhone 15?", true)]
     public async Task CanRetrieveContent(string model, string question, bool empty = false)
     {
-        var client = new OpenAI.OpenAIClient(Configuration["OPENAI_API_KEY"]);
+        var client = new global::OpenAI.OpenAIClient(Configuration["OPENAI_API_KEY"]);
         var store = client.GetVectorStoreClient().CreateVectorStore(true);
         try
         {
-            var file = client.GetOpenAIFileClient().UploadFile("Content/LNS0004592.md", OpenAI.Files.FileUploadPurpose.Assistants);
+            var file = client.GetOpenAIFileClient().UploadFile("Content/LNS0004592.md", global::OpenAI.Files.FileUploadPurpose.Assistants);
             try
             {
                 client.GetVectorStoreClient().AddFileToVectorStore(store.VectorStoreId, file.Value.Id, true);

diff --git a/src/AI.Tests/ToolsTests.cs b/src/AI.Tests/ToolsTests.cs
@@ -1,4 +1,5 @@
 using System.ComponentModel;
+using Devlooped.Extensions.AI.OpenAI;
 using Microsoft.Extensions.AI;
 using static ConfigurationExtensions;
 
@@ -18,7 +19,7 @@ public async Task RunToolResult()
         };
 
         var client = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
-            OpenAI.OpenAIClientOptions.WriteTo(output))
+            global::OpenAI.OpenAIClientOptions.WriteTo(output))
             .AsBuilder()
             .UseFunctionInvocation()
             .Build();
@@ -50,7 +51,7 @@ public async Task RunToolTerminateResult()
         };
 
         var client = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
-            OpenAI.OpenAIClientOptions.WriteTo(output))
+            global::OpenAI.OpenAIClientOptions.WriteTo(output))
             .AsBuilder()
             .UseFunctionInvocation()
             .Build();
@@ -82,7 +83,7 @@ public async Task RunToolExceptionOutcome()
         };
 
         var client = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
-            OpenAI.OpenAIClientOptions.WriteTo(output))
+            global::OpenAI.OpenAIClientOptions.WriteTo(output))
             .AsBuilder()
             .UseFunctionInvocation()
             .Build();

diff --git a/src/AI/Grok/GrokChatClient.cs b/src/AI/Grok/GrokChatClient.cs
@@ -7,7 +7,7 @@
 using Microsoft.Extensions.AI;
 using OpenAI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// An <see cref="IChatClient"/> implementation for Grok.
@@ -64,6 +64,14 @@ IChatClient GetChatClient(string modelId) => clients.GetOrAdd(modelId, model
                     Mode = search.Value
                 };
             }
+            else if (tool is null && options.Tools?.OfType<WebSearchTool>().FirstOrDefault() is { } web)
+            {
+                searchOptions = new GrokChatWebSearchOptions
+                {
+                    Mode = GrokSearch.Auto,
+                    Sources = [new GrokWebSource { Country = web.Country }]
+                };
+            }
             else if (tool is null && options.Tools?.OfType<HostedWebSearchTool>().FirstOrDefault() is not null)
             {
                 searchOptions = new GrokChatWebSearchOptions
@@ -92,9 +100,9 @@ IChatClient GetChatClient(string modelId) => clients.GetOrAdd(modelId, model
             {
                 result.ReasoningEffortLevel = grok.ReasoningEffort switch
                 {
-                    ReasoningEffort.High => OpenAI.Chat.ChatReasoningEffortLevel.High,
+                    ReasoningEffort.High => global::OpenAI.Chat.ChatReasoningEffortLevel.High,
                     // Grok does not support Medium, so we map it to Low too
-                    _ => OpenAI.Chat.ChatReasoningEffortLevel.Low,
+                    _ => global::OpenAI.Chat.ChatReasoningEffortLevel.Low,
                 };
             }
 
@@ -111,7 +119,7 @@ void IDisposable.Dispose() { }
     // Allows creating the base OpenAIClient with a pre-created pipeline.
     class PipelineClient(ClientPipeline pipeline, OpenAIClientOptions options) : OpenAIClient(pipeline, options) { }
 
-    class GrokChatWebSearchOptions : OpenAI.Chat.ChatWebSearchOptions
+    class GrokChatWebSearchOptions : global::OpenAI.Chat.ChatWebSearchOptions
     {
         public GrokSearch Mode { get; set; } = GrokSearch.Auto;
         public DateOnly? FromDate { get; set; }
@@ -166,7 +174,7 @@ class LowercaseNamingPolicy : JsonNamingPolicy
         }
     }
 
-    class GrokCompletionOptions : OpenAI.Chat.ChatCompletionOptions
+    class GrokCompletionOptions : global::OpenAI.Chat.ChatCompletionOptions
     {
         protected override void JsonModelWriteCore(Utf8JsonWriter writer, ModelReaderWriterOptions? options)
         {

diff --git a/src/AI/Grok/GrokChatOptions.cs b/src/AI/Grok/GrokChatOptions.cs
@@ -1,6 +1,6 @@
 using Microsoft.Extensions.AI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// Grok-specific chat options that extend the base <see cref="ChatOptions"/>

diff --git a/src/AI/Grok/GrokClient.cs b/src/AI/Grok/GrokClient.cs
@@ -4,7 +4,7 @@
 using Microsoft.Extensions.AI;
 using OpenAI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// Provides an OpenAI compability client for Grok. It's recommended you 
@@ -26,7 +26,7 @@ public class GrokClient(string apiKey, OpenAIClientOptions? options = null)
     /// Returns an adapter that surfaces an <see cref="IChatClient"/> interface that 
     /// can be used directly in the <see cref="ChatClientBuilder"/> pipeline builder.
     /// </summary>
-    public override OpenAI.Chat.ChatClient GetChatClient(string model) => new GrokChatClientAdapter(this, model);
+    public override global::OpenAI.Chat.ChatClient GetChatClient(string model) => new GrokChatClientAdapter(this, model);
 
     static OpenAIClientOptions EnsureEndpoint(OpenAIClientOptions? options)
     {
@@ -39,7 +39,7 @@ static OpenAIClientOptions EnsureEndpoint(OpenAIClientOptions? options)
     // OpenAI in MEAI docs. Most typical case would be to just create an <see cref="GrokChatClient"/> directly.
     // This throws on any non-IChatClient invoked methods in the AsIChatClient adapter, and 
     // forwards the IChatClient methods to the GrokChatClient implementation which is cached per client.
-    class GrokChatClientAdapter(GrokClient client, string model) : OpenAI.Chat.ChatClient, IChatClient
+    class GrokChatClientAdapter(GrokClient client, string model) : global::OpenAI.Chat.ChatClient, IChatClient
     {
         void IDisposable.Dispose() { }
 
@@ -60,36 +60,36 @@ IAsyncEnumerable<ChatResponseUpdate> IChatClient.GetStreamingResponseAsync(IEnum
             => client.GetChatClientImpl(options?.ModelId ?? model).GetStreamingResponseAsync(messages, options, cancellation);
 
         // These are the only two methods actually invoked by the AsIChatClient adapter from M.E.AI.OpenAI
-        public override Task<ClientResult<OpenAI.Chat.ChatCompletion>> CompleteChatAsync(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override Task<ClientResult<global::OpenAI.Chat.ChatCompletion>> CompleteChatAsync(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)} instead of invoking {nameof(OpenAIClientExtensions.AsIChatClient)} on this instance.");
 
-        public override AsyncCollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override AsyncCollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)} instead of invoking {nameof(OpenAIClientExtensions.AsIChatClient)} on this instance.");
 
         #region Unsupported
 
         public override ClientResult CompleteChat(BinaryContent? content, RequestOptions? options = null)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override ClientResult<OpenAI.Chat.ChatCompletion> CompleteChat(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override ClientResult<global::OpenAI.Chat.ChatCompletion> CompleteChat(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override ClientResult<OpenAI.Chat.ChatCompletion> CompleteChat(params OpenAI.Chat.ChatMessage[] messages)
+        public override ClientResult<global::OpenAI.Chat.ChatCompletion> CompleteChat(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
         public override Task<ClientResult> CompleteChatAsync(BinaryContent? content, RequestOptions? options = null)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override Task<ClientResult<OpenAI.Chat.ChatCompletion>> CompleteChatAsync(params OpenAI.Chat.ChatMessage[] messages)
+        public override Task<ClientResult<global::OpenAI.Chat.ChatCompletion>> CompleteChatAsync(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override CollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override CollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override CollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(params OpenAI.Chat.ChatMessage[] messages)
+        public override CollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override AsyncCollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(params OpenAI.Chat.ChatMessage[] messages)
+        public override AsyncCollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
         #endregion

diff --git a/src/AI/Grok/GrokSearchTool.cs b/src/AI/Grok/GrokSearchTool.cs
@@ -1,7 +1,7 @@
 using System.Text.Json.Serialization;
 using Microsoft.Extensions.AI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// Enables or disables Grok's live search capabilities.

diff --git a/src/AI/OpenAI/OpenAIChatClient.cs b/src/AI/OpenAI/OpenAIChatClient.cs
@@ -5,7 +5,7 @@
 using OpenAI;
 using OpenAI.Responses;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.OpenAI;
 
 /// <summary>
 /// An <see cref="IChatClient"/> implementation for OpenAI.