Skip to content

Add proper readme to Grok package #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kzu merged 1 commit into from
Dec 6, 2025
Merged

Add proper readme to Grok package #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
343 changes: 175 additions & 168 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -322,174 +322,6 @@ var grok = app.Services.GetRequiredKeyedService<IChatClient>("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<CodeInterpreterToolResultContent>()
.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:
Expand Down Expand Up @@ -695,6 +527,181 @@ IChatClient client = new GrokChatClient(Environment.GetEnvironmentVariable("XAI_
```
<!-- #extensions -->

## Grok
<!-- #grok-title -->
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");
```
<!-- #grok-title -->
<!-- #grok -->
### 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<CodeInterpreterToolResultContent>()
.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).
<!-- #grok -->

<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
# Sponsors

Expand Down
9 changes: 9 additions & 0 deletions src/Extensions.Grok/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)

<!-- include ../../readme.md#grok-title -->
<!-- include https://github.com/devlooped/.github/raw/main/osmf.md -->
<!-- include ../../readme.md#grok -->
<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
<!-- exclude -->
Loading