diff --git a/readme.md b/readme.md index 52fd5e6..4fabec2 100644 --- a/readme.md +++ b/readme.md @@ -322,174 +322,6 @@ var grok = app.Services.GetRequiredKeyedService("Grok"); Changing the `appsettings.json` file will automatically update the client configuration without restarting the application. - -## Grok - -Full support for Grok new [agentic tools](https://docs.x.ai/docs/guides/tools/overview): - -### Web Search - -```csharp -var messages = new Chat() -{ - { "system", "You are an AI assistant that knows how to search the web." }, - { "user", "What's Tesla stock worth today? Search X and the news for latest info." }, -}; - -var grok = new GrokClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!).AsIChatClient("grok-4.1-fast"); - -var options = new ChatOptions -{ - Tools = [new HostedWebSearchTool()] // 👈 compatible with OpenAI -}; - -var response = await grok.GetResponseAsync(messages, options); -``` - -In addition to basic web search as shown above, Grok supports more -[advanced search](https://docs.x.ai/docs/guides/tools/search-tools) scenarios, -which can be opted-in by using Grok-specific types: - -```csharp -var grok = new GrokChatClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!).AsIChatClient("grok-4.1-fast"); -var response = await grok.GetResponseAsync( - "What are the latest product news by Tesla?", - new ChatOptions - { - Tools = [new GrokSearchTool() - { - AllowedDomains = [ "ir.tesla.com" ] - }] - }); -``` - -You can alternatively set `ExcludedDomains` instead, and enable image -understanding with `EnableImageUndestanding`. Learn more about these filters -at [web search parameters](https://docs.x.ai/docs/guides/tools/search-tools#web-search-parameters). - -### X Search - -In addition to web search, Grok also supports searching on X (formerly Twitter): - -```csharp -var response = await grok.GetResponseAsync( - "What's the latest on Optimus?", - new ChatOptions - { - Tools = [new GrokXSearchTool - { - // AllowedHandles = [...], - // ExcludedHandles = [...], - // EnableImageUnderstanding = true, - // EnableVideoUnderstanding = true, - // FromDate = ..., - // ToDate = ..., - }] - }); -``` - -Learn more about available filters at [X search parameters](https://docs.x.ai/docs/guides/tools/search-tools#x-search-parameters). - -You can combine both web and X search in the same request by adding both tools. - -### Code Execution - -The code execution tool enables Grok to write and execute Python code in real-time, -dramatically expanding its capabilities beyond text generation. This powerful feature -allows Grok to perform precise calculations, complex data analysis, statistical -computations, and solve mathematical problems that would be impossible through text alone. - -This is Grok's equivalent of the OpenAI code interpreter, and is configured the same way: - -```csharp -var grok = new GrokClient(Configuration["XAI_API_KEY"]!).AsIChatClient("grok-4-fast"); -var response = await grok.GetResponseAsync( - "Calculate the compound interest for $10,000 at 5% annually for 10 years", - new ChatOptions - { - Tools = [new HostedCodeInterpreterTool()] - }); - -var text = response.Text; -Assert.Contains("$6,288.95", text); -``` - -If you want to access the output from the code execution, you can add that as an -include in the options: - -```csharp -var grok = new GrokClient(Configuration["XAI_API_KEY"]!).AsIChatClient("grok-4-fast"); -var options = new GrokChatOptions -{ - Include = { IncludeOption.CodeExecutionCallOutput }, - Tools = [new HostedCodeInterpreterTool()] -}; - -var response = await grok.GetResponseAsync( - "Calculate the compound interest for $10,000 at 5% annually for 10 years", - options); - -var content = response.Messages - .SelectMany(x => x.Contents) - .OfType() - .First(); - -foreach (AIContent output in content.Outputs) - // process outputs from code interpreter -``` - -Learn more about the [code execution tool](https://docs.x.ai/docs/guides/tools/code-execution-tool). - -### Collection Search - -If you maintain a [collection](https://docs.x.ai/docs/key-information/collections), -Grok can perform semantic search on it: - -```csharp -var options = new ChatOptions -{ - Tools = [new HostedFileSearchTool { - Inputs = [new HostedVectorStoreContent("[collection_id]")] - }] -}; -``` - -Learn more about [collection search](https://docs.x.ai/docs/guides/tools/collections-search-tool). - -### Remote MCP - -Remote MCP Tools allow Grok to connect to external MCP (Model Context Protocol) servers. -This example sets up the GitHub MCP server so queries about releases (limited specifically -in this case): - -```csharp -var options = new ChatOptions -{ - Tools = [new HostedMcpServerTool("GitHub", "https://api.githubcopilot.com/mcp/") { - AuthorizationToken = Configuration["GITHUB_TOKEN"]!, - AllowedTools = ["list_releases"], - }] -}; -``` - -Just like with code execution, you can opt-in to surfacing the MCP outputs in -the response: - -```csharp -var options = new GrokChatOptions -{ - // Exposes McpServerToolResultContent in responses - Include = { IncludeOption.McpCallOutput }, - Tools = [new HostedMcpServerTool("GitHub", "https://api.githubcopilot.com/mcp/") { - AuthorizationToken = Configuration["GITHUB_TOKEN"]!, - AllowedTools = ["list_releases"], - }] -}; - -``` - -Learn more about [Remote MCP tools](https://docs.x.ai/docs/guides/tools/remote-mcp-tools). - ## OpenAI The support for OpenAI chat clients provided in [Microsoft.Extensions.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) fall short in some scenarios: @@ -695,6 +527,181 @@ IChatClient client = new GrokChatClient(Environment.GetEnvironmentVariable("XAI_ ``` +## Grok + +Microsoft.Extensions.AI `IChatClient` for Grok with full support for all +[agentic tools](https://docs.x.ai/docs/guides/tools/overview): + +```csharp +var grok = new GrokClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!) + .AsIChatClient("grok-4.1-fast"); +``` + + +### Web Search + +```csharp +var messages = new Chat() +{ + { "system", "You are an AI assistant that knows how to search the web." }, + { "user", "What's Tesla stock worth today? Search X and the news for latest info." }, +}; + +var grok = new GrokClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!).AsIChatClient("grok-4.1-fast"); + +var options = new ChatOptions +{ + Tools = [new HostedWebSearchTool()] // 👈 compatible with OpenAI +}; + +var response = await grok.GetResponseAsync(messages, options); +``` + +In addition to basic web search as shown above, Grok supports more +[advanced search](https://docs.x.ai/docs/guides/tools/search-tools) scenarios, +which can be opted-in by using Grok-specific types: + +```csharp +var grok = new GrokChatClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!).AsIChatClient("grok-4.1-fast"); +var response = await grok.GetResponseAsync( + "What are the latest product news by Tesla?", + new ChatOptions + { + Tools = [new GrokSearchTool() + { + AllowedDomains = [ "ir.tesla.com" ] + }] + }); +``` + +You can alternatively set `ExcludedDomains` instead, and enable image +understanding with `EnableImageUndestanding`. Learn more about these filters +at [web search parameters](https://docs.x.ai/docs/guides/tools/search-tools#web-search-parameters). + +### X Search + +In addition to web search, Grok also supports searching on X (formerly Twitter): + +```csharp +var response = await grok.GetResponseAsync( + "What's the latest on Optimus?", + new ChatOptions + { + Tools = [new GrokXSearchTool + { + // AllowedHandles = [...], + // ExcludedHandles = [...], + // EnableImageUnderstanding = true, + // EnableVideoUnderstanding = true, + // FromDate = ..., + // ToDate = ..., + }] + }); +``` + +Learn more about available filters at [X search parameters](https://docs.x.ai/docs/guides/tools/search-tools#x-search-parameters). + +You can combine both web and X search in the same request by adding both tools. + +### Code Execution + +The code execution tool enables Grok to write and execute Python code in real-time, +dramatically expanding its capabilities beyond text generation. This powerful feature +allows Grok to perform precise calculations, complex data analysis, statistical +computations, and solve mathematical problems that would be impossible through text alone. + +This is Grok's equivalent of the OpenAI code interpreter, and is configured the same way: + +```csharp +var grok = new GrokClient(Configuration["XAI_API_KEY"]!).AsIChatClient("grok-4-fast"); +var response = await grok.GetResponseAsync( + "Calculate the compound interest for $10,000 at 5% annually for 10 years", + new ChatOptions + { + Tools = [new HostedCodeInterpreterTool()] + }); + +var text = response.Text; +Assert.Contains("$6,288.95", text); +``` + +If you want to access the output from the code execution, you can add that as an +include in the options: + +```csharp +var grok = new GrokClient(Configuration["XAI_API_KEY"]!).AsIChatClient("grok-4-fast"); +var options = new GrokChatOptions +{ + Include = { IncludeOption.CodeExecutionCallOutput }, + Tools = [new HostedCodeInterpreterTool()] +}; + +var response = await grok.GetResponseAsync( + "Calculate the compound interest for $10,000 at 5% annually for 10 years", + options); + +var content = response.Messages + .SelectMany(x => x.Contents) + .OfType() + .First(); + +foreach (AIContent output in content.Outputs) + // process outputs from code interpreter +``` + +Learn more about the [code execution tool](https://docs.x.ai/docs/guides/tools/code-execution-tool). + +### Collection Search + +If you maintain a [collection](https://docs.x.ai/docs/key-information/collections), +Grok can perform semantic search on it: + +```csharp +var options = new ChatOptions +{ + Tools = [new HostedFileSearchTool { + Inputs = [new HostedVectorStoreContent("[collection_id]")] + }] +}; +``` + +Learn more about [collection search](https://docs.x.ai/docs/guides/tools/collections-search-tool). + +### Remote MCP + +Remote MCP Tools allow Grok to connect to external MCP (Model Context Protocol) servers. +This example sets up the GitHub MCP server so queries about releases (limited specifically +in this case): + +```csharp +var options = new ChatOptions +{ + Tools = [new HostedMcpServerTool("GitHub", "https://api.githubcopilot.com/mcp/") { + AuthorizationToken = Configuration["GITHUB_TOKEN"]!, + AllowedTools = ["list_releases"], + }] +}; +``` + +Just like with code execution, you can opt-in to surfacing the MCP outputs in +the response: + +```csharp +var options = new GrokChatOptions +{ + // Exposes McpServerToolResultContent in responses + Include = { IncludeOption.McpCallOutput }, + Tools = [new HostedMcpServerTool("GitHub", "https://api.githubcopilot.com/mcp/") { + AuthorizationToken = Configuration["GITHUB_TOKEN"]!, + AllowedTools = ["list_releases"], + }] +}; + +``` + +Learn more about [Remote MCP tools](https://docs.x.ai/docs/guides/tools/remote-mcp-tools). + + # Sponsors diff --git a/src/Extensions.Grok/readme.md b/src/Extensions.Grok/readme.md new file mode 100644 index 0000000..864d2a4 --- /dev/null +++ b/src/Extensions.Grok/readme.md @@ -0,0 +1,9 @@ +[![EULA](https://img.shields.io/badge/EULA-OSMF-blue?labelColor=black&color=C9FF30)](osmfeula.txt) +[![OSS](https://img.shields.io/github/license/devlooped/oss.svg?color=blue)](license.txt) +[![GitHub](https://img.shields.io/badge/-source-181717.svg?logo=GitHub)](https://github.com/devlooped/AI) + + + + + + \ No newline at end of file